python-conventions

Python Conventions

Style Rules

• Type hints on all function parameters and return values
• Docstrings with Args / Returns / Raises sections on every public function
• Constants: UPPERCASE_SNAKE_CASE at module level
• async/await for all I/O — never mix sync blocking calls in async context
• Imports: stdlib → third-party → local, blank line between groups
• Explicit annotations: List[str], Dict[str, Any], Optional[T]

File Section Template

# =============================================================================
# CONSTANTS AND CONFIGURATION
# =============================================================================

# =============================================================================
# GLOBAL VARIABLES
# =============================================================================

# =============================================================================
# CLASSES/FUNCTIONS
# =============================================================================

FastAPI Endpoint Template

@router.post("/endpoint", response_model=ResponseModel)
async def endpoint_handler(
    request_data: RequestModel,
    current_user: Dict[str, Any] = Depends(get_current_user),
    db: AsyncSession = Depends(get_database),
) -> ResponseModel:
    """
    Short description.

    Args:
        request_data: Description
        current_user: Authenticated user from JWT
        db: PostgreSQL database session

    Returns:
        ResponseModel with result data

    Raises:
        APIError: 400/404/422/500 depending on failure type
    """
    try:
        # implementation
        return ResponseModel(...)
    except APIError:
        raise  # re-raise typed errors unchanged
    except Exception as e:
        logger.error(f"Operation failed: {e}", exc_info=True)
        raise internal_error("Operation failed")

Key rules:

• except APIError: raise — never catch and re-wrap typed errors
• Use raise internal_error(...) not raise HTTPException(500, ...)
• Always log the exception before re-raising internal errors
• Check resource ownership before modifying it