Skip to content

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 (.venv via uv sync)
  • Build backend: hatchling with uv-dynamic-versioning for versioned packages
  • Linter: ruff — NOT flake8, NOT pylint
  • Type checker: pyright — NOT mypy
  • Test framework: pytest with pytest-cov
  • Property-based testing: hypothesis
  • Configuration: pydantic-settings (TOML file sources plus environment) — one central typed Settings class; NOT bare os.environ/os.getenv, NOT python-dotenv called directly, NOT dynaconf/configparser

Constraints

  • All code must pass pyright type checking
  • All code must pass ruff check and ruff format --check
  • Use pyproject.toml for all project metadata (not setup.py, not setup.cfg)
  • Pin Python version in .python-version
  • requires-python states 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); no requirements.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-cov with fail_under
  • All configuration is declared in one central pydantic-settings BaseSettings subclass (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.getenv reads 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 .env rules follow twelve-factor; here settings_customise_sources wires environment over config/<env>.toml over config/default.toml over field defaults (.env dev-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 Settings class 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.toml per project (or per package in a workspace)
  • Library projects: use hatchling build backend with uv-dynamic-versioning for git-tag-based versions
  • Application projects: [tool.uv] package = false (no build artifact needed)
  • Organize source under src/<package_name>/ layout
  • Use pydantic v2 for data validation
  • Centralize configuration in one pydantic-settings BaseSettings subclass; group related settings with nested models and an env_nested_delimiter / env_prefix rather than scattering reads
  • Use SecretStr for credentials and AnyUrl/PostgresDsn-style types for endpoints; validate at startup so bad config fails fast
  • Source precedence per twelve-factor, via settings_customise_sources returning (init, env, file_secret, dotenv, toml_env, toml_default) (two TomlConfigSettingsSource instances; .env dev only)
  • settings_customise_sources reads APP_ENV via os.environ.get once, before constructing toml_env, to pick config/<env>.toml; that one read is the sanctioned exception to “no os.environ/os.getenv outside the settings module”
  • Use typer + rich for CLI interfaces

Implementation

  • Create/sync environment: uv sync (creates .venv automatically)
  • Run scripts: uv run python ... or uv run pytest
  • Add dependencies: uv add <pkg> (not pip install)
  • Add dev dependencies: uv add --dev <pkg> or to [dependency-groups] dev
  • Read configuration only through the central Settings object, built once at the entrypoint and injected; never os.getenv
  • Tests construct Settings(...) directly (or via monkeypatch.setenv) — never depend on a developer’s .env
  • Type annotations: all public functions and methods must have type annotations
  • Avoid Any — use pyright targeted # type: ignore with comment when unavoidable
  • Use TYPE_CHECKING guard for import-only type imports

Testing

  • Framework: pytest
  • Run: uv run pytest
  • Property-based: hypothesis for data invariants and input space exploration
  • Mocking: pytest-mock (not unittest.mock directly)
  • Coverage: pytest-cov with branch coverage; set fail_under in [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 . — lint
  • ruff format --check . — format
  • pyright — type check
  • uv run pytest --cov — tests with coverage
  • pre-commit run --all-files for the full gate
  • Complexity, statement, and public-method ceilings, a file-size cap, and pyright strict on application code, per code-shape-ceilings (strict defaults for new projects; ceilings only go down)
  • Reject os.environ/os.getenv outside the settings module (ruff TID251 banned-api on os.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.lock committed
  • 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"
    }
  ]
}