AGENT SKILL

trove-python

Python/FastAPI coding conventions and best practices. Auto-activates when working with Python files. Covers async patterns, type hints, SQLAlchemy, Pydantic, logging, and error handling.

License 许可
MIT
所属仓库
bravew/trove
最近更新
2026-11-12
Stars
★ 10
Forks
1

01 前言 Front Matter

name
trove-python
paths
[ "**/*.py" ]
metadata
{ "trove-category": "code", "trove-category-label": "Code" }
description
Python/FastAPI coding conventions and best practices. Auto-activates when working with Python files. Covers async patterns, type hints, SQLAlchemy, Pydantic, logging, and error handling.
when_to_use
python conventions; fastapi patterns; async python; pydantic models
user-invocable
false

03 SKILL.md 正文

<!-- AUTO-GENERATED from SKILL.md.tmpl — do not edit directly --> <!-- Regenerate: bun run build:skills -->

Session Init

This skill ships Trove conventions. Prefer existing project patterns over generic best practices when they conflict.

Python / FastAPI Conventions

Imports

  • Top-level imports only — never inline imports inside functions
  • Organization: stdlib → third-party → local (isort-compatible)
  • Use from __future__ import annotations when needed for forward refs

Type Hints

  • All function signatures must have type hints (params + return)
  • Use from typing import for complex types (Optional, Union, etc.)
  • Pydantic models for all request/response schemas
  • Prefer X | None over Optional[X] (Python 3.10+)

Async Patterns (CRITICAL)

Never call blocking I/O in async functions:

# BAD — blocks the event loop
async def get_user(user_id: str):
    response = requests.get(f"/users/{user_id}")  # BLOCKING!
    time.sleep(1)  # BLOCKING!

# GOOD — non-blocking
async def get_user(user_id: str):
    async with httpx.AsyncClient() as client:
        response = await client.get(f"/users/{user_id}")
    await asyncio.sleep(1)
  • Use httpx.AsyncClient for HTTP (not requests)
  • Use asyncio.sleep for delays (not time.sleep)
  • Use async with for context managers (DB sessions, HTTP clients)

Logging

# INFO/DEBUG — f-strings are fine (fast path, no Sentry indexing needed)
logger.info(f"Processing user {user_id}")

# WARNING/ERROR — static message + extra dict (enables Sentry grouping)
logger.warning("Payment failed", extra={"user_id": user_id, "amount": amount})

# EXCEPTION — use in except blocks (auto-captures stack trace)
try:
    await process()
except Exception:
    logger.exception("Processing failed", extra={"user_id": user_id})

Never use sentry_sdk.capture_exception() — use logger.exception() instead.

SQLAlchemy Async

# Always use async session context manager
async with get_async_session() as session:
    result = await session.execute(select(User).where(User.id == user_id))
    user = result.scalar_one_or_none()

# Eager loading to avoid N+1
stmt = select(User).options(selectinload(User.posts)).where(User.id == user_id)

Error Handling

  • Use specific exception types, not bare except:
  • FastAPI: raise HTTPException with appropriate status codes
  • Service layer: raise domain-specific exceptions
  • Never silently swallow exceptions

Pydantic Models

class UserResponse(BaseModel):
    model_config = ConfigDict(from_attributes=True)

    id: str
    name: str
    email: str | None = None
    created_at: datetime

AI Gotchas

  • httpx vs requests: Always use httpx.AsyncClient in async code
  • datetime: Use datetime.now(tz=UTC) not datetime.utcnow() (deprecated)
  • Pydantic v2: Use model_config = ConfigDict(...) not class Config:
  • SQLAlchemy 2.0: Use select() not session.query()

04 同仓库更多 Skills