Python + uv
Category: Tech Stack · Areas: all
Description
Category
tech-stack
Areas
all
Slot
language-runtime
Components
- Language: Python; applications target the version their deploy runtime runs (3.12+ when the runtime allows), libraries target the lowest Python their consumers run
- Package manager: uv — NOT pip, NOT poetry, NOT conda
- Virtual environment: uv-managed (
.venvviauv sync) - Build backend:
hatchlingwithuv-dynamic-versioningfor versioned packages - Linter:
ruff— NOT flake8, NOT pylint - Type checker:
pyright— NOT mypy - Test framework:
pytestwithpytest-cov - Property-based testing:
hypothesis - Configuration:
pydantic-settings(TOML file sources plus environment) — one central typedSettingsclass; NOT bareos.environ/os.getenv, NOTpython-dotenvcalled directly, NOTdynaconf/configparser
Constraints
- All code must pass
pyrighttype checking - All code must pass
ruff checkandruff format --check - Use
pyproject.tomlfor all project metadata (notsetup.py, notsetup.cfg) - Pin Python version in
.python-version requires-pythonstates the lowest supported Python, and CI runs the tests on that version; a library’s floor is the lowest Python any consumer runtime runs, not a preferred version- All dependencies in
[project.dependencies]or[dependency-groups](dev); norequirements.txt - Use
[tool.uv.sources]for custom package indexes (e.g., PyTorch CUDA wheels) - Tests in
tests/directory; pytest markers for test categories (acceptance, contract, slow, fast) - Branch coverage enforced via
pytest-covwithfail_under - All configuration is declared in one central
pydantic-settingsBaseSettingssubclass (single module, e.g.src/<package>/settings.py); every setting is a typed field with a default or is required - Settings are instantiated once at the composition root (app/CLI entrypoint) and passed in; no
os.environ/os.getenvreads and no module-level settings singletons elsewhere in the codebase - Secrets use
SecretStr; missing or invalid config fails at startup, not at first use - Config layering and
.envrules followtwelve-factor; heresettings_customise_sourceswires environment overconfig/<env>.tomloverconfig/default.tomlover field defaults (.envdev-only)
When to use
Python projects that benefit from fast dependency resolution and reproducible environments. Good for data services, APIs, ML pipelines, CLI tools, and libraries. uv is the single tool for venv creation, dependency resolution, and script running.
Artifact Impact
Selecting this concern requires these artifacts to change (a selected concern absent from them is drift):
- TD: pyproject.toml layout, dependency-group conventions, branch-coverage floor, central
Settingsclass and its config-key contract (owner and source per key)
Practices by activity
Agents working in any of these activities inherit the practices below through runtime work context, such as a DDx bead context digest.
Requirements (Frame activity)
- Specify the minimum Python version from the deploy targets, not a preference: an application uses what its runtime runs (3.12+ when the runtime allows); a library uses the lowest Python any consumer runtime runs (for example, pip-resolved Databricks Apps run Python 3.11)
- Inventory the configuration the system needs (endpoints, credentials, feature flags) and which are secrets
- Identify whether the project is a library (published) or an application (not published)
- If ML/GPU dependencies exist, plan for
[tool.uv.sources]with custom package indexes
Design
- One
pyproject.tomlper project (or per package in a workspace) - Library projects: use
hatchlingbuild backend withuv-dynamic-versioningfor git-tag-based versions - Application projects:
[tool.uv] package = false(no build artifact needed) - Organize source under
src/<package_name>/layout - Use
pydanticv2 for data validation - Centralize configuration in one
pydantic-settingsBaseSettingssubclass; group related settings with nested models and anenv_nested_delimiter/env_prefixrather than scattering reads - Use
SecretStrfor credentials andAnyUrl/PostgresDsn-style types for endpoints; validate at startup so bad config fails fast - Source precedence per
twelve-factor, viasettings_customise_sourcesreturning(init, env, file_secret, dotenv, toml_env, toml_default)(twoTomlConfigSettingsSourceinstances;.envdev only) settings_customise_sourcesreadsAPP_ENVviaos.environ.getonce, before constructingtoml_env, to pickconfig/<env>.toml; that one read is the sanctioned exception to “noos.environ/os.getenvoutside the settings module”- Use
typer+richfor CLI interfaces
Implementation
- Create/sync environment:
uv sync(creates.venvautomatically) - Run scripts:
uv run python ...oruv run pytest - Add dependencies:
uv add <pkg>(notpip install) - Add dev dependencies:
uv add --dev <pkg>or to[dependency-groups] dev - Read configuration only through the central
Settingsobject, built once at the entrypoint and injected; neveros.getenv - Tests construct
Settings(...)directly (or viamonkeypatch.setenv) — never depend on a developer’s.env - Type annotations: all public functions and methods must have type annotations
- Avoid
Any— usepyrighttargeted# type: ignorewith comment when unavoidable - Use
TYPE_CHECKINGguard for import-only type imports
Testing
- Framework:
pytest - Run:
uv run pytest - Property-based:
hypothesisfor data invariants and input space exploration - Mocking:
pytest-mock(notunittest.mockdirectly) - Coverage:
pytest-covwith branch coverage; setfail_underin[tool.coverage.report] - Test markers:
acceptance,contract,slow,fast— use--strict-markers - Filter known third-party deprecation warnings in
[tool.pytest.ini_options] filterwarnings
Quality Gates (pre-commit / CI)
ruff check .— lintruff format --check .— formatpyright— type checkuv run pytest --cov— tests with coveragepre-commit run --all-filesfor the full gate- Complexity, statement, and public-method ceilings, a file-size cap, and pyright
stricton application code, percode-shape-ceilings(strict defaults for new projects; ceilings only go down) - Reject
os.environ/os.getenvoutside the settings module (ruffTID251banned-api onos.getenv/os.environ, ignored per-file for the settings module)
Dependency Management
uv add <pkg>/uv add --dev <pkg>- Custom indexes: declare in
[tool.uv.sources]and[[tool.uv.index]] - Lock file:
uv.lockcommitted - Do not commit
.venv/or use system Python
Innsigle seal: model-primary by HELIX
The signature covers the markdown source of this page, not these HTML bytes. This page quotes that seal; verify it against the source file.
- Composition
- model-primary
- Issuer
- HELIX
helix - Signing key
ed25519:b0865d76d834a52c48506414d16f4e5a(build key)- Signed source
concerns/python-uv.md- Signed
- 2026-11-16T15:52:45Z
- Content digest
sha256:b2a70003…30c3aec1
This build key is endorsed by the human key for build signing; the signature is not a detector and not a truth guarantee.
Raw attestation JSON
{
"payload": {
"innsigle": "1",
"type": "https://innsigle.dev/claim/colophon/v1",
"issued_at": "2026-11-16T15:52:45Z",
"issuer": {
"id": "helix",
"name": "HELIX",
"key_id": "ed25519:b0865d76d834a52c48506414d16f4e5a",
"key_url": "https://documentdrivendx.github.io/helix/.well-known/innsigle/keys.json"
},
"subjects": [
{
"uri": "https://documentdrivendx.github.io/helix/concerns/python-uv/",
"digest": {
"alg": "sha256",
"value": "b2a70003990a51a69bd100684f54776728620d8007bb126fb7b62a6a30c3aec1"
}
}
],
"colophon": {
"schema_version": "1",
"composition": "model-primary",
"ingredients": [
{
"kind": "model",
"name": "Claude",
"role": "draft"
},
{
"kind": "tool",
"name": "sloptimizer",
"role": "rewrite"
},
{
"kind": "human",
"name": "operator",
"role": "structure-edit"
}
],
"notes": null
}
},
"payload_encoding": "json",
"signatures": [
{
"key_id": "ed25519:b0865d76d834a52c48506414d16f4e5a",
"alg": "ed25519",
"sig": "yatT8aR_-oYCJyJPKz8Eu0M2Ty71yvR0xYlk-wXjaE9SaYWLlCZl3roQ1K_swaTP8G-zZOzzcvhsBC0HN8ZdBg",
"signed_at": "2026-11-16T15:52:45Z"
}
]
}