tomevault-io Python Best Practices
Code Style
| Rule | Guideline |
|---|---|
| Formatter | ruff format or black |
| Linter | ruff check with strict rules |
| Type hints | Always for public APIs |
| Docstrings | Google or NumPy style |
Type Hints
def process(items: list[str], max_count: int = 10) -> dict[str, int]: ...
def find_user(user_id: int) -> User | None: ...
Error Handling
| Rule | Guideline |
|---|---|
| Specific exceptions | Never bare except: |
| Context managers | Use with for resources |
| Early return | Validate inputs, fail fast |
# Good
try:
result = process(data)
except ValidationError as e:
logger.warning(f"Validation failed: {e}")
return default
Project Structure
src/package_name/
├── __init__.py
├── core/
└── py.typed
tests/
├── conftest.py
└── test_*.py
pyproject.toml
Common Patterns
| Pattern | Usage |
|---|---|
@dataclass |
Data containers |
@property |
Computed attributes |
| Generators | Memory-efficient iteration |
functools.cache |
Memoization |
Anti-Patterns
| Avoid | Use Instead |
|---|---|
| Mutable default args | None default, create inside |
import * |
Explicit imports |
| Global state | Dependency injection |
# Bad: def add(item, items=[]): ...
# Good:
def add(item, items=None):
items = items or []
items.append(item)
return items
Tools
| Tool | Purpose |
|---|---|
pytest |
Testing |
ruff |
Linting + formatting |
mypy |
Type checking |
uv |
Dependencies |
Converted and distributed by TomeVault — claim your Tome and manage your conversions.