gregoryg/aipihkal/python-dev

Python Development

Prime Directive: Verify Before You Deliver

Every piece of Python code you write or edit MUST be tested before presenting it to the user.

After writing or modifying a .py file:

1. Syntax check: python3 -c "import ast; ast.parse(open('FILE').read())" or python3 -m py_compile FILE
2. Additional Code check: use ruff check if available
3. Smoke run: Execute the file or its entry point: python3 FILE
4. Run tests: If tests exist, run them: python3 -m pytest TEST_FILE -v

If any step fails, fix the code and re-test before responding. Do not present broken code and ask the user to debug it. You have shell access—use it.

Style & Conventions

• Python version: 3.12+ unless the project specifies otherwise.
• Indentation: 4 spaces (PEP 8).
• Type hints: Always. Use str | None union syntax (3.10+), not Optional[str].
• Naming:
• Modules/files: lowercase_with_underscores
• Classes: PascalCase
• Functions/variables: snake_case
• Constants: UPPER_SNAKE_CASE
• Tests: test_*.py files, test_* functions
• Docstrings: Google-style, short. One-liner for trivial functions.

def fetch_user(user_id: int) -> dict:
    """Fetch a user record by ID.
    Args:
        user_id: The unique user identifier.
    Returns:
        A dict with user fields.
    Raises:
        ValueError: If user_id is negative.
    """

• Formatting: Use black if available (black --check FILE). Do not obsess if unavailable—PEP 8 compliance is sufficient.
• Imports: stdlib → third-party → local, separated by blank lines. Prefer explicit imports over star imports.

Testing Patterns

• Prefer pytest over unittest unless the project already uses unittest.
• Keep test functions focused: one behavior per test.
• Use fixtures for shared setup; avoid deep inheritance in test classes.
• Name tests descriptively: test_fetch_user_returns_none_for_missing_id.

Error Handling

• Catch specific exceptions, not bare except:.
• Use raise ... from e to preserve tracebacks.
• Validate inputs early; fail fast with clear messages.

When Editing Existing Code

• Read the surrounding code first to match existing style.
• Run the project's existing test suite after changes.
• If no tests exist for the changed code, write at least one.