claudient 0.1.0

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

@@ -0,0 +1,285 @@
+> 🇪🇸 Esta es la traducción en español. [Versión en inglés](../django.md).
+
+# Skill de Django
+
+## Cuándo activar
+- Construir un proyecto Django con modelos ORM, migraciones y vistas
+- Configurar serializadores, viewsets y routers de Django REST Framework (DRF)
+- Escribir managers de modelos personalizados o métodos QuerySet
+- Usar señales de Django para efectos secundarios desacoplados
+- Configurar Celery para tareas asíncronas en un proyecto Django
+- Personalizar el admin de Django
+- Escribir pruebas con `django.test.TestCase` o `pytest-django`
+
+## Cuándo NO usar
+- APIs async-first — usar el skill de FastAPI en su lugar
+- Microservicios que no necesitan el ORM o el admin de Django
+- Scripts o CLIs simples — Python puro o Typer
+- Si el proyecto ya usa FastAPI o Flask
+
+## Instrucciones
+
+### Estructura del proyecto
+```
+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
+```
+
+### División de configuración
+```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"  # Siempre establece un modelo de usuario personalizado desde el primer día
+
+# config/settings/production.py
+from .base import *
+DEBUG = False
+ALLOWED_HOSTS = env.list("ALLOWED_HOSTS")
+DATABASES = {"default": env.db("DATABASE_URL")}
+```
+
+### Modelo de usuario personalizado
+```python
+# apps/users/models.py — configurar antes de la primera migración, nunca cambiar después
+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 personalizado
+```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)
+```
+
+### Serializadores 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)
+```
+
+### Configuración del 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
+```
+
+### Señales
+```python
+# apps/users/signals.py — usa señales solo para efectos secundarios verdaderamente desacoplados
+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:
+        # enviar correo
+        pass
+    except Exception as exc:
+        raise self.retry(exc=exc, countdown=60)
+```
+
+### Personalización del 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")}),
+        ("Permisos", {"fields": ("is_active", "is_staff", "is_superuser", "groups")}),
+    )
+    add_fieldsets = (
+        (None, {"fields": ("email", "password1", "password2")}),
+    )
+```
+
+### Optimización de QuerySet
+```python
+# Siempre select_related para campos FK, prefetch_related para M2M/FK inversa
+posts = Post.objects.select_related("author").prefetch_related("tags").filter(published=True)
+
+# Usa only() o defer() para modelos grandes cuando solo necesitas campos específicos
+emails = User.objects.filter(is_active=True).only("email")
+
+# Usa values() para agregaciones de solo lectura — omite la construcción de objetos ORM
+counts = Order.objects.values("status").annotate(count=Count("id"))
+```
+
+### Testing
+```python
+# Estilo 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"
+```
+
+## Ejemplo
+
+**Usuario:** Agregar un modelo `Post` a un proyecto Django con DRF, incluyendo endpoints de lista/create/retrieve, resultados paginados y filtro por `published=True`.
+
+**Salida esperada:**
+- `models.py` — `Post` con `title`, `body`, `author` (FK a User), `published`, `created_at`
+- `serializers.py` — `PostSerializer` con `author` de solo lectura (anidado), `title`/`body`/`published` editables
+- `views.py` — `PostViewSet` con `queryset` filtrado a `published=True` para usuarios no autenticados, permiso `IsAuthenticatedOrReadOnly`, `PageNumberPagination`
+- `urls.py` — router registrado en `/api/posts/`
+
+---
+
+> **Trabaja con nosotros:** Claudient está respaldado por [Uitbreiden](https://uitbreiden.com/) — construimos productos de IA y soluciones B2B con comunidades de desarrolladores. [uitbreiden.com](https://uitbreiden.com/)

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

@@ -0,0 +1,244 @@
+> 🇪🇸 Esta es la traducción en español. [Versión en inglés](../fastapi.md).
+
+# Skill de FastAPI
+
+## Cuándo activar
+- Construir una API REST o asíncrona en Python con FastAPI
+- Definir modelos de solicitud/respuesta con Pydantic
+- Configurar inyección de dependencias con `Depends`
+- Escribir manejadores de rutas asíncronos con SQLAlchemy o drivers de BD asíncronos
+- Agregar middleware (CORS, autenticación, logging, limitación de tasa)
+- Configurar tareas en segundo plano o workers de Celery
+- Personalizar la documentación OpenAPI (etiquetas, descripciones, esquemas de respuesta)
+- Escribir pruebas de integración con `TestClient` o `AsyncClient`
+- Estructurar un proyecto FastAPI multi-módulo
+
+## Cuándo NO usar
+- Proyectos Django/DRF — usar el skill de Django
+- Codebases solo síncronos donde la sobrecarga asíncrona no está justificada
+- Scripts simples que no necesitan HTTP — usar Python puro
+- APIs gRPC o GraphQL — capa de transporte y esquema diferente
+
+## Instrucciones
+
+### Estructura del proyecto
+```
+app/
+├── main.py              # Factoría de la aplicación FastAPI
+├── core/
+│   ├── config.py        # Configuración mediante pydantic-settings
+│   └── security.py      # Utilidades JWT y hashing
+├── api/
+│   ├── deps.py          # Funciones Depends() compartidas
+│   └── v1/
+│       ├── router.py    # Agregador APIRouter
+│       └── endpoints/
+│           ├── users.py
+│           └── items.py
+├── models/              # Modelos ORM de SQLAlchemy
+├── schemas/             # Esquemas de solicitud/respuesta Pydantic
+├── crud/                # Funciones de operación en BD (no ORM, no HTTP)
+└── db/
+    ├── session.py       # Factoría AsyncSession
+    └── base.py          # Importación de la base declarativa
+```
+
+### Factoría de la aplicación
+```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()
+```
+
+### Configuración con 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()
+```
+
+### Dependencia de sesión SQLAlchemy asíncrona
+```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
+```
+
+### Manejadores de rutas
+```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)
+```
+
+### Inyección de dependencias para autenticación
+```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
+```
+
+### Tareas en segundo plano
+```python
+# Usa BackgroundTasks de FastAPI para tareas ligeras fire-and-forget (sin resultado necesario)
+@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"}
+
+# Usa Celery para: reintentos, seguimiento de resultados, programación, tareas entre servicios
+```
+
+### Middleware CORS
+```python
+from fastapi.middleware.cors import CORSMiddleware
+
+app.add_middleware(
+    CORSMiddleware,
+    allow_origins=settings.ALLOWED_ORIGINS,  # Nunca ["*"] en producción
+    allow_credentials=True,
+    allow_methods=["*"],
+    allow_headers=["*"],
+)
+```
+
+### Manejadores de excepciones personalizados
+```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"
+```
+
+### Patrones comunes de Pydantic
+```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}  # reemplaza orm_mode = True
+```
+
+## Ejemplo
+
+**Usuario:** Construir un endpoint FastAPI para crear una publicación de blog, autenticada con JWT, guardando en PostgreSQL con SQLAlchemy async.
+
+**Estructura esperada:**
+- `schemas/post.py` — `PostCreate(BaseModel)`, `PostResponse(BaseModel)` con `from_attributes=True`
+- `models/post.py` — modelo ORM `Post` con `id`, `title`, `body`, `author_id` (FK a User), `created_at`
+- `crud/post.py` — función asíncrona `create(db, *, obj_in, author_id)`
+- `api/v1/endpoints/posts.py` — `POST /posts/` con `Depends(get_current_user)` y `Depends(get_db)`
+- `api/v1/router.py` — incluir router de posts
+
+---
+
+> **Trabaja con nosotros:** Claudient está respaldado por [Uitbreiden](https://uitbreiden.com/) — construimos productos de IA y soluciones B2B con comunidades de desarrolladores. [uitbreiden.com](https://uitbreiden.com/)