build-python-apps

name	build-python-apps
description	Build or modify Python applications using the user's preferred Python defaults. Use when working on Python services, src-layout packages, uv projects, typed functions, Ruff, Pyright, pytest, configuration, service-layer business logic, dependency groups, or Python app structure.

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].

Use environment-specific config modules or typed settings objects when runtime behavior changes by environment. Keep defaults safe for local development and tests.

Testing And Verification

Write behavior-focused tests:

• Unit tests for pure service logic.
• Integration tests for database, HTTP, queue, or external dependency boundaries.
• Factories for repeated model setup.
• Async tests with pytest-asyncio when needed.

Run the closest available checks:

• uv run ruff check .
• uv run ruff format --check .
• uv run pyright
• uv run pytest

If the repo has Makefile targets, use those instead of raw commands.