| name | python |
| description | Python development patterns for this project. Use when writing new Python code, refactoring, or setting up modules. Focuses on type hints, import organization (no barrel imports), ruff integration, and script execution patterns. |
Python Development
Core Practices
| Practice | Rule |
|---|---|
| No barrel imports | Import directly from modules, don't re-export everything |
| Type hints | Always use str, int, dict[str, Any], etc. |
| Ruff | Run ruff check --fix && ruff format before commit |
| Script execution | Use python script.py, not chmod +x script.py |
Type Hints
from typing import Any
# Always annotate function signatures
def process_data(data: dict[str, Any], limit: int = 100) -> list[dict]:
...
# Return types required for non-None returns
def get_record(id: str) -> dict[str, Any] | None:
...
Import Organization
Avoid Barrel Imports
Bad (barrel pattern - re-exports from submodules):
# etl/__init__.py
from etl.parsers import * # Don't do this
from etl.models import *
Good (direct imports):
# In consuming code
from etl.parsers import ParserBase
from etl.models import UnifiedPropertyRecord
Group Imports
Order: stdlib → third-party → local
# 1. Standard library
from pathlib import Path
from typing import Any
# 2. Third-party
from pymongo import MongoClient
# 3. Local
from etl.config import CONFIG
Script Execution
Python Scripts
#!/usr/bin/env python3
"""Script description."""
def main():
...
if __name__ == "__main__":
main()
Run with: python script.py
Shell Scripts (with chmod)
#!/usr/bin/env bash
# Only .sh files should be executable
# Rest of script
Make executable: chmod +x script.sh (only for .sh)
Ruff Integration
# Check and fix
ruff check --fix
# Format
ruff format
# Combined
ruff check --fix && ruff format
When to Use References
| Need | Reference |
|---|---|
| Type hint patterns | references/types.md |
| Import patterns | references/imports.md |