phenobarbital/antigravity-config/python-standards

Python Standards

Core Rule: Use uv for all package operations, pytest for testing, ruff for formatting/linting. Write self-documenting code with minimal comments.

When to use this skill

• When installing or managing Python packages and dependencies
• When writing or running unit tests, integration tests, or test suites
• When formatting Python code or fixing linting issues
• When adding type hints or running type checking
• When writing function/method docstrings
• When organizing imports in Python files
• When deciding whether to create a new Python file or extend existing ones
• When setting up code quality checks (linting, formatting, type checking)
• When running coverage reports or analyzing test results
• When ensuring code follows Python best practices and tooling standards

Package Management - uv Only

MANDATORY: Use `uv` for all Python package operations. Never use `pip` directly.

# Installing packages
uv pip install package-name
uv pip install -r requirements.txt
 
# Package information
uv pip list
uv pip show package-name
 
# Running Python scripts/modules
uv run python script.py
uv run pytest
 
# Add a new package:
uv add package-name

Why uv: Faster dependency resolution, better lock file management, project standard for consistency.

If you catch yourself typing `pip`: Stop and use uv pip instead.

Testing with pytest

Run tests using `uv run pytest`:

uv run pytest                                      # All tests
uv run pytest -m unit                              # Unit tests only
uv run pytest -m integration                       # Integration tests only
uv run pytest tests/unit/test_module.py            # Specific file
uv run pytest tests/unit/test_module.py::test_name # Specific test
uv run pytest -v                                   # Verbose output
uv run pytest -s                                   # Show print statements
uv run pytest --cov=src --cov-report=term-missing  # Coverage report
uv run pytest --cov-fail-under=80                  # Enforce 80% coverage

Test markers: Use @pytest.mark.unit and @pytest.mark.integration to categorize tests.

Code Quality Tools

Ruff (Linting & Formatting):

ruff check .           # Check for issues
ruff check . --fix     # Auto-fix issues
ruff format .          # Format all code

Type Checking:

basedpyright src            # Type checker

Run quality checks before marking work complete. Use getDiagnostics tool to verify no errors.

Code Style

Docstrings

Use concise one-line docstrings for most functions:

def calculate_discount(price: float, rate: float) -> float:
    """Calculate discounted price by applying rate."""
    return price * (1 - rate)

Multi-line docstrings only for complex functions:

def process_payment(order_id: str, payment_method: str) -> PaymentResult:
    """
    Process payment for order using specified method.
    Validates payment method, charges customer, updates order status,
    and sends confirmation email. Rolls back on any failure.
    Args:
        order_id: str
        payment_method: str
    Returns:
        PaymentResult: 
    """
    # Implementation

Don't document obvious behavior:

# BAD - docstring adds no value
def get_user_email(user_id: str) -> str:
    """Get the email address for a user by their ID."""
# GOOD - name is self-explanatory
def get_user_email(user_id: str) -> str:
    return db.query(User).filter_by(id=user_id).first().email

Comments

Write self-documenting code. Minimize inline comments.

Use clear names instead of comments:

# BAD - comment explains unclear code
# Check if user has permission
if u.r == 'admin' or u.r == 'moderator':
# GOOD - code explains itself
if user.is_admin() or user.is_moderator():

Use comments only for:

• Complex algorithms requiring explanation
• Non-obvious business logic or domain rules
• Explaining why a certain approach was taken
• Definition of arguments and return values
• Workarounds for external library bugs (include issue link)
• Performance optimizations that sacrifice clarity

Import Organization

Order: Standard library → Third-party → Local application

# Standard library
import os
from datetime import datetime
# Third-party
import pytest
from sqlalchemy import Column, Integer
# Local application
from app.models import User
from app.services import EmailService
# Relative imports:
from .main import MainApp

Ruff automatically organizes imports. Run ruff check . --fix to sort.

Remove unused imports immediately. Use getDiagnostics to identify them.

Type Hints

Add type hints to all function signatures:

# Required
def process_order(order_id: str, user_id: int) -> Order:
    pass
# Not required for simple private methods
def _format_price(amount):
    return f"${amount:.2f}"

Use modern type syntax (Python 3.10+):

# Good
def get_users(ids: list[int]) -> list[User]:
    pass
# Avoid (old style)
from typing import List
def get_users(ids: List[int]) -> List[User]:
    pass

File Organization

Prefer editing existing files over creating new ones.

Before creating a new Python file, ask:

1. Can this fit in an existing module?
2. Is there a related file to extend?
3. Does this truly need to be separate?

Benefits: Reduces file sprawl, maintains coherent structure, easier navigation.

When to create new files:

• New model/entity with distinct responsibility
• New service layer for separate domain
• Test file for new module
• Clear architectural boundary

Common Patterns

Avoid bare `except`:

# BAD
try:
    process()
except:
    pass
# GOOD
try:
    process()
except ValueError as e:
    logger.error(f"Invalid value: {e}")
    raise

Use context managers for resources:

# GOOD
with open(file_path) as f:
    data = f.read()
# GOOD
with db.session() as session:
    user = session.query(User).first()

Prefer pathlib over os.path:

# GOOD
from pathlib import Path
config_path = Path(__file__).parent / "config.yaml"
# Avoid
import os
config_path = os.path.join(os.path.dirname(__file__), "config.yaml")

Verification Checklist

Before marking Python work complete:

• [ ] Used uv for all package operations (not pip)
• [ ] All tests pass: uv run pytest
• [ ] Code formatted: ruff format .
• [ ] No linting issues: ruff check .
• [ ] Type checking passes: basedpyright src
• [ ] No unused imports (check with getDiagnostics)
• [ ] Docstrings added to public functions
• [ ] Type hints on function signatures
• [ ] Coverage ≥ 80%: uv run pytest --cov=src --cov-fail-under=80

Quick Reference