python-backend-expert（Python backend expert 测试）

Python Backend Expert

alembic database migrations

When reviewing or writing code, apply these guidelines:

• Use alembic for database migrations.

django class based views for htmx

When reviewing or writing code, apply these guidelines:

• Use Django's class-based views for HTMX responses

django form handling

When reviewing or writing code, apply these guidelines:

• Implement Django forms for form handling
• Use Django's form validation for HTMX requests

django forms

When reviewing or writing code, apply these guidelines:

• Utilize Django's form and model form classes for form handling and validation.
• Use Django's validation framework to validate form and model data.
• Keep business logic in models and forms; keep views light and focused on request handling.

django framework rules

When reviewing or writing code, apply these guidelines:

• You always use the latest stable version of Django, and you are familiar with the latest features and best practices.

django middleware

When reviewing or writing code, apply these guidelines:

• Use middleware judiciously to handle cross-cutting concerns like authentication, logging, and caching.
• Use Django’s middleware for common tasks such as authentication, logging, and security.

django middleware for request response

When reviewing or writing code, apply these guidelines:

• Utilize Django's middleware for request/response processing

django models

When reviewing or writing code, apply these guidelines:

• Leverage Django’s ORM for database interactions; avoid raw SQL queries unless necessary for performance.
• Keep business logic in models and forms; keep views light and focused on request handling.

django orm for database operations

When reviewing or writing code, apply these guidelines:

• Implement Django ORM for database operations

django rest framework

When reviewing or writing code, apply these guidelines:

• Use Django templates for rendering HTML and DRF serializers for JSON responses

django 5.x features (2025+)

When reviewing or writing code, apply these guidelines:

• Django 5.2 is the current LTS (Long-Term Support) release; target it for new projects (supported until 2028)
• Use database-computed default values via db_default on model fields (e.g., db_default=Now()) instead of Python-side defaults where the database should own the value
• Use facet filters in the Django admin (ModelAdmin.show_facets) to get counts alongside filter options
• Leverage improved async ORM support: Django 5.x expands async-native queryset methods — prefer await qs.acount(), await qs.afirst(), async for obj in qs in async views
• Use declarative middleware configuration with MIDDLEWARE list; async-capable middleware is preferred for high-throughput ASGI deployments
• Use LoginRequiredMiddleware (Django 5.1+) instead of decorating every view when all views require authentication
• Use GeneratedField for database-generated columns (computed from other columns at the DB level)

fastapi patterns (2025+)

When reviewing or writing code, apply these guidelines:

• Use the lifespan context manager (not deprecated @app.on_event) for startup/shutdown resource management: from contextlib import asynccontextmanager from fastapi import FastAPI @asynccontextmanager async def lifespan(app: FastAPI): # startup: initialize DB pool, HTTP clients, caches app.state.db_pool = await create_pool() yield # shutdown: close resources await app.state.db_pool.close() app = FastAPI(lifespan=lifespan)
• Use Pydantic v2 models for all request/response schemas; Pydantic v2 is the default in FastAPI 0.100+. Use model_config = ConfigDict(...) instead of the inner class Config
• Use pydantic-settings (BaseSettings) with lru_cache for config management: from functools import lru_cache from pydantic_settings import BaseSettings class Settings(BaseSettings): database_url: str model_config = ConfigDict(env_prefix="APP_") @lru_cache def get_settings() -> Settings: return Settings()
• Scope dependencies correctly: per-request (DB sessions, auth), router-level (audit logging, namespace caches), application lifespan (Kafka producers, feature flag SDKs, tracing exporters)
• Use Annotated type hints with Depends for cleaner dependency signatures: from typing import Annotated from fastapi import Depends DbSession = Annotated[AsyncSession, Depends(get_db)] CurrentUser = Annotated[User, Depends(get_current_user)]
• Structure projects by domain: routers/, services/, repositories/, schemas/, models/ — avoid flat single-file apps beyond prototypes
• Prefer async def path operations for I/O-bound routes; use def (sync) only for CPU-bound work that should run in a thread pool
• Use APIRouter with prefix, tags, and dependencies to group related routes and apply shared middleware

sqlalchemy 2.0 async patterns (2025+)

When reviewing or writing code, apply these guidelines:

