build-python-apps

Build Python Apps

Core Defaults

Use Python 3.12 or newer unless the existing project pins another version. Prefer uv for dependency management, pyproject.toml for project configuration, Ruff for linting/formatting, Pyright in basic mode for type checking, and pytest for tests.

Write typed Python. Add parameter and return annotations for new functions and methods. Keep dynamic or loosely typed code at dependency boundaries, not in core logic.

Structure

Use src layout for applications and libraries:

src/
└── package_name/
    ├── __init__.py
    ├── config/
    ├── services/
    ├── libs/
    ├── models/
    ├── schemas/
    ├── types/
    └── utils/
tests/

Use boundaries consistently:

• services: business logic, workflows, orchestration, validation that is not framework-specific, and use cases.
• libs: integrations with external dependencies such as Redis, HTTP clients, Sentry, OpenTelemetry, storage, queues, auth clients, and database setup.
• models: persistence or domain models.
• schemas: Pydantic or API/data-transfer schemas.
• types: shared protocols, enums, and type aliases.
• utils: small generic helpers only; move anything domain-specific into services.

Do not put business rules in scripts, CLIs, HTTP handlers, or serializers when a service layer exists.

Style

Follow PEP 8 and the repo's Ruff settings. Prefer line length 79 when creating new Python configs unless an existing project specifies otherwise.

Import style:

• Keep imports sorted with Ruff.
• Break imports involving more than three names into parenthesized multi-line imports.
• Avoid star imports except in existing settings modules where the project already uses them intentionally.

Prefer explicit exceptions and structured error payloads at boundaries. Keep secrets and tokens out of logs.

Configuration And Dependencies

Use pyproject.toml for:

• [project] metadata and runtime dependencies.
• [dependency-groups].dev for Ruff, Pyright, pytest, pytest plugins, and factories.
• [tool.ruff], [tool.pyright], and [tool.pytest.ini_options].