Release channels
The package is published to PyPI as auth-ai under the MIT license, and imported as auth_ai. It requires Python 3.12 or later.
Channels
| Channel | Trigger | PyPI version | Install |
|---|---|---|---|
| Stable | Creating a GitHub release vX.Y.Z from main. | X.Y.Z | pip install auth-ai |
| Pre-release | Creating a GitHub release marked pre-release for a version such as X.Y.ZrcN. | X.Y.ZrcN | pip install --pre auth-ai |
| Nightly | A manual run of the Nightly workflow, from develop or main. | X.Y.Z.devYYYYMMDDHHMM | pip install --pre auth-ai |
pip skips pre-releases and developmental releases unless you pass --pre (or pin the exact version).
Stable
The release is the trigger: create the GitHub release (and its tag vX.Y.Z) from main once the version is set in pyproject.toml. The workflow never creates a release or a tag itself. It:
- runs the same quality gates as continuous integration (format check, lint, strict type-check, unit tests with a coverage threshold, build and distribution checks, and an audit of the runtime dependencies);
- requires that the tag matches the version in
pyproject.toml, that the pre-release flag of the release matches the version (a PEP 440a,b,rcor.devsuffix means pre-release), and that a stable release points at a commit onmain; - builds the wheel and the source distribution, checks them with
twine check --strict, and publishes them.
If a run fails, fix the cause, then delete the release and its tag and create them again. PyPI never accepts the same version twice: bump the version if one was already uploaded.
Nightly
A nightly is published as a PEP 440 developmental release X.Y.Z.devYYYYMMDDHHMM, where the suffix is the UTC date and minute of the run. X.Y.Z is the version in pyproject.toml, or the next patch when that version is already on PyPI, so a nightly never sorts before a stable release. The version exists only in the workflow's workspace: no commit is made, so no version bump lands on the branch. The nightly runs the same quality gates first.
Use a nightly to try an unreleased change. Nothing about its API is guaranteed. Nightlies stay on PyPI: removing or yanking one is a manual action on pypi.org, because Trusted Publishing covers uploads only.
Authentication to PyPI
Both workflows publish through PyPI Trusted Publishing (OpenID Connect): no PyPI token is stored in the repository. Each workflow file (release.yml, nightly.yml) must be registered as a trusted publisher of the auth-ai project on pypi.org (owner circle-rd, repository auth-ai-py, GitHub environment pypi); before the first upload, register them as pending publishers.
Versioning
The project follows Semantic Versioning, written as a PEP 440 version. While the major version is 0, a breaking change bumps the minor version. Breaking changes are listed in the changelog, with a migration note, and the old behaviour is removed rather than kept behind a compatibility shim.
Supported runtimes and dependencies
Continuous integration runs the checks on Python 3.12, 3.13 and 3.14. Newer interpreters (3.15) are tested too, but without blocking a release. The runtime dependencies are httpx2[brotli,http2] (>=2.16), joserfc (>=1.7) and pydantic (>=2.12); the fastapi (>=0.115) and starlette (>=0.46) extras are optional.