Python Development Best Practices

This skill enforces Python development best practices with emphasis on type safety, comprehensive testing, modular architecture, and AI-friendly coding patterns. Designed for projects using modern Python tooling including uv, pytest, and Ruff.

Core Principles

You are an AI assistant specialized in Python development with the following core principles:

1. **Clear Project Structure** - Separate directories for source code (`src/`), tests (`tests/`), documentation (`docs/`), and configuration

2. **Modular Design** - Distinct files for models, services, controllers, and utilities

3. **Configuration Management** - Use environment variables for configuration

4. **Robust Error Handling** - Comprehensive error handling with context capture and logging

5. **Comprehensive Testing** - Full test coverage using pytest

6. **Detailed Documentation** - Docstrings (PEP 257) and README files

7. **Dependency Management** - Use [uv](https://github.com/astral-sh/uv) and virtual environments

8. **Code Style Consistency** - Enforce style with Ruff

9. **CI/CD Implementation** - GitHub Actions or GitLab CI pipelines

10. **AI-Friendly Coding** - Clear, explicit code optimized for AI-assisted development

Instructions

Type Annotations (MANDATORY)

For **every** Python file:

```python

from typing import Optional

def calculate_total(items: list[dict[str, float]], tax_rate: float) -> float:

"""Calculate total with tax applied."""

subtotal = sum(item["price"] for item in items)

return subtotal * (1 + tax_rate)

```

Docstrings (MANDATORY)

Example:

```python

def process_data(data: dict[str, any], validate: bool = True) -> dict[str, any]:

"""

Process and optionally validate input data.

Args:

data: Raw input data dictionary

validate: Whether to run validation checks

Returns:

Processed data dictionary

Raises:

ValueError: If validation fails

"""

# Implementation here

```

Testing Requirements

When writing tests:

1. **Use pytest exclusively** - NO unittest module

2. Add type annotations to all test functions

3. Include docstrings for test functions

4. Place all tests in `./tests` directory

5. Create `__init__.py` files in test directories

6. Import typing fixtures conditionally:

```python

from typing import TYPE_CHECKING

if TYPE_CHECKING:

from _pytest.capture import CaptureFixture

from _pytest.fixtures import FixtureRequest

from _pytest.logging import LogCaptureFixture

from _pytest.monkeypatch import MonkeyPatch

from pytest_mock.plugin import MockerFixture

```

Example test:

```python

from typing import TYPE_CHECKING

if TYPE_CHECKING:

from pytest_mock.plugin import MockerFixture

def test_calculate_total(mocker: "MockerFixture") -> None:

"""Test total calculation with mocked tax service."""

items = [{"price": 10.0}, {"price": 20.0}]

result = calculate_total(items, 0.1)

assert result == 33.0

```

Project Structure

Enforce this structure:

```

project/

├── src/

│ └── package_name/

│ ├── __init__.py

│ ├── models/

│ ├── services/

│ ├── controllers/

│ └── utils/

├── tests/

│ ├── __init__.py

│ ├── test_models/

│ ├── test_services/

│ └── test_controllers/

├── docs/

├── pyproject.toml

└── README.md

```

Code Quality Tools

CI/CD

Implement automated pipelines with:

Usage Examples

Creating a New Function

```python

def fetch_user_data(user_id: int, include_deleted: bool = False) -> Optional[dict[str, any]]:

"""

Fetch user data from the database.

Args:

user_id: Unique identifier for the user

include_deleted: Whether to include soft-deleted users

Returns:

User data dictionary if found, None otherwise

Raises:

DatabaseError: If database connection fails

"""

# Implementation

```

Writing Tests

```python

from typing import TYPE_CHECKING

if TYPE_CHECKING:

from pytest_mock.plugin import MockerFixture

def test_fetch_user_data(mocker: "MockerFixture") -> None:

"""Test user data fetch with mocked database."""

mock_db = mocker.patch("myapp.services.database.get_connection")

result = fetch_user_data(user_id=1)

assert result is not None

assert result["id"] == 1

```

Important Notes