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 annotationswhen needed for forward refs
Type Hints
- All function signatures must have type hints (params + return)
- Use
from typing importfor complex types (Optional,Union, etc.) - Pydantic models for all request/response schemas
- Prefer
X | NoneoverOptional[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.AsyncClientfor HTTP (notrequests) - Use
asyncio.sleepfor delays (nottime.sleep) - Use
async withfor 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
HTTPExceptionwith 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.AsyncClientin async code - datetime: Use
datetime.now(tz=UTC)notdatetime.utcnow()(deprecated) - Pydantic v2: Use
model_config = ConfigDict(...)notclass Config: - SQLAlchemy 2.0: Use
select()notsession.query()
04 同仓库更多 Skills
using-trove
Skill discipline anchor for the Trove marketplace. Loaded once per session; routes the agent to the right trove-* skill before code, planning, review, or git actions.
trove-write-skill
Skill authoring workflow. Use when creating or updating a Codex or Trove skill, including rubrics, tasks, metadata, and validation.
trove-worktree
Git worktree workflow for spikes, risky experiments, and broad refactors that should not disturb the user's current branch.
trove-why
Reconstruct design rationale and decision history from evidence — source control, issue tracker (Linear), docs (Notion), chat (Slack), error tracking (Sentry) — with calibrated confidence. Use for "why does X work this way", "why did we pick Y", regressions, and postmortems. Use trove-explain for how it works now.
trove-verify
Completion verification workflow. Use before claiming done, fixed, complete, ready, or shipped.
trove-unslop
Cut AI tells from writing — PR descriptions, release notes, specs, commit bodies, and replies. Use before finalizing prose, or when the user asks to clean up, de-slop, or make text sound human.