coding-standards

Python Coding Standards

A comprehensive collection of Python coding standards and best practices. Designed for AI agents and LLMs to generate high-quality, performant, and maintainable Python code.

Categories

Error Handling [CRITICAL]

Prevent failures from being hidden or reported as successful outcomes.

Rule	Description
error-no-silent-exceptions	Never swallow exceptions

Performance Optimization [CRITICAL]

Apply Python optimization patterns to improve processing speed and memory efficiency.

Rule	Description
perf-list-comprehension	Prefer list comprehensions over loops (1.5-2x faster)
perf-generator-expression	Use generators for large datasets (O(1) memory)
perf-dict-get	Use dict.get() for efficient default values
perf-set-lookup	Use set for fast lookups (O(1) vs O(n))
perf-str-join	Use join for string concatenation (O(n) vs O(n²))

Async Processing [HIGH]

Efficient asynchronous programming patterns using asyncio.

Rule	Description
async-gather	Use asyncio.gather for independent tasks
async-create-task	Proper background task creation
async-context-manager	Resource management with async with
async-semaphore	Limit concurrency with semaphores

Design Principles [HIGH]

Software design principles for maintainability and extensibility.

Rule	Description
design-philosophy	DRY, YAGNI, KISS principles
design-single-responsibility	Single Responsibility Principle
design-dependency-injection	Loose coupling with dependency injection
design-no-global-singleton	Avoid global singletons and module-level shared instances
solid-ocp	Open/Closed Principle
solid-lsp	Liskov Substitution Principle
solid-isp	Interface Segregation Principle
design-pure-functions	Prefer pure functions without side effects
design-early-return	Reduce nesting with early returns

Documentation [HIGH]

Documentation standards for public API clarity and machine-checkable contracts.

Rule	Description
doc-docstring	Document public APIs with Google style docstrings
doc-type-hints	Require type hints for public APIs

Data Validation [HIGH]

Validation patterns for data crossing trust boundaries.

Rule	Description
validation-pydantic	Use Pydantic for boundary data validation

Object-Oriented Programming [MEDIUM]

Best practices for Pythonic object-oriented programming.

Rule	Description
oop-composition-over-inheritance	Prefer composition over inheritance
oop-dataclass	Use dataclass for data containers
oop-protocol	Prefer Protocol over abstract base classes
oop-property	Use property instead of getters

Quick Reference

Error Handling

try:
    config = parse_config(path)
except ConfigParseError as exc:
    raise StartupError(f"Invalid configuration: {path}") from exc


def main() -> int:
    try:
        start_application()
    except StartupError:
        logger.exception("Application startup failed")
        return 1  # explicit non-success outcome at the process boundary
    return 0


if __name__ == "__main__":
    raise SystemExit(main())

Performance Patterns

# List comprehension (not loops)
result = [x * 2 for x in items]

# Generator for large data
total = sum(x * x for x in range(1_000_000))

# dict.get() with default
value = config.get("key", default_value)

# Set for fast lookup
valid_ids: set[int] = {1, 2, 3}
if item_id in valid_ids: ...

# join for strings
result = ",".join(values)

Async Patterns

# Concurrent execution
results = await asyncio.gather(task1(), task2(), task3())

# Resource management
async with aiohttp.ClientSession() as session:
    async with session.get(url) as response:
        data = await response.json()

# Concurrency limit
semaphore = asyncio.Semaphore(10)
async with semaphore:
    await do_work()

Design Patterns

# Dependency injection (not module-level singletons)
class Service:
    def __init__(self, repository: Repository) -> None:
        self.repository = repository

# Composition root builds the graph once
def create_app(settings: Settings) -> Service:
    return Service(repository=PostgresRepository(settings.dsn))

# Open/Closed: extend via new types, not edits
class JsonFormat:
    def export(self, invoice: Invoice) -> str: ...

# Interface Segregation: small Protocols
class Workable(Protocol):
    def work(self) -> None: ...

# Early return
def process(data: Data | None) -> Result:
    if data is None:
        return Result.empty()
    # main logic here

Documentation Patterns

def create_user(email: str, name: str) -> User:
    """Create a user account.

    Args:
        email: Unique email address for the account.
        name: Display name for the user.

    Returns:
        The created user.
    """
    return user_repository.create(email=email, name=name)

Validation Patterns

from pydantic import BaseModel, EmailStr, Field

class CreateUserRequest(BaseModel):
    email: EmailStr
    age: int = Field(ge=0, le=150)

OOP Patterns

# Dataclass
@dataclass
class User:
    name: str
    email: str

# Protocol for interfaces
class Repository(Protocol):
    def get(self, id: str) -> Entity: ...

# Property
@property
def full_name(self) -> str:
    return f"{self.first} {self.last}"

See Also

• Recommended Tooling - Tools to enforce these standards automatically (ruff, mypy, pytest, pyscn, uv)