python-semver · tomschr · Sep 2, 2026 · Aug 28, 2026 · Sep 2, 2026 · Sep 2, 2026
diff --git a/changelog.d/pr476.feature.rst b/changelog.d/pr476.feature.rst
@@ -0,0 +1,3 @@
+Added optional ``[native]`` extra to accelerate parsing on CPython via the 
+``fast-semver-rs-backend`` package. The pure-Python parser remains the default; 
+the native backend is opt-in and only available on CPython.
diff --git a/docs/install.rst b/docs/install.rst
@@ -54,6 +54,27 @@ Then use the command :command:`uv` to install the package:
     uv pip install semver
 
 
+Optional Native Backend
+-----------------------
+
+The ``semver`` package provides an optional native backend that can accelerate version parsing on CPython.
+Install it with the ``[native]`` extra:
+
+.. code-block:: bash
+
+    pip3 install 'semver[native]'
+
+Or with :command:`uv`:
+
+.. code-block:: bash
+
+    uv pip install 'semver[native]'
+
+The native backend uses the ``fast-semver-rs-backend`` package, which is only available
+on CPython. On other Python implementations or when the extra is not installed,
+``semver`` automatically falls back to its pure-Python parser. No code changes are required.
+
+
 Linux Distributions
 -------------------
 

diff --git a/pyproject.toml b/pyproject.toml
@@ -55,6 +55,11 @@ Documentation = "https://python-semver.rtfd.io"
 Releases = "https://github.com/python-semver/python-semver/releases"
 "Bug Tracker" = "https://github.com/python-semver/python-semver/issues"
 
+[project.optional-dependencies]
+native = [
+  "fast-semver-rs-backend>=0.1.1; platform_python_implementation == 'CPython'",
+]
+
 
 [project.scripts]
 pysemver = "semver.cli:main"

diff --git a/src/semver/version.py b/src/semver/version.py
@@ -27,6 +27,11 @@
     VersionPart,
 )
 
+try:
+    from fast_semver_rs_backend import parse_parts as _native_parse_parts
+except ImportError:  # optional backend is deliberately absent on the default path
+    _native_parse_parts = None
+
 # These types are required here because of circular imports
 Comparable = Union["Version", Dict[str, VersionPart], Collection[VersionPart], str]
 Comparator = Callable[["Version", Comparable], bool]
@@ -662,6 +667,14 @@ def parse(
         elif not isinstance(version, String.__args__):  # type: ignore
             raise TypeError("not expecting type '%s'" % type(version))
 
+        if _native_parse_parts is not None and not optional_minor_and_patch:
+            try:
+                return cls(*_native_parse_parts(version))
+            except ValueError:
+                # The backend uses bounded Rust integers. Falling through keeps
+                # Python's arbitrary-size integer and exact error contracts.
+                pass
+
         if optional_minor_and_patch:
             match = cls._REGEX_OPTIONAL_MINOR_AND_PATCH.match(version)
         else:

diff --git a/tests/test_optional_native_backend.py b/tests/test_optional_native_backend.py
@@ -0,0 +1,26 @@
+from __future__ import annotations
+
+# selftest marker: keep for fork CI path filter
+
+
+import importlib.util
+
+import pytest
+
+from semver import Version
+from semver import version as version_module
+
+
+def test_optional_backend_is_available_without_changing_public_objects() -> None:
+    if importlib.util.find_spec("fast_semver_rs_backend") is None:
+        pytest.skip("optional backend is not installed")
+
+    assert version_module._native_parse_parts is not None
+    result = Version.parse("1.2.3-rc.1+build.4")
+    assert type(result) is Version
+    assert result.to_tuple() == (1, 2, 3, "rc.1", "build.4")
+
+
+def test_optional_backend_is_not_used_for_python_only_optional_parts() -> None:
+    result = Version.parse("7", optional_minor_and_patch=True)
+    assert result.to_tuple() == (7, 0, 0, None, None)
diff --git a/uv.lock b/uv.lock