Skip to content

Add optional native parser backend (minimal adapter) - #476

Merged
tomschr merged 6 commits into
python-semver:masterfrom
lowmiaq-gmail:codex/semver-native-adapter-20260828
Sep 2, 2026
Merged

tomschr merged 6 commits into
python-semver:masterfrom
lowmiaq-gmail:codex/semver-native-adapter-20260828

Conversation

@lowmiaq-gmail

Copy link
Copy Markdown
Contributor

Refs

Closes the next step agreed in #474 (Tom’s summary + my confirmation).

What this is

A minimal optional adapter so maintainers can review the actual maintenance footprint—no larger design commitment.

Default install stays pure Python. Opt-in only via:

pip install 'python-semver[native]'

which pulls fast-semver-rs-backend (CPython only; maintained in a separate repo under my account). If the backend is absent or declines a value, parsing falls through to the existing Python path.

Footprint (3 files)

File Change
pyproject.toml optional-dependencies native
src/semver/version.py optional import + call at parse boundary
tests/test_optional_native_backend.py skips when backend missing

Behavior notes

  • Pure-Python remains the default and fully functional alone.
  • Native path is not used for optional_minor_and_patch=True (Python-only contract).
  • Backend ValueError falls through so arbitrary-size ints / exact errors stay Python’s.
  • No Rust sources, wheel CI, or packaging work lands in this repository.

Maintenance boundary (as agreed in #474)

  • python-semver owns API/semantics + this thin hook.
  • Backend repo owns Rust, wheels, Trusted Publishing, and decoupled releases.

Happy to adjust the shape if you’d prefer a different footprint for this first look.

@tomschr

tomschr commented Sep 2, 2026

Copy link
Copy Markdown
Member

Thank you for your contribution! 👍 Looks like one step failed:

Install the project
Run uv sync --all-extras --group gh-action
  uv sync --all-extras --group gh-action
  shell: /usr/bin/bash -e {0}
  env:
    UV_PYTHON_INSTALL_DIR: /home/runner/work/_temp/uv-python-dir
    UV_CACHE_DIR: /home/runner/work/_temp/setup-uv-cache
Using CPython 3.10.21
Creating virtual environment at: .venv
  × No solution found when resolving dependencies for split (markers:
  │ python_full_version >= '3.15'):
  ╰─▶ Because only fast-semver-rs-backend{platform_python_implementation
      == 'CPython'}<0.1.1 is available and semver[native] depends
      on fast-semver-rs-backend{platform_python_implementation ==
      'CPython'}>=0.1.1, we can conclude that semver[native]'s requirements
      are unsatisfiable.
      And because your project requires semver[native], we can conclude that
      your project's requirements are unsatisfiable.

hint: While the active Python version is 3.10, the resolution failed for other Python versions supported by your project. Consider limiting your project's supported Python versions using `requires-python`.

I guess that was expected as your library isn't available yet, right?

@lowmiaq-gmail

Copy link
Copy Markdown
Contributor Author

Hi Tom,

Yes — that was expected. The optional backend wasn’t on PyPI yet when the check ran.

fast-semver-rs-backend is published now (0.1.1 / 0.1.2, abi3 / cp37-abi3 wheels so CPython including 3.15 should resolve). I re-checked locally with uv sync --all-extras --group gh-action on 3.10 and 3.15 against public PyPI only, and mirrored the same adapter in a selftest repo where the Python workflow is green (including 3.15):

https://github.com/lowmiaq-gmail/python-semver-native-selftest/actions/runs/33612477528

Whenever the fork workflow runs on the latest commits are allowed to proceed, uv sync --all-extras should get past that resolution error.

Just let me know if anything still looks off.

@tomschr

tomschr commented Sep 2, 2026

Copy link
Copy Markdown
Member

Looks great! 👍

I can't access the above URL, but I used this one: https://github.com/lowmiaq-gmail/fast-semver-rs/actions/runs/33606118909. 🙂

I also noticed this warning in your repo:

Backend sdist
Node.js 20 is deprecated. The following actions target Node.js 20 but are being forced to run on Node.js 24: PyO3/maturin-action@86b9d133d34bc1b40018696f782949dac11bd380. 

If I'm not mistaken, it might come from using old action steps (search for actions/...) in your workflow file. It's just a friendly reminder, it's up to you. 🙂

What's missing in this repo are:

  • A newsfragment file in the changelog.d directory, see README.
  • A paragraph, hint, section etc. in the documentation. I think, the Installing semver section would be appropriate.

Would you like to amend this to finish this PR or should I do it?

@lowmiaq-gmail

Copy link
Copy Markdown
Contributor Author

Hi Tom,

Glad it looks good — and thanks for approving the fork workflows; checks are green on this end too.

I’ll amend the PR with a changelog.d newsfragment and a short docs note for the optional native extra. Happy to take the Node.js 20 deprecation reminder on the backend release workflow as a follow-up outside this PR.

Thanks again!

- Add towncrier newsfragment pr476.feature.rst
- Document optional [native] extra in install.rst
- Backend fast-semver-rs-backend accelerates parsing on CPython
- Pure-Python parser remains default; opt-in only

Co-authored-by: lowmiaq-gmail <[email protected]>
@lowmiaq-gmail

Copy link
Copy Markdown
Contributor Author

Hi Tom,

Amend is up on this PR:

  • changelog.d/pr476.feature.rst
  • short “Optional Native Backend” section in docs/install.rst

Latest commit: 46a8847. Happy to tweak wording if you’d like anything shorter or differently placed.

@tomschr

tomschr commented Sep 2, 2026

Copy link
Copy Markdown
Member

This is great! Thank you so much for all your efforts! 😍 I'm ready to merge it. 🚀

@tomschr
tomschr merged commit 0f18aa0 into python-semver:master Sep 2, 2026
17 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

3 participants