claudient 0.1.0

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

@@ -0,0 +1,244 @@
+> 🇫🇷 This is the French translation. [English version](../fastapi.md).
+
+# Compétence FastAPI
+
+## Quand activer
+- Construire une API Python REST ou async avec FastAPI
+- Définir des modèles Pydantic de requête/réponse
+- Configurer l'injection de dépendances avec `Depends`
+- Rédiger des gestionnaires de routes async avec SQLAlchemy ou des drivers DB async
+- Ajouter des middlewares (CORS, auth, logging, rate limiting)
+- Configurer des tâches en arrière-plan ou des workers Celery
+- Personnaliser les docs OpenAPI (tags, descriptions, schémas de réponse)
+- Rédiger des tests d'intégration avec `TestClient` ou `AsyncClient`
+- Structurer un projet FastAPI multi-modules
+
+## Quand NE PAS utiliser
+- Projets Django/DRF — utiliser la compétence Django
+- Bases de code uniquement synchrones où le surcoût async n'est pas justifié
+- Scripts simples qui n'ont pas besoin de HTTP — utiliser du Python simple
+- APIs gRPC ou GraphQL — transport et couche de schéma différents
+
+## Instructions
+
+### Structure du projet
+```
+app/
+├── main.py              # Fabrique d'application FastAPI
+├── core/
+│   ├── config.py        # Paramètres via pydantic-settings
+│   └── security.py      # JWT, utilitaires de hachage
+├── api/
+│   ├── deps.py          # Fonctions Depends() partagées
+│   └── v1/
+│       ├── router.py    # Agrégateur APIRouter
+│       └── endpoints/
+│           ├── users.py
+│           └── items.py
+├── models/              # Modèles ORM SQLAlchemy
+├── schemas/             # Schémas Pydantic de requête/réponse
+├── crud/                # Fonctions d'opérations DB (pas ORM, pas HTTP)
+└── db/
+    ├── session.py       # Fabrique AsyncSession
+    └── base.py          # Import de la base déclarative
+```
+
+### Fabrique d'application
+```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()
+```
+
+### Paramètres avec 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()
+```
+
+### Dépendance de session SQLAlchemy async
+```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
+```
+
+### Gestionnaires de routes
+```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)
+```
+
+### Injection de dépendances pour l'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
+```
+
+### Tâches en arrière-plan
+```python
+# Utiliser BackgroundTasks de FastAPI pour les tâches légères fire-and-forget (pas de résultat nécessaire)
+@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"}
+
+# Utiliser Celery pour : les réessais, le suivi des résultats, la planification, les tâches inter-services
+```
+
+### Middleware CORS
+```python
+from fastapi.middleware.cors import CORSMiddleware
+
+app.add_middleware(
+    CORSMiddleware,
+    allow_origins=settings.ALLOWED_ORIGINS,  # Jamais ["*"] en production
+    allow_credentials=True,
+    allow_methods=["*"],
+    allow_headers=["*"],
+)
+```
+
+### Gestionnaires d'exceptions personnalisés
+```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)})
+```
+
+### Tests
+```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"
+```
+
+### Patterns Pydantic courants
+```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}  # remplace orm_mode = True
+```
+
+## Exemple
+
+**Utilisateur :** Construire un endpoint FastAPI pour créer un article de blog, authentifié avec JWT, sauvegardant dans PostgreSQL avec SQLAlchemy async.
+
+**Structure attendue :**
+- `schemas/post.py` — `PostCreate(BaseModel)`, `PostResponse(BaseModel)` avec `from_attributes=True`
+- `models/post.py` — modèle ORM `Post` avec `id`, `title`, `body`, `author_id` (FK vers User), `created_at`
+- `crud/post.py` — fonction async `create(db, *, obj_in, author_id)`
+- `api/v1/endpoints/posts.py` — `POST /posts/` avec `Depends(get_current_user)` et `Depends(get_db)`
+- `api/v1/router.py` — inclure le router 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/)

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

@@ -0,0 +1,285 @@
+> 🇳🇱 Dit is de Nederlandse vertaling. [Engelse versie](../django.md).
+
+# Django Skill
+
+## Wanneer te activeren
+- Een Django-project bouwen met ORM-modellen, migraties en views
+- Django REST Framework (DRF) serializers, viewsets en routers instellen
+- Aangepaste model-managers of QuerySet-methoden schrijven
+- Django-signalen gebruiken voor ontkoppelde neveneffecten
+- Celery instellen voor async taken in een Django-project
+- De Django-admin aanpassen
+- Tests schrijven met `django.test.TestCase` of `pytest-django`
+
+## Wanneer NIET te gebruiken
+- Async-first API's — gebruik in plaats daarvan de FastAPI skill
+- Microservices die Django's ORM of admin niet nodig hebben
+- Eenvoudige scripts of CLI's — gewone Python of Typer
+- Als het project al FastAPI of Flask gebruikt
+
+## Instructies
+
+### Projectindeling
+```
+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
+```
+
+### Instellingen splitsen
+```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"  # Stel altijd een aangepast gebruikersmodel in vanaf dag één
+
+# config/settings/production.py
+from .base import *
+DEBUG = False
+ALLOWED_HOSTS = env.list("ALLOWED_HOSTS")
+DATABASES = {"default": env.db("DATABASE_URL")}
+```
+
+### Aangepast User-model
+```python
+# apps/users/models.py — instellen vóór eerste migratie, daarna nooit meer wijzigen
+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()
+```
+
+### Aangepaste Manager
+```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)
+```
+
+### DRF Serializers
+```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"]
+```
+
+### DRF ViewSets
+```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)
+```
+
+### Router-instelling
+```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
+```
+
+### Signalen
+```python
+# apps/users/signals.py — gebruik signalen alleen voor werkelijk ontkoppelde neveneffecten
+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:
+        # e-mail verzenden
+        pass
+    except Exception as exc:
+        raise self.retry(exc=exc, countdown=60)
+```
+
+### Admin-aanpassing
+```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")}),
+    )
+```
+
+### QuerySet-optimalisatie
+```python
+# Gebruik altijd select_related voor FK-velden, prefetch_related voor M2M/reverse FK
+posts = Post.objects.select_related("author").prefetch_related("tags").filter(published=True)
+
+# Gebruik only() of defer() voor grote modellen wanneer je alleen specifieke velden nodig hebt
+emails = User.objects.filter(is_active=True).only("email")
+
+# Gebruik values() voor alleen-lezen aggregaties — slaat ORM-objectconstructie over
+counts = Order.objects.values("status").annotate(count=Count("id"))
+```
+
+### Testen
+```python
+# pytest-django-stijl
+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"
+```
+
+## Voorbeeld
+
+**Gebruiker:** Voeg een `Post`-model toe aan een Django-project met DRF, inclusief lijst/aanmaken/ophalen-endpoints, gepagineerde resultaten en filter op `published=True`.
+
+**Verwachte output:**
+- `models.py` — `Post` met `title`, `body`, `author` (FK naar User), `published`, `created_at`
+- `serializers.py` — `PostSerializer` met alleen-lezen `author` (genest), beschrijfbare `title`/`body`/`published`
+- `views.py` — `PostViewSet` met `queryset` gefilterd op `published=True` voor niet-geauthenticeerde gebruikers, `IsAuthenticatedOrReadOnly`-toestemming, `PageNumberPagination`
+- `urls.py` — router geregistreerd op `/api/posts/`
+
+---
+
+> **Werk met ons:** Claudient wordt ondersteund door [Uitbreiden](https://uitbreiden.com/) — we bouwen AI-producten en B2B-oplossingen met ontwikkelaarsgemeenschappen. [uitbreiden.com](https://uitbreiden.com/)