claudient 0.1.0

package/skills/backend/python/fastapi.md

@@ -0,0 +1,242 @@
+# FastAPI Skill
+
+## When to activate
+- Building a Python REST or async API with FastAPI
+- Defining Pydantic request/response models
+- Setting up dependency injection with `Depends`
+- Writing async route handlers with SQLAlchemy or async DB drivers
+- Adding middleware (CORS, auth, logging, rate limiting)
+- Configuring background tasks or Celery workers
+- Customizing OpenAPI docs (tags, descriptions, response schemas)
+- Writing integration tests with `TestClient` or `AsyncClient`
+- Structuring a multi-module FastAPI project
+
+## When NOT to use
+- Django/DRF projects — use the Django skill
+- Synchronous-only codebases where async overhead is not justified
+- Simple scripts that don't need HTTP — use plain Python
+- gRPC or GraphQL APIs — different transport and schema layer
+
+## Instructions
+
+### Project structure
+```
+app/
+├── main.py              # FastAPI app factory
+├── core/
+│   ├── config.py        # Settings via pydantic-settings
+│   └── security.py      # JWT, hashing utilities
+├── api/
+│   ├── deps.py          # Shared Depends() functions
+│   └── v1/
+│       ├── router.py    # APIRouter aggregator
+│       └── endpoints/
+│           ├── users.py
+│           └── items.py
+├── models/              # SQLAlchemy ORM models
+├── schemas/             # Pydantic request/response schemas
+├── crud/                # DB operation functions (not ORM, not HTTP)
+└── db/
+    ├── session.py       # AsyncSession factory
+    └── base.py          # Declarative base import
+```
+
+### App factory
+```python
+# main.py
+from fastapi import FastAPI
+from app.api.v1.router import api_router
+from app.core.config import settings
+
+def create_app() -> FastAPI:
+    app = FastAPI(
+        title=settings.PROJECT_NAME,
+        openapi_url=f"{settings.API_V1_STR}/openapi.json",
+        docs_url="/docs" if settings.ENVIRONMENT != "production" else None,
+    )
+    app.include_router(api_router, prefix=settings.API_V1_STR)
+    return app
+
+app = create_app()
+```
+
+### Settings with pydantic-settings
+```python
+# core/config.py
+from pydantic_settings import BaseSettings
+
+class Settings(BaseSettings):
+    PROJECT_NAME: str = "MyAPI"
+    API_V1_STR: str = "/api/v1"
+    DATABASE_URL: str
+    SECRET_KEY: str
+    ENVIRONMENT: str = "development"
+    ACCESS_TOKEN_EXPIRE_MINUTES: int = 30
+
+    class Config:
+        env_file = ".env"
+        case_sensitive = True
+
+settings = Settings()
+```
+
+### Async SQLAlchemy session dependency
+```python
+# db/session.py
+from sqlalchemy.ext.asyncio import AsyncSession, create_async_engine, async_sessionmaker
+
+engine = create_async_engine(settings.DATABASE_URL, echo=False)
+AsyncSessionLocal = async_sessionmaker(engine, expire_on_commit=False)
+
+# api/deps.py
+async def get_db() -> AsyncIterator[AsyncSession]:
+    async with AsyncSessionLocal() as session:
+        try:
+            yield session
+            await session.commit()
+        except Exception:
+            await session.rollback()
+            raise
+```
+
+### Route handlers
+```python
+# api/v1/endpoints/users.py
+from fastapi import APIRouter, Depends, HTTPException, status
+from sqlalchemy.ext.asyncio import AsyncSession
+from app.api.deps import get_db, get_current_user
+from app.crud import user as crud_user
+from app.schemas.user import UserCreate, UserResponse
+
+router = APIRouter(prefix="/users", tags=["users"])
+
+@router.post("/", response_model=UserResponse, status_code=status.HTTP_201_CREATED)
+async def create_user(
+    payload: UserCreate,
+    db: AsyncSession = Depends(get_db),
+) -> UserResponse:
+    if await crud_user.get_by_email(db, email=payload.email):
+        raise HTTPException(status_code=400, detail="Email already registered")
+    return await crud_user.create(db, obj_in=payload)
+```
+
+### Dependency injection for auth
+```python
+# api/deps.py
+from fastapi import Depends, HTTPException, status
+from fastapi.security import OAuth2PasswordBearer
+from jose import JWTError, jwt
+
+oauth2_scheme = OAuth2PasswordBearer(tokenUrl="/api/v1/auth/token")
+
+async def get_current_user(
+    token: str = Depends(oauth2_scheme),
+    db: AsyncSession = Depends(get_db),
+) -> User:
+    try:
+        payload = jwt.decode(token, settings.SECRET_KEY, algorithms=["HS256"])
+        user_id: str = payload.get("sub")
+        if user_id is None:
+            raise credentials_exception
+    except JWTError:
+        raise HTTPException(status_code=401, detail="Invalid credentials")
+    user = await crud_user.get(db, id=user_id)
+    if user is None:
+        raise HTTPException(status_code=404, detail="User not found")
+    return user
+```
+
+### Background tasks
+```python
+# Use FastAPI's BackgroundTasks for lightweight fire-and-forget (no result needed)
+@router.post("/send-email")
+async def send_email_endpoint(
+    payload: EmailPayload,
+    background_tasks: BackgroundTasks,
+):
+    background_tasks.add_task(send_email, payload.to, payload.subject, payload.body)
+    return {"status": "queued"}
+
+# Use Celery for: retries, result tracking, scheduling, cross-service tasks
+```
+
+### CORS middleware
+```python
+from fastapi.middleware.cors import CORSMiddleware
+
+app.add_middleware(
+    CORSMiddleware,
+    allow_origins=settings.ALLOWED_ORIGINS,  # Never ["*"] in production
+    allow_credentials=True,
+    allow_methods=["*"],
+    allow_headers=["*"],
+)
+```
+
+### Custom exception handlers
+```python
+from fastapi.responses import JSONResponse
+
+@app.exception_handler(ValueError)
+async def value_error_handler(request: Request, exc: ValueError) -> JSONResponse:
+    return JSONResponse(status_code=422, content={"detail": str(exc)})
+```
+
+### Testing
+```python
+# tests/conftest.py
+import pytest
+from httpx import AsyncClient, ASGITransport
+from app.main import app
+
+@pytest.fixture
+async def client() -> AsyncIterator[AsyncClient]:
+    async with AsyncClient(
+        transport=ASGITransport(app=app), base_url="http://test"
+    ) as ac:
+        yield ac
+
+# tests/test_users.py
+@pytest.mark.asyncio
+async def test_create_user(client: AsyncClient, db_session):
+    resp = await client.post("/api/v1/users/", json={"email": "a@b.com", "password": "secret"})
+    assert resp.status_code == 201
+    assert resp.json()["email"] == "a@b.com"
+```
+
+### Common Pydantic patterns
+```python
+from pydantic import BaseModel, EmailStr, field_validator, model_validator
+
+class UserCreate(BaseModel):
+    email: EmailStr
+    password: str
+
+    @field_validator("password")
+    @classmethod
+    def password_strength(cls, v: str) -> str:
+        if len(v) < 8:
+            raise ValueError("Password must be at least 8 characters")
+        return v
+
+class UserResponse(BaseModel):
+    id: int
+    email: EmailStr
+
+    model_config = {"from_attributes": True}  # replaces orm_mode = True
+```
+
+## Example
+
+**User:** Build a FastAPI endpoint to create a blog post, authenticated with JWT, saving to PostgreSQL with SQLAlchemy async.
+
+**Expected structure:**
+- `schemas/post.py` — `PostCreate(BaseModel)`, `PostResponse(BaseModel)` with `from_attributes=True`
+- `models/post.py` — `Post` ORM model with `id`, `title`, `body`, `author_id` (FK to User), `created_at`
+- `crud/post.py` — `create(db, *, obj_in, author_id)` async function
+- `api/v1/endpoints/posts.py` — `POST /posts/` with `Depends(get_current_user)` and `Depends(get_db)`
+- `api/v1/router.py` — include posts router
+
+---
+
+> **Work with us:** Claudient is backed by [Uitbreiden](https://uitbreiden.com/) — we build AI products and B2B solutions with developer communities. [uitbreiden.com](https://uitbreiden.com/)

package/skills/backend/python/fr/django.md

@@ -0,0 +1,285 @@
+> 🇫🇷 This is the French translation. [English version](../django.md).
+
+# Compétence Django
+
+## Quand activer
+- Construire un projet Django avec des modèles ORM, des migrations et des vues
+- Configurer les sérialiseurs, viewsets et routers Django REST Framework (DRF)
+- Rédiger des managers de modèles personnalisés ou des méthodes QuerySet
+- Utiliser les signaux Django pour des effets secondaires découplés
+- Configurer Celery pour les tâches async dans un projet Django
+- Personnaliser l'admin Django
+- Rédiger des tests avec `django.test.TestCase` ou `pytest-django`
+
+## Quand NE PAS utiliser
+- APIs async en priorité — utiliser la compétence FastAPI à la place
+- Microservices qui n'ont pas besoin de l'ORM ou de l'admin Django
+- Scripts ou CLIs simples — Python simple ou Typer
+- Si le projet utilise déjà FastAPI ou Flask
+
+## Instructions
+
+### Structure du projet
+```
+project_name/
+├── manage.py
+├── config/
+│   ├── settings/
+│   │   ├── base.py
+│   │   ├── development.py
+│   │   └── production.py
+│   ├── urls.py
+│   └── wsgi.py
+├── apps/
+│   └── users/
+│       ├── models.py
+│       ├── serializers.py
+│       ├── views.py
+│       ├── urls.py
+│       ├── admin.py
+│       ├── managers.py
+│       └── tests/
+└── requirements/
+    ├── base.txt
+    ├── development.txt
+    └── production.txt
+```
+
+### Séparation des paramètres
+```python
+# config/settings/base.py
+from pathlib import Path
+BASE_DIR = Path(__file__).resolve().parent.parent.parent
+
+INSTALLED_APPS = [
+    "django.contrib.admin",
+    "django.contrib.auth",
+    "django.contrib.contenttypes",
+    "rest_framework",
+    "apps.users",
+]
+
+AUTH_USER_MODEL = "users.User"  # Toujours définir un modèle utilisateur personnalisé dès le début
+
+# config/settings/production.py
+from .base import *
+DEBUG = False
+ALLOWED_HOSTS = env.list("ALLOWED_HOSTS")
+DATABASES = {"default": env.db("DATABASE_URL")}
+```
+
+### Modèle User personnalisé
+```python
+# apps/users/models.py — à configurer avant la première migration, ne jamais changer ensuite
+from django.contrib.auth.models import AbstractBaseUser, PermissionsMixin
+from django.db import models
+from .managers import UserManager
+
+class User(AbstractBaseUser, PermissionsMixin):
+    email = models.EmailField(unique=True)
+    is_staff = models.BooleanField(default=False)
+    is_active = models.BooleanField(default=True)
+    created_at = models.DateTimeField(auto_now_add=True)
+
+    USERNAME_FIELD = "email"
+    REQUIRED_FIELDS = []
+    objects = UserManager()
+```
+
+### Manager personnalisé
+```python
+# apps/users/managers.py
+from django.contrib.auth.base_user import BaseUserManager
+
+class UserManager(BaseUserManager):
+    def create_user(self, email: str, password: str, **extra_fields):
+        if not email:
+            raise ValueError("Email is required")
+        email = self.normalize_email(email)
+        user = self.model(email=email, **extra_fields)
+        user.set_password(password)
+        user.save()
+        return user
+
+    def create_superuser(self, email: str, password: str, **extra_fields):
+        extra_fields.setdefault("is_staff", True)
+        extra_fields.setdefault("is_superuser", True)
+        return self.create_user(email, password, **extra_fields)
+
+    def active(self):
+        return self.get_queryset().filter(is_active=True)
+```
+
+### Sérialiseurs DRF
+```python
+# apps/users/serializers.py
+from rest_framework import serializers
+from .models import User
+
+class UserCreateSerializer(serializers.ModelSerializer):
+    password = serializers.CharField(write_only=True, min_length=8)
+
+    class Meta:
+        model = User
+        fields = ["id", "email", "password"]
+
+    def create(self, validated_data: dict) -> User:
+        return User.objects.create_user(**validated_data)
+
+class UserSerializer(serializers.ModelSerializer):
+    class Meta:
+        model = User
+        fields = ["id", "email", "created_at"]
+        read_only_fields = ["id", "created_at"]
+```
+
+### ViewSets DRF
+```python
+# apps/users/views.py
+from rest_framework import viewsets, permissions, status
+from rest_framework.decorators import action
+from rest_framework.response import Response
+from .models import User
+from .serializers import UserSerializer, UserCreateSerializer
+
+class UserViewSet(viewsets.ModelViewSet):
+    queryset = User.objects.active()
+    permission_classes = [permissions.IsAuthenticated]
+
+    def get_serializer_class(self):
+        if self.action == "create":
+            return UserCreateSerializer
+        return UserSerializer
+
+    def get_permissions(self):
+        if self.action == "create":
+            return [permissions.AllowAny()]
+        return super().get_permissions()
+
+    @action(detail=False, methods=["get"])
+    def me(self, request):
+        return Response(UserSerializer(request.user).data)
+```
+
+### Configuration du Router
+```python
+# apps/users/urls.py
+from rest_framework.routers import DefaultRouter
+from .views import UserViewSet
+
+router = DefaultRouter()
+router.register("users", UserViewSet, basename="user")
+urlpatterns = router.urls
+```
+
+### Signaux
+```python
+# apps/users/signals.py — utiliser les signaux uniquement pour des effets secondaires vraiment découplés
+from django.db.models.signals import post_save
+from django.dispatch import receiver
+from .models import User
+
+@receiver(post_save, sender=User)
+def send_welcome_email(sender, instance: User, created: bool, **kwargs):
+    if created:
+        send_email_task.delay(instance.email, "welcome")
+
+# apps/users/apps.py
+class UsersConfig(AppConfig):
+    name = "apps.users"
+    def ready(self):
+        import apps.users.signals  # noqa: F401
+```
+
+### Celery
+```python
+# config/celery.py
+from celery import Celery
+import os
+
+os.environ.setdefault("DJANGO_SETTINGS_MODULE", "config.settings.production")
+app = Celery("project_name")
+app.config_from_object("django.conf:settings", namespace="CELERY")
+app.autodiscover_tasks()
+
+# apps/users/tasks.py
+from config.celery import app
+
+@app.task(bind=True, max_retries=3)
+def send_email_task(self, to_email: str, template: str):
+    try:
+        # envoyer l'email
+        pass
+    except Exception as exc:
+        raise self.retry(exc=exc, countdown=60)
+```
+
+### Personnalisation de l'admin
+```python
+# apps/users/admin.py
+from django.contrib import admin
+from django.contrib.auth.admin import UserAdmin as BaseUserAdmin
+from .models import User
+
+@admin.register(User)
+class UserAdmin(BaseUserAdmin):
+    list_display = ["email", "is_active", "is_staff", "created_at"]
+    list_filter = ["is_active", "is_staff"]
+    search_fields = ["email"]
+    ordering = ["-created_at"]
+    fieldsets = (
+        (None, {"fields": ("email", "password")}),
+        ("Permissions", {"fields": ("is_active", "is_staff", "is_superuser", "groups")}),
+    )
+    add_fieldsets = (
+        (None, {"fields": ("email", "password1", "password2")}),
+    )
+```
+
+### Optimisation des QuerySet
+```python
+# Toujours select_related pour les champs FK, prefetch_related pour M2M/FK inverse
+posts = Post.objects.select_related("author").prefetch_related("tags").filter(published=True)
+
+# Utiliser only() ou defer() pour les grands modèles quand vous n'avez besoin que de champs spécifiques
+emails = User.objects.filter(is_active=True).only("email")
+
+# Utiliser values() pour les agrégations en lecture seule — évite la construction d'objets ORM
+counts = Order.objects.values("status").annotate(count=Count("id"))
+```
+
+### Tests
+```python
+# Style pytest-django
+import pytest
+from rest_framework.test import APIClient
+
+@pytest.fixture
+def api_client():
+    return APIClient()
+
+@pytest.fixture
+def authenticated_client(api_client, user):
+    api_client.force_authenticate(user=user)
+    return api_client
+
+@pytest.mark.django_db
+def test_create_user(api_client):
+    resp = api_client.post("/api/users/", {"email": "a@b.com", "password": "strongpass"})
+    assert resp.status_code == 201
+    assert resp.data["email"] == "a@b.com"
+```
+
+## Exemple
+
+**Utilisateur :** Ajouter un modèle `Post` à un projet Django avec DRF, incluant des endpoints liste/création/récupération, des résultats paginés et un filtre par `published=True`.
+
+**Sortie attendue :**
+- `models.py` — `Post` avec `title`, `body`, `author` (FK vers User), `published`, `created_at`
+- `serializers.py` — `PostSerializer` avec `author` en lecture seule (imbriqué), `title`/`body`/`published` modifiables
+- `views.py` — `PostViewSet` avec `queryset` filtré à `published=True` pour les utilisateurs non authentifiés, permission `IsAuthenticatedOrReadOnly`, `PageNumberPagination`
+- `urls.py` — router enregistré à `/api/posts/`
+
+---
+
+> **Travaillez avec nous :** Claudient est soutenu par [Uitbreiden](https://uitbreiden.com/) — nous construisons des produits IA et des solutions B2B avec des communautés de développeurs. [uitbreiden.com](https://uitbreiden.com/)