Skill v1.0.1
currentLLM-judged scan100/1001 files
version: "1.0.1" name: coding-standards description: Python coding standards and best practices covering error handling, performance optimization, async patterns, SOLID design principles, documentation, data validation, and object-oriented programming. Use when writing, reviewing, or refactoring Python code, or when the user asks about Python style, design, or best practices. paths:
- "**/*.py"
- "pyproject.toml"
- "setup.py"
- "requirements*.txt"
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 excdef main() -> int:try:start_application()except StartupError:logger.exception("Application startup failed")return 1 # explicit non-success outcome at the process boundaryreturn 0if __name__ == "__main__":raise SystemExit(main())
Performance Patterns
# List comprehension (not loops)result = [x * 2 for x in items]# Generator for large datatotal = sum(x * x for x in range(1_000_000))# dict.get() with defaultvalue = config.get("key", default_value)# Set for fast lookupvalid_ids: set[int] = {1, 2, 3}if item_id in valid_ids: ...# join for stringsresult = ",".join(values)
Async Patterns
# Concurrent executionresults = await asyncio.gather(task1(), task2(), task3())# Resource managementasync with aiohttp.ClientSession() as session:async with session.get(url) as response:data = await response.json()# Concurrency limitsemaphore = 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 oncedef create_app(settings: Settings) -> Service:return Service(repository=PostgresRepository(settings.dsn))# Open/Closed: extend via new types, not editsclass JsonFormat:def export(self, invoice: Invoice) -> str: ...# Interface Segregation: small Protocolsclass Workable(Protocol):def work(self) -> None: ...# Early returndef 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, Fieldclass CreateUserRequest(BaseModel):email: EmailStrage: int = Field(ge=0, le=150)
OOP Patterns
# Dataclass@dataclassclass User:name: stremail: str# Protocol for interfacesclass Repository(Protocol):def get(self, id: str) -> Entity: ...# Property@propertydef 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)