avibebuilder/claude-prime / .claude/starter-skills/backend-fastapi-python
backend-fastapi-python
UnverifiedUse this skill for any Python backend work in this project: building FastAPI endpoints, writing service functions, defining Pydantic/SQLModel schemas, running Alembic migrations, or debugging 422 errors. Essential for authentication and authorization patterns — setting up get_current_user, is_superuser checks, admin-only guards, role-based access, and dependency injection chains like Depends(). Also covers middleware, background tasks, async SQLAlchemy sessions, ORM relationship loading, and request/response design. Activate whenever the question involves Python API code, FastAPI patterns, or backend architecture in this codebase. Not for frontend, Docker, CI/CD, or infrastructure.
| File | Kind | Size |
|---|---|---|
| SKILL.md | skill md | 3.9 KB |
| references/auth.md | markdown | 5.5 KB |
| references/configuration.md | markdown | 3.5 KB |
| references/database.md | markdown | 3.9 KB |
| references/dependencies.md | markdown | 4.4 KB |
| references/error-handling.md | markdown | 4.7 KB |
| references/file-structure.md | markdown | 3.8 KB |
| references/middleware.md | markdown | 4.9 KB |
| references/models.md | markdown | 3.9 KB |
| references/routing.md | markdown | 4.5 KB |
| references/schemas.md | markdown | 4.3 KB |
| references/services.md | markdown | 5.1 KB |
references/services.md
View on GitHub# Services
## Service Layer Pattern
Services contain business logic. They are **stateless functions**, not classes.
## Structure
```python
# src/modules/auth/auth_service.py
from sqlalchemy import select
from sqlalchemy.ext.asyncio import AsyncSession
from src.core.exceptions import AppException
from src.models.user_model import User
from src.modules.auth.auth_constants import AuthErrorCode
from src.modules.auth.auth_schemas import RegisterRequest
from src.modules.auth.auth_utils import hash_password, verify_password
async def get_user_by_email(db: AsyncSession, email: str) -> User | None:
result = await db.execute(select(User).where(User.email == email))
return result.scalar_one_or_none()
async def get_user_by_id(db: AsyncSession, user_id: str) -> User | None:
result = await db.execute(select(User).where(User.id == user_id))
return result.scalar_one_or_none()
async def register_user(db: AsyncSession, data: RegisterRequest) -> User:
# Check existing
existing = await get_user_by_email(db, data.email)
if existing:
raise AppException(400, "Email already registered", AuthErrorCode.USER_EXISTED)
# Create user
hashed = hash_password(data.password)
user = User(
email=data.email,
first_name=data.first_name,
last_name=data.last_name,
hashed_password=hashed,
auth_providers=["email"],
)
db.add(user)
await db.commit()
await db.refresh(user)
return user
async def authenticate_user(db: AsyncSession, email: str, password: str) -> User:
user = await get_user_by_email(db, email)
if not user or not user.hashed_password:
raise AppException(401, "Invalid email or password")
if not verify_password(password, user.hashed_password):
raise AppException(401, "Invalid email or password")
if not user.is_active:
raise AppException(403, "Account is inactive")
# Update last sign in
user.last_sign_in_at = datetime.now(UTC)
db.add(user)
await db.commit()
return user
```
## Key Conventions
### Function Signature
```python
# First parameter is always db session
async def some_operation(
db: AsyncSession,
# Required parameters
entity_id: str,
data: SomeRequest,
# Optional parameters with defaults
include_deleted: bool = False,
) -> ReturnType:
...
```
### Error Handling
```python
from src.core.exceptions import AppException
from src.modules.users.user_constants import UserErrorCode
async def update_user(db: AsyncSession, user_id: str, data: UpdateUserRequest) -> User:
user = await get_user_by_id(db, user_id)
if not user:
raise AppException(404, "User not found", UserErrorCode.USER_NOT_FOUND)
# Business rule validation
if user_id == current_admin_id and data.is_admin is False:
raise AppException(
400,
"Cannot demote yourself",
UserErrorCode.CANNOT_SELF_MODIFY,
)
# Update and save
...
```
### Using FastCRUD for Complex Queries
```python
from fastcrud import FastCRUD
from typing import Any
user_crud: FastCRUD = FastCRUD(User)
async def list_users_paginated(
db: AsyncSession,
page: int,
limit: int,
q: str | None,
is_active: bool | None,
sort_by: list[str],
) -> dict:
# Build filters
filters: dict[str, Any] = {}
if is_active is not None:
filters["is_active"] = is_active
# OR search across fields
if q:
filters["_or"] = {
"first_name__ilike": f"%{q}%",
"last_name__ilike": f"%{q}%",
"email__ilike": f"%{q}%",
}
# Parse sort
sort_columns = []
sort_orders = []
for item in sort_by:
if ":" in item:
col, order = item.split(":", 1)
sort_columns.append(col)
sort_orders.append(order)
offset = (page - 1) * limit
return await user_crud.get_multi(
db=db,
offset=offset,
limit=limit,
sort_columns=sort_columns or ["created_at"],
sort_orders=sort_orders or ["desc"],
return_total_count=True,
**filters,
)
```
## Utils vs Services
**Services** (`*_service.py`):
- Business logic
- Database operations
- Validation rules
**Utils** (`*_utils.py`):
- Pure functions
- No database
- Reusable helpers
```python
# src/modules/auth/auth_utils.py (utils - no db)
import bcrypt
from jose import jwt
def hash_password(password: str) -> str:
return bcrypt.hashpw(password.encode(), bcrypt.gensalt()).decode()
def verify_password(plain: str, hashed: str) -> bool:
return bcrypt.checkpw(plain.encode(), hashed.encode())
def create_access_token(user_id: str) -> str:
payload = {"sub": user_id, "exp": expire, "type": "access"}
return jwt.encode(payload, secret, algorithm=algorithm)
```
## Best Practices
1. **Stateless functions** - No class instances, no shared state
2. **db as first param** - Consistent signature across all services
3. **Raise AppException** - With error codes for frontend
4. **Single responsibility** - One function, one operation
5. **Composition** - Services can call other services
6. **No HTTP concerns** - No Request/Response objects in services
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| writing-skillsobra/superpowersUse when creating new skills, editing existing skills, or verifying skills work before deployment | Stars: 318k | Updated | Claude CodeCodex | Unverified | Install |
| xlsxanthropics/skillsUse this skill any time a spreadsheet file is the primary input or output. This means any task where the user wants to: open, read, edit, or fix an existing .xlsx, .xlsm, .xltx, .csv, or .tsv file (e.g., adding columns, computing formulas, formatting, charting, cleaning messy data); create a new spreadsheet from scratch or from other data sources; or convert between tabular file formats. Trigger especially when the user references a spreadsheet file by name or path — even casually (like "the xlsx in my downloads") — and wants something done to it or produced from it. Also trigger for cleaning or restructuring messy tabular data files (malformed rows, misplaced headers, junk data) into proper spreadsheets. The deliverable must be a spreadsheet file. Do NOT trigger when the primary deliverable is a Word document, HTML report, standalone Python script, database pipeline, or Google Sheets API integration, even if tabular data is involved. | Stars: 196k | Updated | Claude CodeCodex | Verified | Install |
| shipping-and-launchaddyosmani/agent-skillsPrepares production launches. Use when preparing to deploy to production, or when asking what needs to be in place before shipping. Use when you need a pre-launch checklist, when setting up monitoring, when planning a staged rollout, or when you need a rollback strategy. | Stars: 118k | Updated | Claude CodeCodex | Verified | Install |
| childhoodthedotmack/claude-memBabysit a shipped release after merge, publication, or deployment. Verify published packages, production behavior, installed plugins, and late CI or user reports until the observation window is clean; use babysit for PR readiness before release. | Stars: 117k | Updated | Claude CodeCodex | Unverified | Install |