tomevault-io 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
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-pure-functions | Prefer pure functions without side effects |
| design-early-return | Reduce nesting with early returns |
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
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
class Service:
def __init__(self, repository: Repository) -> None:
self.repository = repository
# Early return
def process(data: Data | None) -> Result:
if data is None:
return Result.empty()
# main logic here
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)
Converted and distributed by TomeVault — claim your Tome and manage your conversions.