Python Anti Patterns

Python Anti-Patterns Checklist

A reference checklist of common mistakes and anti-patterns in Python code. Review this before finalizing implementations to catch issues early.

When to Use This Skill

• Reviewing code before merge
• Debugging mysterious issues
• Teaching or learning Python best practices
• Establishing team coding standards
• Refactoring legacy code

Note: This skill focuses on what to avoid. For guidance on positive patterns and architecture, see python-design-patterns.

With design & code-style skills: Turning on Ruff, ty, tests, Pydantic, repositories, and clear layers (python-code-style) is not premature abstraction�those are quality gates everyone pays once. The rule of three in design patterns applies to deduplicating business logic, not to postponing linters or boundaries. Prefer duplication over a wrong shared primitive; avoid duplication across public API surfaces when it hides inconsistent validation.

HTTP clients: Prefer HTTPX for sync and async HTTP�the same default as the Official FastAPI skill and FastAPI other-tools (HTTPX over Requests). Examples below use HTTPX so they stay consistent with python-testing-patterns.

Infrastructure Anti-Patterns

Scattered Timeout/Retry Logic

# BAD: Timeout logic duplicated everywhere
import httpx

def fetch_user(client: httpx.Client, user_id: str) -> httpx.Response | None:
    try:
        return client.get(f"/users/{user_id}", timeout=30.0)
    except httpx.TimeoutException:
        logger.warning("Timeout fetching user")
        return None

def fetch_orders(client: httpx.Client, user_id: str) -> httpx.Response | None:
    try:
        return client.get(f"/users/{user_id}/orders", timeout=30.0)
    except httpx.TimeoutException:
        logger.warning("Timeout fetching orders")
        return None

Fix: Centralize in decorators or client wrappers.

# GOOD: Centralized retry logic on a pooled client (HTTPX + tenacity)
import httpx
from tenacity import retry, stop_after_attempt, wait_exponential

client = httpx.Client(base_url="https://api.example.com", timeout=30.0)

@retry(stop=stop_after_attempt(3), wait=wait_exponential())
def http_get(path: str) -> httpx.Response:
    response = client.get(path)
    response.raise_for_status()
    return response

Double Retry

# BAD: Retrying at multiple layers
@retry(max_attempts=3)  # Application retry
def call_service():
    return client.request()  # Client also has retry configured!

Fix: Retry at one layer only. Know your infrastructure's retry behavior.

Hard-Coded Configuration

# BAD: Secrets and config in code
DB_HOST = "prod-db.example.com"
API_KEY = "sk-12345"

def connect():
    return psycopg.connect(f"host={DB_HOST}...")

Fix: Use environment variables with typed settings.

# GOOD
from pydantic_settings import BaseSettings

class Settings(BaseSettings):
    db_host: str = Field(alias="DB_HOST")
    api_key: str = Field(alias="API_KEY")

settings = Settings()

Architecture Anti-Patterns

Exposed Internal Types

# BAD: Leaking the SQLModel table to the API
from sqlmodel import SQLModel, Field

class User(SQLModel, table=True):  # table model � internal
    id: str = Field(primary_key=True)
    email: str
    password_hash: str  # must never leak

@app.get("/users/{id}")
def get_user(id: str, session: SessionDep) -> User:  # leaks password_hash
    return session.get(User, id)

Fix: Use DTOs / response models.

# GOOD: public schema built from the table instance (Pydantic v2 + SQLModel)
from pydantic import ConfigDict
from sqlmodel import SQLModel

class UserPublic(SQLModel):
    model_config = ConfigDict(from_attributes=True)
    id: str
    email: str

@app.get("/users/{id}")
def get_user(id: str, session: SessionDep) -> UserPublic:
    user = session.get(User, id)
    return UserPublic.model_validate(user)

Aligned with fastapi-config-01 and fastapi/other-tools � prefer SQLModel over SQLAlchemy, and keep table models (table=True) out of response signatures.

Mixed I/O and Business Logic

# BAD: SQL embedded in business logic
from sqlmodel import select

async def calculate_discount(user_id: str, session: AsyncSession) -> float:
    user = await session.get(User, user_id)
    orders = (await session.exec(select(Order).where(Order.user_id == user_id))).all()
    # Business logic mixed with data access
    if len(orders) > 10:
        return 0.15
    return 0.0

Fix: Repository pattern. Keep business logic pure.

# GOOD
def calculate_discount(user: User, orders: list[Order]) -> float:
    # Pure business logic, easily testable
    if len(orders) > 10:
        return 0.15
    return 0.0

Error Handling Anti-Patterns

Bare Exception Handling

Scope: The anti-pattern is silent broad catches � except Exception: pass (or except: with no re-raise, no log, no typed outcome). Three intentional uses of except Exception are not covered by this rule:

1. Transaction / cleanup context managers that roll back and then raise � see python-resource-management Pattern 3.
2. Batch processors that capture per-item failures into a BatchResult � see python-error-handling Pattern 7 and the Ignored Partial Failures section below.
3. fail_safe decorators that log and return a default for non-critical, degradable paths � see python-resilience Pattern 9.

