Python Development Standards

Enforce strict development standards for Python projects, ensuring code quality, consistency, and maintainability through modern tooling and best practices.

Core Principles

When working on Python projects with this skill:

1. **Always use English** for all code, comments, documentation, strings, and log messages

2. **Format with 2-space indentation** consistently throughout the codebase

3. **Use full English words** for all identifiers (variables, functions, classes) - no abbreviations

4. **Apply type hints** to all function signatures without exception

5. **Leverage modern Python features**: f-strings, pathlib, dataclasses

Toolchain Requirements

Package Management

Code Quality

Commenting Philosophy

Comments must explain **why**, not what. For complex logic, clarify both the "what" and provide examples.

DO:

DON'T:

Examples:

```python

✅ GOOD: Explains the "why" behind the magic number

The upstream gateway has a hard limit of 10 seconds

TIMEOUT = 10

✅ GOOD: Explains complex logic with example

This regex matches comma-separated values, ignoring commas inside quotes

e.g., "a,b,\"c,d\",e" -> ["a", "b", "\"c,d\"", "e"]

COMPLEX_REGEX = r',(?=(?:[^\"]*\"[^\"]*\")*[^\"]*$)'

❌ BAD: Describes edit history

Changed timeout from 5s to 10s

TIMEOUT = 10

❌ BAD: Useless comment for simple code

Defines a function that adds two numbers

def add(a: int, b: int) -> int:

return a + b

✅ GOOD: Self-explanatory code needs no comment

def add(a: int, b: int) -> int:

return a + b

```

Modern Python Requirements

Type Hints

All function signatures must include complete type hints:

```python

from pathlib import Path

from dataclasses import dataclass

def process_file(file_path: Path, timeout: int = 10) -> dict[str, str]:

"""Process a file and return parsed data."""

pass

@dataclass

class Config:

timeout: int

retries: int

base_url: str

```

String Formatting

Always use f-strings:

```python

✅ GOOD

message = f"Processing {file_count} files in {duration}s"

❌ BAD

message = "Processing {} files in {}s".format(file_count, duration)

message = "Processing %d files in %ds" % (file_count, duration)

```

File Path Operations

Always use `pathlib.Path`:

```python

from pathlib import Path

✅ GOOD

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

if config_path.exists():

content = config_path.read_text()

❌ BAD

import os

config_path = os.path.join("config", "settings.json")

if os.path.exists(config_path):

with open(config_path) as f:

content = f.read()

```

Testing Standards

Test Organization

Test Assertions

Use Python's built-in `assert` statement:

```python

def test_parser():

result = parse_input("test")

assert result == expected_value

assert len(result.items) > 0

```

Test Data Sources

Use standard examples when possible:

Running Tests

```bash

Run all tests

uv run pytest

Run specific test file

uv run pytest tests/test_parser.py

Run with verbose output

uv run pytest -v

```

Workflow

1. **Plan First**: For complex tasks, propose a step-by-step implementation plan before writing code

2. **Test Coverage**: Write pytest tests for all new functionality

3. **Atomic Commits**: Keep commits small and focused on a single change

4. **Clean Implementation**: If a solution becomes messy, reset and re-implement cleanly rather than patching

5. **Format Before Commit**: Run `ruff` formatting on all modified files before finalizing

Quality Checklist

Before completing any task, verify:

Constraints