This page documents the build system and dependency management infrastructure used in the Auth0 Python SDK. It covers the Poetry build system, dependency architecture, project configuration, and the dynamic versioning mechanism.
For information about the development environment setup process, see Development Environment Setup. For details about the CI/CD pipeline that uses this build system, see CI/CD Pipeline.
The Auth0 Python SDK uses Poetry as its build system and dependency manager. Poetry provides deterministic builds through lock files, separates runtime and development dependencies, and integrates with modern Python packaging standards (PEP 517/518). The build system is configured via pyproject.toml and uses the poetry-dynamic-versioning plugin to extract version information from git tags.
Sources: pyproject.toml1-102 .github/workflows/test.yml61-64
Diagram: Build System Architecture and Artifact Flow
The build system uses Poetry as the central orchestrator, with poetry-core serving as the PEP 517 build backend. Version numbers are dynamically extracted from git tags via the poetry-dynamic-versioning plugin. The poetry.lock file ensures reproducible builds by pinning all transitive dependencies.
Sources: pyproject.toml99-101 .github/workflows/test.yml61-64
The SDK has a dual-stack dependency architecture, reflecting the separation between the Management API (v5.0+ rewrite using Fern) and the Authentication API (legacy implementation):
Diagram: Dependency Architecture by API Type
The dependency tree clearly separates concerns:
httpx and pydanticaiohttp, requests, and JWT librariesSources: pyproject.toml38-65 requirements.txt1-12
The [project] and [tool.poetry] sections define package metadata:
| Configuration Key | Value | Purpose |
|---|---|---|
name | "auth0-python" | Package name on PyPI |
version | "5.1.0" | Current version (overridden by dynamic versioning) |
description | "Auth0 Python SDK..." | Short package description |
license | "MIT" | License type |
python | "^3.8" | Minimum Python version |
The package supports Python 3.8-3.12, with specific classifiers for each version:
Sources: pyproject.toml1-29
Diagram: Package Structure Configuration
The packages directive maps the auth0 package from the src/ directory to the site-packages location during installation, following the src-layout pattern.
Sources: pyproject.toml30-32
The SDK uses semantic versioning constraints:
| Constraint Type | Example | Meaning |
|---|---|---|
| Minimum version | >= 0.21.2 | Any version at or above |
| Caret range | ^7.4.0 | Compatible versions (7.4.0 ≤ x < 8.0.0) |
| Exact pin | == 1.13.0 | Exact version only |
| Range | >= 0.23.3, < 0.26.0 | Between two versions |
Critical pins:
mypy == 1.13.0 - Exact version to ensure consistent type checkingruff == 0.11.5 - Exact version for consistent linting rulesFlexible ranges:
pytest ^7.4.0 - Allow minor/patch updates within v7httpx >= 0.21.2 - Minimum version with no upper boundSources: pyproject.toml38-65
Diagram: Poetry Lock File Structure and Verification
The poetry.lock file contains:
Example entry structure:
[[package]]
name = "aiohttp"
version = "3.10.11"
description = "Async http client/server framework (asyncio)"
optional = false
python-versions = ">=3.8"
groups = ["main", "dev"]
markers = "python_full_version == \"3.8.*\" or platform_python_implementation == \"PyPy\""
files = [
{file = "aiohttp-3.10.11-cp310-cp310-macosx_10_9_universal2.whl", hash = "sha256:..."},
...
]
Sources: poetry.lock1-15 poetry.lock30-141
The [build-system] section defines the PEP 517 build backend:
This configuration:
poetry-core as the only build-time dependencypoetry.core.masonry.api build backend for creating wheels and source distributionspip install directly from sourceSources: pyproject.toml99-101
The SDK uses poetry-dynamic-versioning to automatically extract version numbers from git tags:
Diagram: Dynamic Versioning Workflow
The plugin is installed in CI:
During build, it:
.version file if git is unavailableversion field in pyproject.toml (in-memory only)Sources: .github/workflows/test.yml64 pyproject.toml6
Diagram: Development Dependency Installation Flow
The typical development workflow:
git clone https://github.com/auth0/auth0-pythonpipx install poetrypoetry config virtualenvs.in-project truepoetry install --with devpoetry shell or poetry run <command>In CI, the workflow additionally installs poetry-dynamic-versioning:
Sources: .github/workflows/test.yml54-68 README.md32-34
Sources: pyproject.toml70-73
Configuration includes:
Sources: pyproject.toml75-97
Enables automatic async test detection and execution via pytest-asyncio.
Sources: pyproject.toml67-68
The complete dependency breakdown:
| Package | Version | Used By | Purpose |
|---|---|---|---|
httpx | ≥0.21.2 | Management API | HTTP client (sync/async) |
pydantic | ≥1.9.2 | Management API | Data validation |
pydantic-core | ≥2.18.2 | Management API | Pydantic internals |
typing_extensions | ≥4.0.0 | Both APIs | Type hint backports |
aiohttp | ≥3.10.11 | Authentication API | Async HTTP client |
cryptography | ≥43.0.1 | Authentication API | Cryptographic operations |
pyjwt | ≥2.8.0 | Authentication API | JWT handling |
requests | ≥2.32.3 | Authentication API | Sync HTTP client |
urllib3 | ≥2.2.3 | Authentication API | HTTP foundation |
| Package | Version | Purpose |
|---|---|---|
mypy | ==1.13.0 | Static type checking |
ruff | ==0.11.5 | Linting and formatting |
pytest | ^7.4.0 | Test framework |
pytest-asyncio | ^0.23.5 | Async test support |
pytest-xdist | ^3.6.1 | Parallel test execution |
pytest-cov | ^4.1.0 | Coverage reporting |
pytest-aiohttp | ^1.0.4 | aiohttp test utilities |
aioresponses | ^0.7.8 | Mock aiohttp responses |
responses | ≥0.23.3,<0.26.0 | Mock requests responses |
mock | ^5.1.0 | General mocking |
python-dateutil | ^2.9.0 | Date utilities for tests |
types-python-dateutil | ^2.9.0.20240316 | Type stubs |
types-requests | ^2.31.0 | Type stubs |
Sources: pyproject.toml38-65 requirements.txt1-12
The requirements.txt file is a simplified representation of runtime dependencies:
Diagram: requirements.txt vs Poetry Dependency Management
The requirements.txt file:
pip install -r requirements.txtpyproject.toml)Sources: requirements.txt1-12 pyproject.toml38-49
Summary: The Auth0 Python SDK uses Poetry for modern, deterministic dependency management. The dual-stack architecture reflects the Management API (modern, Pydantic-based) and Authentication API (legacy) implementations. The build system integrates dynamic versioning from git tags and maintains reproducible builds through poetry.lock. All configuration is centralized in pyproject.toml, with separate dev dependencies for comprehensive testing and quality assurance.
Refresh this wiki