In all three, the catch is broad on purpose and every failure is either re-raised, captured, or logged. What this rule forbids is swallowing without a trace.

# BAD: Swallowing all exceptions
try:
    process()
except Exception:
    pass  # Silent failure - bugs hidden forever

Fix: Catch specific exceptions. Log or handle appropriately.

# GOOD
try:
    process()
except ConnectionError as e:
    logger.warning("Connection failed, will retry", error=str(e))
    raise
except ValueError as e:
    logger.error("Invalid input", error=str(e))
    raise BadRequestError(str(e))

Ignored Partial Failures

# BAD: Stops on first error
def process_batch(items):
    results = []
    for item in items:
        result = process(item)  # Raises on error - batch aborted
        results.append(result)
    return results

Fix: Capture both successes and failures. Use the generic BatchResult[T] shape defined in python-error-handling Pattern 7 so both skills return the same type.

# GOOD
from python_error_handling import BatchResult  # same shape as python-error-handling

def process_batch(items: list[Item]) -> BatchResult[ProcessedItem]:
    succeeded: dict[int, ProcessedItem] = {}
    failed: dict[int, Exception] = {}
    for idx, item in enumerate(items):
        try:
            succeeded[idx] = process(item)
        except Exception as e:
            failed[idx] = e
    return BatchResult(succeeded=succeeded, failed=failed)

Missing Input Validation

# BAD: No validation
def create_user(data: dict):
    return User(**data)  # Crashes deep in code on bad input

Fix: Validate early at API boundaries.

# GOOD
def create_user(data: dict) -> User:
    validated = CreateUserInput.model_validate(data)
    return User.from_input(validated)

Resource Anti-Patterns

Unclosed Resources

# BAD: File never closed
def read_file(path):
    f = open(path)
    return f.read()  # What if this raises?

Fix: Use context managers.

# GOOD
def read_file(path):
    with open(path) as f:
        return f.read()

Blocking in Async

Scope: This rule is about blocking calls inside an async def. It does not say you must make every FastAPI path operation async. The Official FastAPI skill (Async vs Sync path operations) explicitly recommends plain def by default � FastAPI runs it in a threadpool, so blocking libraries are safe there. Only once a function is async def does the anti-pattern below apply.

# BAD: Blocks the entire event loop
import time
import httpx

async def fetch_data(url: str):
    time.sleep(1)  # Blocks everything!
    httpx.get(url, timeout=30.0)  # sync HTTP in async def � also blocks!

Fix (preferred in FastAPI projects): use async def with async-native libraries.

# GOOD
import asyncio
import httpx

async def fetch_data(url: str):
    await asyncio.sleep(1)
    async with httpx.AsyncClient(timeout=30.0) as client:
        response = await client.get(url)

Fix (when a blocking library is unavoidable): bridge with Asyncer. Per fastapi/other-tools, prefer Asyncer (asyncify / syncify) over AnyIO or raw asyncio for crossing the sync/async boundary.

from asyncer import asyncify

async def fetch_via_blocking_lib(url: str) -> dict:
    return await asyncify(blocking_lib.get)(url)

If Asyncer isn't a dependency, fall back to asyncio.to_thread(...) (see async-python-patterns).

Type Safety Anti-Patterns

Missing Type Hints

# BAD: No types
def process(data):
    return data["value"] * 2

Fix: Annotate all public functions.

# GOOD
def process(data: dict[str, int]) -> int:
    return data["value"] * 2

Untyped Collections

# BAD: Generic list without type parameter
def get_users() -> list:
    ...

Fix: Use type parameters.

# GOOD
def get_users() -> list[User]:
    ...

Testing Anti-Patterns

Only Testing Happy Paths

# BAD: Only tests success case
def test_create_user():
    user = service.create_user(valid_data)
    assert user.id is not None

Fix: Test error conditions and edge cases.

# GOOD
def test_create_user_success():
    user = service.create_user(valid_data)
    assert user.id is not None

def test_create_user_invalid_email():
    with pytest.raises(ValueError, match="Invalid email"):
        service.create_user(invalid_email_data)

def test_create_user_duplicate_email():
    service.create_user(valid_data)
    with pytest.raises(ConflictError):
        service.create_user(valid_data)

Over-Mocking

# BAD: Mocking everything
def test_user_service():
    mock_repo = Mock()
    mock_cache = Mock()
    mock_logger = Mock()
    mock_metrics = Mock()
    # Test doesn't verify real behavior

Fix: Use integration tests for critical paths. Mock only external services.

Quick Review Checklist

Before finalizing code, verify:

• No scattered timeout/retry logic (centralized)
• No double retry (app + infrastructure)
• No hard-coded configuration or secrets
• No exposed internal types (ORM models, protobufs)
• No mixed I/O and business logic
• No bare except Exception: pass
• No ignored partial failures in batches
• No missing input validation
• No unclosed resources (using context managers)
• No blocking calls in async code
• All public functions have type hints
• Collections have type parameters
• Error paths are tested
• Edge cases are covered

Common Fixes Summary