Python Best Practices with Typing & Pytest

An AI assistant specialized in Python development following modern best practices, emphasizing type safety, comprehensive testing, and clear documentation.

What This Skill Does

This skill guides you to write production-quality Python code with:

Instructions

1. Project Structure

Always organize Python projects with clear separation:

```

project/

├── src/

│ └── package_name/

│ ├── __init__.py

│ ├── models/

│ ├── services/

│ ├── controllers/

│ └── utils/

├── tests/

│ ├── __init__.py

│ └── test_*.py

├── docs/

├── .env.example

├── pyproject.toml

└── README.md

```

2. Type Annotations

**CRITICAL:** Add type annotations to EVERY function and class:

```python

from typing import Optional, List, Dict, Any

def process_data(

items: List[Dict[str, Any]],

threshold: float = 0.5

) -> Optional[Dict[str, Any]]:

"""Process data items above threshold.

Args:

items: List of data dictionaries to process.

threshold: Minimum value threshold for processing.

Returns:

Processed result dictionary, or None if no items qualify.

"""

# Implementation here

pass

```

3. Docstrings

Use PEP 257 convention for ALL functions and classes:

```python

def calculate_metrics(data: pd.DataFrame, window: int = 7) -> Dict[str, float]:

"""Calculate rolling metrics for the given data.

Computes mean, median, and standard deviation over a rolling window.

Args:

data: Input DataFrame with numeric columns.

window: Rolling window size in days.

Returns:

Dictionary mapping metric names to computed values.

Raises:

ValueError: If window size is less than 1.

"""

pass

```

4. Testing with Pytest

**NEVER use unittest module.** All tests use pytest:

```python

from typing import TYPE_CHECKING

import pytest

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

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

"""Test data processing with mocked dependencies.

Verifies that process_data correctly filters and transforms

input items based on the threshold parameter.

"""

# Test implementation

pass

@pytest.fixture

def sample_data() -> Dict[str, Any]:

"""Provide sample test data.

Returns:

Dictionary containing test fixture data.

"""

return {"key": "value"}

```

5. File Organization

6. Configuration & Dependencies

Use modern Python tooling:

```toml

pyproject.toml

[project]

name = "your-package"

requires-python = ">=3.11"

dependencies = [

"pydantic>=2.0",

]

[tool.ruff]

line-length = 100

select = ["E", "F", "I"]

[tool.pytest.ini_options]

testpaths = ["tests"]

python_files = ["test_*.py"]

```

Manage dependencies with `uv`:

```bash

uv pip install -r requirements.txt

uv pip compile pyproject.toml -o requirements.txt

```

7. Error Handling & Logging

Implement robust error handling with context:

```python

import logging

from typing import Optional

logger = logging.getLogger(__name__)

def safe_operation(data: Dict[str, Any]) -> Optional[Result]:

"""Perform operation with comprehensive error handling.

Args:

data: Input data dictionary.

Returns:

Operation result, or None if operation fails.

"""

try:

result = risky_operation(data)

logger.info("Operation succeeded", extra={"data_keys": list(data.keys())})

return result

except ValueError as e:

logger.error("Invalid data provided", exc_info=True, extra={"data": data})

return None

```

8. CI/CD Integration

Include GitHub Actions or GitLab CI configuration:

```yaml

.github/workflows/test.yml

name: Test

on: [push, pull_request]

jobs:

test:

runs-on: ubuntu-latest

steps:

- uses: actions/checkout@v4

- uses: actions/setup-python@v5

with:

python-version: '3.11'

- run: pip install uv

- run: uv pip install -e ".[test]"

- run: pytest tests/ -v

- run: ruff check .

```

Key Principles

1. **Type Everything**: Every function parameter, return value, and variable should have type annotations

2. **Document Everything**: All public functions and classes need PEP 257 docstrings

3. **Test Everything**: Use pytest with full type annotations and conditional TYPE_CHECKING imports

4. **Preserve Comments**: Never remove existing comments when modifying code

5. **Modular Design**: Separate concerns into models, services, controllers, and utilities

6. **Modern Tooling**: Use uv for dependencies, Ruff for linting, pytest for testing

Example Usage

When creating a new Python module:

```python

"""User service module.

Handles user-related business logic and data operations.

"""

from typing import Optional, List

import logging

from .models import User

from .exceptions import UserNotFoundError

logger = logging.getLogger(__name__)

class UserService:

"""Service for managing user operations.

Provides methods for creating, retrieving, updating, and deleting users.

"""

def __init__(self, db_connection: Connection) -> None:

"""Initialize user service.

Args:

db_connection: Database connection instance.

"""

self.db = db_connection

def get_user(self, user_id: int) -> Optional[User]:

"""Retrieve user by ID.

Args:

user_id: Unique user identifier.

Returns:

User instance if found, None otherwise.

Raises:

DatabaseError: If database query fails.

"""

try:

return self.db.query(User).filter_by(id=user_id).first()

except Exception as e:

logger.error(f"Failed to retrieve user {user_id}", exc_info=True)

raise DatabaseError(f"Database query failed: {e}") from e

```

Constraints