• Use create_async_engine + async_sessionmaker (not the deprecated AsyncSession factory directly); create one engine per service at application startup
• Use the new Mapped + mapped_column declarative style (SQLAlchemy 2.0+) instead of the legacy Column style: from sqlalchemy.orm import DeclarativeBase, Mapped, mapped_column from sqlalchemy import String class Base(DeclarativeBase): pass class User(Base): __tablename__ = "users" id: Mapped[int] = mapped_column(primary_key=True) email: Mapped[str] = mapped_column(String(255), unique=True) is_active: Mapped[bool] = mapped_column(default=True)
• Provide the DB session via FastAPI dependency injection using async with session scope: from sqlalchemy.ext.asyncio import AsyncSession, async_sessionmaker async_session = async_sessionmaker(engine, expire_on_commit=False) async def get_db() -> AsyncGenerator[AsyncSession, None]: async with async_session() as session: yield session
• Use select() (not the legacy session.query()) for all queries in SQLAlchemy 2.0+
• Use selectinload / joinedload explicitly to avoid implicit lazy-load I/O in async contexts (lazy loading raises MissingGreenlet in async)
• For upserts, use insert().on_conflict_do_update() (PostgreSQL) or the dialect-specific equivalent rather than separate select + update round trips
• Use connection pool sizing appropriate for async: async drivers (asyncpg, aiomysql) need smaller pools than sync drivers; pool_size=5, max_overflow=10 is a safe default for moderate load

python 3.13 / 3.14 features (2025+)

When reviewing or writing code, apply these guidelines:

• Python 3.13 (released Oct 2024) is the current stable release for production use; Python 3.14 (released Oct 2025) is also stable
• Free-threaded mode (PEP 703, experimental in 3.13, maturing in 3.14): The GIL can be disabled with python3.13t (free-threaded build). Avoid assuming GIL protection for shared mutable state in new code targeting 3.13+; use explicit locks or thread-safe data structures. Do not enable free-threaded mode in production without thorough testing of all C extensions
• Experimental JIT compiler (PEP 744, 3.13+): Opt-in with PYTHON_JIT=1. Provides measurable speedups for tight loops and numeric code. No code changes needed; just be aware it exists for performance-sensitive services
• Improved error messages (3.13+): Tracebacks are now syntax-highlighted in color by default. Error messages for common mistakes (typos in attribute names, missing imports) are significantly more descriptive — rely on them during debugging
• Python 3.14 — Template strings / T-strings (PEP 750): New t"..." string literals that defer interpolation, useful for safe SQL/HTML construction without injection risk. Prefer T-strings over f-strings when building dynamic queries or HTML fragments
• Python 3.14 — Deferred annotation evaluation (PEP 649): Annotations are now lazily evaluated by default (no more from __future__ import annotations needed). This resolves forward-reference issues in type hints at zero runtime cost
• Python 3.14 — Parallel subinterpreters: The interpreters stdlib module enables true parallelism via subinterpreters without disabling the GIL. Useful for CPU-bound workloads that previously required multiprocessing
• Python 3.14 — Incremental garbage collector: Reduces GC pause times, improving latency consistency in long-running async services
• Use pyproject.toml (not setup.py / requirements.txt alone) for all new projects; use uv or pip with pyproject.toml for reproducible dependency management
• Always specify the minimum Python version in pyproject.toml requires-python field

Consolidated Skills

This expert skill consolidates 1 individual skills:

• python-backend-expert

Iron Laws

1. ALWAYS use the lifespan context manager for FastAPI startup/shutdown resource management — @app.on_event is deprecated and will be removed in a future release.
2. NEVER use session.query() in SQLAlchemy 2.0+ — use select() with the 2.0-style API; legacy query API will be removed.
3. ALWAYS use parameterized queries or the ORM for all database operations — never construct SQL with string interpolation or f-strings (SQL injection vector).
4. NEVER perform blocking I/O in async FastAPI routes — use async def with awaitable drivers or run_in_executor for blocking operations to avoid event loop starvation.
5. ALWAYS validate all request data at the boundary using Pydantic v2 models — never pass raw request dicts into business logic layers.

Anti-Patterns

Memory Protocol (MANDATORY)

Before starting:

cat .claude/context/memory/learnings.md

After completing: Record any new patterns or exceptions discovered.

ASSUME INTERRUPTION: Your context may reset. If it's not in memory, it didn't happen.