Python Coding Patterns

Mandatory

Rules in this section block task completion when violated.

No Bare Except

Never silently swallow exceptions. A bare except: or except Exception: pass hides bugs and makes debugging impossible.

# BAD
try:
    result = process(data)
except:
    pass

# BAD — catches too broadly and discards the error
try:
    result = process(data)
except Exception:
    pass

# GOOD — catch specific exception, log with context, re-raise or handle
try:
    result = process(data)
except ValueError as e:
    logger.error("Invalid data in process: %s", e)
    raise
except IOError as e:
    logger.error("IO failure in process: %s", e)
    raise RuntimeError("Processing unavailable") from e

No print() for Logging

Never use print() to record application events. print() has no log level, no timestamp, and cannot be filtered or routed in production.

# BAD
print(f"Processing user {user_id}")
print("ERROR: " + str(e))

# GOOD
import logging
logger = logging.getLogger(__name__)

logger.info("Processing user %s", user_id)
logger.error("Failed to process user %s: %s", user_id, e)

Recommended

Rules in this section are flagged in review but do not block submission.

Naming Conventions (Python)

Type Hints

Recommended for all new code. Not a hard gate — absence does not block review. Static analysis (mypy, pyright) is optional but encouraged on CI.

# Recommended — explicit contracts
from typing import Optional

def get_user(user_id: int) -> Optional[User]:
    ...

def create_order(request: OrderRequest) -> OrderResponse:
    ...

# Acceptable when type is unambiguous from context
def _double(x):
    return x * 2

Function and File Size

• Function body: ≤ 50 lines, cyclomatic complexity ≤ 10
• Single file: ≤ 500 lines — split by responsibility when approaching the limit

Project Structure

Standard layout for a Python backend service:

project/
├── src/                    # optional src layout
│   ├── __init__.py
│   ├── api/                # route handlers / controllers
│   ├── services/           # business logic
│   ├── models/             # domain models / Pydantic schemas
│   ├── repositories/       # data access layer
│   └── config.py
├── tests/
│   ├── conftest.py         # shared fixtures
│   ├── unit/
│   └── integration/
├── requirements.txt        # or pyproject.toml / uv.lock
└── .env.example

__init__.py:

• Required in each package directory for explicit package declaration
• Keep empty or limit to public re-exports — no business logic inside

Package management is project-specific: pip + venv, Poetry, and uv are all acceptable. Do not prescribe a tool unless the project already has one established.

Logging

Obtain a module-level logger once per file. Never configure logging inside library/module code (only in application entry point).

import logging

# One logger per module — do this at module level
logger = logging.getLogger(__name__)


def process_order(order_id: int) -> None:
    logger.info("Processing order %s", order_id)

    try:
        result = _run(order_id)
        logger.info("Order %s completed: %s", order_id, result.status)
    except ProcessingError as e:
        # Pass exc_info=True (or the exception) to capture full traceback
        logger.error("Order %s failed: %s", order_id, e, exc_info=True)
        raise

Log level guide: