Python Helper

Python Helper

Follow the project's declared Python version and dependency workflow. Validate runtime data, make async ownership explicit, and distinguish read-only checks, local mutations, and external publication.

Current baseline

Verified 2026-08-03:

Python 3.14.7 was scheduled for the day after this verification. Check live status before repeating a patch number:

python --version
uv --version

The project's requires-python is the syntax and standard-library ceiling. Do not use a current interpreter to justify APIs outside that declared range.

Read references/releases.md for the 48-page research ledger and 3.14/3.15 features. Read references/tooling-and-packaging.md for uv, pip, publishing, Ruff, and type-checkers. Read references/testing-and-concurrency.md for pytest, asyncio, TaskGroup, interpreters, and free threading. Read references/types-and-security.md for typed boundaries, deferred annotations, subprocesses, archives, and secrets.

Command authority

Read-only or check-oriented commands:

python --version
uv --version
uv python list
uv tree --locked
uv run --locked ruff check .
uv run --locked ruff format --check .
uv run --locked pytest --collect-only
uv run --locked mypy .
uv run --locked pyright

For a uv-managed project, run project-installed tools through uv run --locked so checks use the versions selected by uv.lock and fail on lock drift. For another dependency workflow, use its verified project environment rather than whichever global tool happens to be on PATH.

Local mutations include uv add, uv sync, uv python install, uv python pin, ruff check --fix, and ruff format. Ruff unsafe fixes can change runtime behavior or remove comments; require an explicit diff review and focused tests.

uv publish mutates an external registry. Require explicit artifacts, registry, credentials, and publication authorization.

uv projects

Use uv's project interface for a uv-managed application or package:

uv sync --locked
uv run --locked pytest
uv add httpx
uv add --dev pytest ruff

• Commit uv.lock; it is a universal exact-resolution lockfile.
• --locked checks that project metadata and lock agree.
• --frozen uses the lock without checking whether project metadata changed; it is not the stricter CI option.
• Development tools belong in [dependency-groups].dev.
• [project.optional-dependencies] defines consumer-installable extras.
• uv pip is the lower-level environment interface, not the default project/lock workflow.
• uv --version reports the uv binary. uv version reads or can update the project version.

pip boundaries

Use python -m pip inside a verified virtual environment when a project uses pip. pip freeze is an environment snapshot, not a portable lock or secure supply-chain workflow. pip lock remains experimental and its pylock.toml is specific to the current Python/platform.

Secure requirements installs need complete hashes and may disallow source distributions:

python -m pip install --require-hashes --only-binary :all: -r requirements.txt

Type and validate boundaries

Avoid bare dict and list[dict]; they introduce imprecise values. Use dataclasses, TypedDict, Pydantic models, or precise mappings according to whether runtime validation is needed.

from pydantic import BaseModel, TypeAdapter


class User(BaseModel):
    id: int
    email: str


Users = TypeAdapter(list[User])
users = Users.validate_python(response.json())

Check HTTP status before parsing. A type annotation does not validate JSON, environment variables, database results, cache values, or deserialized files.

Any disables static checking and is not an escape hatch for repository code. Use precise protocols, generics, or object plus boundary validation instead. Use Never for exhaustiveness.

TypeIs narrows both branches and requires the narrowed type to be a subtype. TypeGuard remains necessary for some invariant-container or otherwise non-subtype narrowing. Neither is universally preferred.

Async and concurrency

Use TaskGroup when sibling cancellation and grouped failures are the intended semantics. asyncio.gather() does not cancel sibling awaitables merely because one fails. return_exceptions=True turns exceptions into results and must not silently normalize failure.

Reuse clients so connection pooling works:

import asyncio

import httpx


async def fetch_all(urls: list[str]) -> list[str]:
    async with httpx.AsyncClient() as client:
        async with asyncio.TaskGroup() as group:
            tasks = [group.create_task(fetch_text(client, url)) for url in urls]
    return [task.result() for task in tasks]


async def fetch_text(client: httpx.AsyncClient, url: str) -> str:
    response = await client.get(url)
    response.raise_for_status()
    return response.text

Own the event loop at the application boundary. Do not monkey-patch it with archived nest_asyncio; use top-level await in notebooks or refactor nested asyncio.run() calls.

Subinterpreters have separate execution contexts and GILs but are not security boundaries. Free-threaded Python is supported in 3.14, yet extensions can re-enable the GIL and shared state still requires synchronization.