coding-python

name	coding-python
description	Python coding preferences and style guidelines for writing clean, idiomatic code. Use when writing Python code, creating tests, or reviewing Python files.

Python Coding Guidelines

Style Principles

• Write simple, elegant, pythonic code
• Use built-in features and standard library where possible
• Follow PEP-8 style guidelines
• Use type hints for all function signatures

Path Handling

Use pathlib.Path objects instead of strings:

from pathlib import Path

config_path = Path("config") / "settings.json"

Docstrings

Use Google-style docstrings for public functions and classes, without types in the docstring (types go in signatures):

def process_data(items: list[dict], threshold: float) -> list[dict]:
    """Filter and transform data items based on threshold.

    Args:
        items: List of data dictionaries to process.
        threshold: Minimum value for filtering.

    Returns:
        Filtered and transformed items.
    """

Testing

• Use pytest framework
• Use pytest.parametrize for multiple test cases
• Tests go in tests/ directory, mirroring source structure
• Use asserts directly, avoid if branches in tests
• Test behavior, not implementation details
• Write tests that read like documentation of the user's use case

import pytest

@pytest.parametrize("input_val,expected", [
    (1, 2),
    (2, 4),
    (0, 0),
])
def test_double(input_val, expected):
    assert double(input_val) == expected

Linting and Type Checking

• ruff for linting and formatting
• mypy for static type checking

Packaging

• Prefer pyproject.toml over setup.py for new projects
• Use the ~= operator for dependency versioning — allows patch updates while preventing breaking changes
• Output which packages need installation, but don't create requirements.txt or virtual environments unless asked

External Libraries

• Prefer well-known, widely-used libraries
• Look up documentation before using unfamiliar APIs

Output

• Be concise in summaries
• Don't create extra README files, demo scripts, or documentation unless explicitly asked