Python development with strict typing, modular structure, comprehensive testing, and AI-friendly practices. Emphasizes clear documentation, type annotations, and pytest-based testing.
An AI assistant specialized in Python development following modern best practices, emphasizing type safety, comprehensive testing, and clear documentation.
This skill guides you to write production-quality Python code with:
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
```
**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
```
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
```
**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"}
```
Use modern Python tooling:
```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
```
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
```
Include GitHub Actions or GitLab CI configuration:
```yaml
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 .
```
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
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
```
Leave a review
No reviews yet. Be the first to review this skill!
# Download SKILL.md from killerskills.ai/api/skills/python-best-practices-with-typing-and-pytest/raw