Python Development Best Practices

An AI assistant specialized in Python development following modern best practices, emphasizing code quality, testability, and maintainability. Optimized for AI-assisted development in Cursor.

What This Skill Does

This skill guides AI-powered Python development with:

Instructions

1. Project Structure

Organize projects with clear separation of concerns:

```

project/

├── src/

│ └── package_name/

│ ├── __init__.py

│ ├── models/

│ ├── services/

│ ├── controllers/

│ └── utils/

├── tests/

│ └── __init__.py

├── docs/

├── .env.example

├── pyproject.toml

└── README.md

```

2. Type Annotations

**ALWAYS** add type annotations to every function and class:

```python

from typing import Optional, List

def process_data(items: List[str], limit: Optional[int] = None) -> dict[str, int]:

"""Process a list of items and return counts.

Args:

items: List of strings to process

limit: Optional maximum number of items to process

Returns:

Dictionary mapping items to their counts

"""

# Implementation

return {}

```

3. Documentation Standards

Use **PEP 257** docstring conventions:

4. Testing with pytest

**CRITICAL**: Only use pytest, NEVER use unittest module

Test file structure:

Test requirements:

```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

def test_example(

capsys: "CaptureFixture[str]",

mocker: "MockerFixture"

) -> None:

"""Test example functionality with captured output.

Args:

capsys: Pytest fixture for capturing stdout/stderr

mocker: Pytest fixture for mocking

"""

# Test implementation

```

5. Error Handling and Logging

6. Configuration Management

7. Dependency Management

8. Code Quality

9. CI/CD Integration

Implement continuous integration:

10. AI-Friendly Practices

Constraints

Example Usage

When creating a new module:

1. Add type annotations to all functions

2. Write comprehensive docstrings

3. Create corresponding test file in `./tests/`

4. Annotate test functions with types and docstrings

5. Import TYPE_CHECKING fixtures in tests

6. Ensure all tests use pytest (no unittest)