@jaimevalasek/aioson 1.3.0

package/template/.aioson/skills/static/django-patterns.md

@@ -0,0 +1,342 @@
+# Django Conventions
+
+> Django's batteries are included for a reason. Use them — don't reinvent the ORM, admin, or auth system.
+
+---
+
+## Project structure
+
+```
+myproject/
+├── manage.py
+├── config/
+│   ├── settings/
+│   │   ├── base.py
+│   │   ├── development.py
+│   │   └── production.py
+│   ├── urls.py
+│   └── wsgi.py
+├── apps/
+│   ├── users/
+│   │   ├── models.py
+│   │   ├── views.py
+│   │   ├── serializers.py
+│   │   ├── urls.py
+│   │   ├── services.py
+│   │   └── tests/
+│   └── core/
+│       └── models.py        # abstract base models (TimestampMixin, etc.)
+├── requirements/
+│   ├── base.txt
+│   ├── development.txt
+│   └── production.txt
+└── templates/
+```
+
+**Convention:** keep apps small and domain-focused. One app = one bounded context.
+
+---
+
+## Models
+
+```python
+# core/models.py — reusable base
+from django.db import models
+
+class TimestampMixin(models.Model):
+    created_at = models.DateTimeField(auto_now_add=True)
+    updated_at = models.DateTimeField(auto_now=True)
+
+    class Meta:
+        abstract = True
+
+# users/models.py
+class UserProfile(TimestampMixin):
+    user = models.OneToOneField(
+        settings.AUTH_USER_MODEL,
+        on_delete=models.CASCADE,
+        related_name='profile'
+    )
+    bio = models.TextField(blank=True)
+
+    class Meta:
+        db_table = 'user_profiles'
+
+    def __str__(self):
+        return f'Profile({self.user.email})'
+```
+
+**Rules:**
+- Always define `__str__`
+- Always set `db_table` in `Meta` (avoid auto-generated names)
+- Use `TimestampMixin` for all models that need audit fields
+- `blank=True` for optional string fields; `null=True` only for non-string nullable fields
+
+---
+
+## Views — use class-based views for CRUD, function-based for one-offs
+
+```python
+# WRONG — fat view with business logic
+def create_order(request):
+    if request.method == 'POST':
+        # 30 lines of business logic here
+        pass
+
+# RIGHT — view delegates to service
+from django.views import View
+from .services import OrderService
+
+class OrderCreateView(LoginRequiredMixin, View):
+    def post(self, request):
+        result = OrderService.create(user=request.user, data=request.POST)
+        if result.ok:
+            return redirect('orders:detail', pk=result.order.id)
+        return render(request, 'orders/create.html', {'errors': result.errors})
+```
+
+**Rules:**
+- Views handle HTTP only: parse request → call service → format response
+- Business logic goes in `services.py`
+- Always use `LoginRequiredMixin` for authenticated views
+- Use `get_object_or_404` instead of manual `try/except`
+
+---
+
+## Services — business logic layer
+
+```python
+# orders/services.py
+from dataclasses import dataclass
+from typing import Optional
+from .models import Order
+
+@dataclass
+class OrderResult:
+    ok: bool
+    order: Optional[Order] = None
+    errors: Optional[dict] = None
+
+class OrderService:
+    @staticmethod
+    def create(user, data) -> OrderResult:
+        # validate
+        if not data.get('items'):
+            return OrderResult(ok=False, errors={'items': 'At least one item required'})
+
+        # execute
+        order = Order.objects.create(
+            user=user,
+            total=sum(item['price'] for item in data['items'])
+        )
+        return OrderResult(ok=True, order=order)
+```
+
+---
+
+## Django REST Framework (DRF)
+
+```python
+# serializers.py
+from rest_framework import serializers
+from .models import Order
+
+class OrderSerializer(serializers.ModelSerializer):
+    class Meta:
+        model = Order
+        fields = ['id', 'status', 'total', 'created_at']
+        read_only_fields = ['id', 'created_at']
+
+    def validate_total(self, value):
+        if value <= 0:
+            raise serializers.ValidationError('Total must be positive')
+        return value
+
+# views.py (DRF)
+from rest_framework import generics, permissions
+from .serializers import OrderSerializer
+
+class OrderListCreateView(generics.ListCreateAPIView):
+    serializer_class = OrderSerializer
+    permission_classes = [permissions.IsAuthenticated]
+
+    def get_queryset(self):
+        return Order.objects.filter(user=self.request.user).select_related('user')
+
+    def perform_create(self, serializer):
+        serializer.save(user=self.request.user)
+```
+
+**Rules:**
+- Always define `read_only_fields` to prevent mass assignment
+- Use `select_related` / `prefetch_related` in `get_queryset` to prevent N+1
+- `perform_create` / `perform_update` for attaching request context (user, etc.)
+
+---
+
+## URL routing
+
+```python
+# apps/orders/urls.py
+from django.urls import path
+from . import views
+
+app_name = 'orders'
+
+urlpatterns = [
+    path('', views.OrderListCreateView.as_view(), name='list'),
+    path('<int:pk>/', views.OrderDetailView.as_view(), name='detail'),
+]
+
+# config/urls.py
+from django.urls import path, include
+
+urlpatterns = [
+    path('admin/', admin.site.urls),
+    path('api/orders/', include('apps.orders.urls')),
+]
+```
+
+**Always use `app_name`** in each app's `urls.py` for namespaced reversals.
+
+---
+
+## Authentication
+
+- **Built-in auth:** `django.contrib.auth` for session-based apps
+- **JWT (API):** `djangorestframework-simplejwt`
+- **Social auth:** `django-allauth`
+- **Permission check:** always use `@login_required` / `LoginRequiredMixin` or DRF `permission_classes`
+
+```python
+# DRF JWT setup
+REST_FRAMEWORK = {
+    'DEFAULT_AUTHENTICATION_CLASSES': [
+        'rest_framework_simplejwt.authentication.JWTAuthentication',
+    ],
+    'DEFAULT_PERMISSION_CLASSES': [
+        'rest_framework.permissions.IsAuthenticated',
+    ],
+}
+```
+
+---
+
+## Database
+
+```python
+# Migrations — never edit after applied to production
+python manage.py makemigrations
+python manage.py migrate
+
+# Always write reversible migrations (define both operations)
+# Squash if > 50 unapplied migrations in dev
+
+# Query optimization
+# BAD — N+1
+orders = Order.objects.all()
+for o in orders:
+    print(o.user.email)  # query per iteration
+
+# GOOD
+orders = Order.objects.select_related('user').all()
+
+# Use .only() for large models when you need few fields
+orders = Order.objects.only('id', 'status', 'total')
+```
+
+---
+
+## Settings split
+
+```python
+# config/settings/base.py — shared
+INSTALLED_APPS = [
+    'django.contrib.admin',
+    'django.contrib.auth',
+    'rest_framework',
+    'apps.users',
+    'apps.orders',
+]
+
+# config/settings/development.py
+from .base import *
+DEBUG = True
+DATABASES = {'default': {'ENGINE': 'django.db.backends.sqlite3', 'NAME': BASE_DIR / 'db.sqlite3'}}
+
+# config/settings/production.py
+from .base import *
+DEBUG = False
+DATABASES = {'default': dj_database_url.config(conn_max_age=600)}
+SECRET_KEY = os.environ['DJANGO_SECRET_KEY']
+```
+
+**Never commit secrets.** Use `python-decouple` or `django-environ`.
+
+---
+
+## Admin
+
+```python
+# orders/admin.py
+from django.contrib import admin
+from .models import Order
+
+@admin.register(Order)
+class OrderAdmin(admin.ModelAdmin):
+    list_display = ['id', 'user', 'status', 'total', 'created_at']
+    list_filter = ['status']
+    search_fields = ['user__email']
+    readonly_fields = ['created_at', 'updated_at']
+    ordering = ['-created_at']
+```
+
+Always register models with `@admin.register` (not `admin.site.register`).
+
+---
+
+## Tests (pytest-django)
+
+```python
+# conftest.py
+import pytest
+from django.contrib.auth import get_user_model
+
+@pytest.fixture
+def user(db):
+    return get_user_model().objects.create_user(
+        email='test@example.com', password='testpass123'
+    )
+
+@pytest.fixture
+def api_client(user):
+    from rest_framework.test import APIClient
+    client = APIClient()
+    client.force_authenticate(user=user)
+    return client
+
+# orders/tests/test_views.py
+import pytest
+
+@pytest.mark.django_db
+def test_create_order_authenticated(api_client):
+    response = api_client.post('/api/orders/', {'items': [{'price': 10}]})
+    assert response.status_code == 201
+
+@pytest.mark.django_db
+def test_create_order_unauthenticated(client):
+    response = client.post('/api/orders/', {})
+    assert response.status_code == 401
+```
+
+**Use `pytest-django` over `unittest`** — fixtures are composable and tests are shorter.
+
+---
+
+## Hard rules
+
+- Never put business logic in views, models, or serializers — use services
+- Never use raw SQL unless `ORM` genuinely can't express it
+- Always use `select_related`/`prefetch_related` for related objects in list views
+- Always split settings by environment (base / dev / prod)
+- Always use `get_object_or_404` in views — never `Model.objects.get()` bare

package/template/.aioson/skills/static/fastapi-patterns.md

@@ -0,0 +1,344 @@
+# FastAPI Conventions
+
+> Async by default, typed by contract. If it's not typed, it's not FastAPI.
+
+---
+
+## Project structure
+
+```
+myproject/
+├── main.py                  # app entrypoint
+├── app/
+│   ├── api/
+│   │   ├── v1/
+│   │   │   ├── router.py    # aggregates all v1 routes
+│   │   │   ├── users.py
+│   │   │   └── orders.py
+│   ├── core/
+│   │   ├── config.py        # settings via pydantic-settings
+│   │   ├── database.py      # async engine + session
+│   │   └── security.py      # password hashing, JWT
+│   ├── models/
+│   │   └── user.py          # SQLAlchemy ORM models
+│   ├── schemas/
+│   │   └── user.py          # Pydantic request/response models
+│   ├── services/
+│   │   └── user_service.py  # business logic
+│   └── repositories/
+│       └── user_repo.py     # DB queries (optional for SMALL+)
+├── tests/
+│   ├── conftest.py
+│   └── test_users.py
+├── alembic/                 # migrations
+└── requirements.txt
+```
+
+---
+
+## App bootstrap
+
+```python
+# main.py
+from fastapi import FastAPI
+from app.api.v1.router import router as v1_router
+from app.core.config import settings
+
+app = FastAPI(
+    title=settings.PROJECT_NAME,
+    version="1.0.0",
+    docs_url="/docs" if settings.DEBUG else None,
+)
+
+app.include_router(v1_router, prefix="/api/v1")
+
+@app.get("/health")
+async def health():
+    return {"status": "ok"}
+```
+
+---
+
+## Settings (pydantic-settings)
+
+```python
+# app/core/config.py
+from pydantic_settings import BaseSettings
+
+class Settings(BaseSettings):
+    PROJECT_NAME: str = "My App"
+    DEBUG: bool = False
+    DATABASE_URL: str
+    SECRET_KEY: str
+    ACCESS_TOKEN_EXPIRE_MINUTES: int = 30
+
+    class Config:
+        env_file = ".env"
+
+settings = Settings()
+```
+
+**Never hardcode secrets.** Always read from environment via `pydantic-settings`.
+
+---
+
+## Database (SQLAlchemy async)
+
+```python
+# app/core/database.py
+from sqlalchemy.ext.asyncio import create_async_engine, AsyncSession, async_sessionmaker
+from app.core.config import settings
+
+engine = create_async_engine(settings.DATABASE_URL, echo=settings.DEBUG)
+AsyncSessionLocal = async_sessionmaker(engine, expire_on_commit=False)
+
+async def get_db() -> AsyncSession:
+    async with AsyncSessionLocal() as session:
+        yield session
+```
+
+```python
+# app/models/user.py
+from sqlalchemy import Column, Integer, String, DateTime, func
+from sqlalchemy.orm import DeclarativeBase
+
+class Base(DeclarativeBase):
+    pass
+
+class User(Base):
+    __tablename__ = "users"
+
+    id = Column(Integer, primary_key=True, index=True)
+    email = Column(String, unique=True, nullable=False, index=True)
+    hashed_password = Column(String, nullable=False)
+    created_at = Column(DateTime(timezone=True), server_default=func.now())
+```
+
+---
+
+## Schemas (Pydantic)
+
+```python
+# app/schemas/user.py
+from pydantic import BaseModel, EmailStr
+from datetime import datetime
+
+class UserCreate(BaseModel):
+    email: EmailStr
+    password: str
+
+class UserResponse(BaseModel):
+    id: int
+    email: EmailStr
+    created_at: datetime
+
+    model_config = {"from_attributes": True}  # pydantic v2
+
+class UserLogin(BaseModel):
+    email: EmailStr
+    password: str
+```
+
+**Rules:**
+- Separate schemas for input (`UserCreate`) and output (`UserResponse`)
+- Use `EmailStr` for email fields — free format validation
+- `model_config = {"from_attributes": True}` to convert from ORM models
+
+---
+
+## Routers — thin, delegate to services
+
+```python
+# app/api/v1/users.py
+from fastapi import APIRouter, Depends, HTTPException, status
+from sqlalchemy.ext.asyncio import AsyncSession
+from app.core.database import get_db
+from app.schemas.user import UserCreate, UserResponse
+from app.services.user_service import UserService
+
+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)):
+    service = UserService(db)
+    user = await service.create(payload)
+    if not user:
+        raise HTTPException(status_code=409, detail="Email already registered")
+    return user
+
+@router.get("/{user_id}", response_model=UserResponse)
+async def get_user(user_id: int, db: AsyncSession = Depends(get_db)):
+    service = UserService(db)
+    user = await service.get_by_id(user_id)
+    if not user:
+        raise HTTPException(status_code=404, detail="User not found")
+    return user
+```
+
+---
+
+## Services — business logic
+
+```python
+# app/services/user_service.py
+from sqlalchemy.ext.asyncio import AsyncSession
+from sqlalchemy import select
+from app.models.user import User
+from app.schemas.user import UserCreate
+from app.core.security import hash_password
+
+class UserService:
+    def __init__(self, db: AsyncSession):
+        self.db = db
+
+    async def create(self, payload: UserCreate) -> User | None:
+        existing = await self.db.execute(select(User).where(User.email == payload.email))
+        if existing.scalar_one_or_none():
+            return None
+
+        user = User(
+            email=payload.email,
+            hashed_password=hash_password(payload.password)
+        )
+        self.db.add(user)
+        await self.db.commit()
+        await self.db.refresh(user)
+        return user
+
+    async def get_by_id(self, user_id: int) -> User | None:
+        result = await self.db.execute(select(User).where(User.id == user_id))
+        return result.scalar_one_or_none()
+```
+
+---
+
+## Authentication (JWT)
+
+```python
+# app/core/security.py
+from passlib.context import CryptContext
+from jose import jwt
+from datetime import datetime, timedelta
+from app.core.config import settings
+
+pwd_context = CryptContext(schemes=["bcrypt"], deprecated="auto")
+
+def hash_password(password: str) -> str:
+    return pwd_context.hash(password)
+
+def verify_password(plain: str, hashed: str) -> bool:
+    return pwd_context.verify(plain, hashed)
+
+def create_access_token(subject: str) -> str:
+    expire = datetime.utcnow() + timedelta(minutes=settings.ACCESS_TOKEN_EXPIRE_MINUTES)
+    return jwt.encode({"sub": subject, "exp": expire}, settings.SECRET_KEY, algorithm="HS256")
+
+# Dependency for protected routes
+from fastapi import Security
+from fastapi.security import HTTPBearer, HTTPAuthorizationCredentials
+
+security = HTTPBearer()
+
+async def get_current_user(
+    credentials: HTTPAuthorizationCredentials = Security(security),
+    db: AsyncSession = Depends(get_db)
+):
+    try:
+        payload = jwt.decode(credentials.credentials, settings.SECRET_KEY, algorithms=["HS256"])
+        user_id = int(payload["sub"])
+    except Exception:
+        raise HTTPException(status_code=401, detail="Invalid token")
+    user = await UserService(db).get_by_id(user_id)
+    if not user:
+        raise HTTPException(status_code=401, detail="User not found")
+    return user
+```
+
+---
+
+## Dependency injection pattern
+
+```python
+# Reuse db dependency across all routes
+@router.get("/me", response_model=UserResponse)
+async def get_me(current_user: User = Depends(get_current_user)):
+    return current_user
+```
+
+---
+
+## Migrations (Alembic)
+
+```bash
+alembic init alembic
+# Set sqlalchemy.url in alembic.ini or use env.py to read from config
+alembic revision --autogenerate -m "create users table"
+alembic upgrade head
+```
+
+```python
+# alembic/env.py — connect to async engine
+from app.models.user import Base
+target_metadata = Base.metadata
+```
+
+---
+
+## Tests (pytest + httpx)
+
+```python
+# tests/conftest.py
+import pytest
+from httpx import AsyncClient, ASGITransport
+from sqlalchemy.ext.asyncio import create_async_engine, AsyncSession, async_sessionmaker
+from app.core.database import get_db
+from app.models.user import Base
+from main import app
+
+TEST_DB_URL = "sqlite+aiosqlite:///./test.db"
+
+@pytest.fixture
+async def db():
+    engine = create_async_engine(TEST_DB_URL)
+    async with engine.begin() as conn:
+        await conn.run_sync(Base.metadata.create_all)
+    session_factory = async_sessionmaker(engine, expire_on_commit=False)
+    async with session_factory() as session:
+        yield session
+    async with engine.begin() as conn:
+        await conn.run_sync(Base.metadata.drop_all)
+
+@pytest.fixture
+async def client(db):
+    app.dependency_overrides[get_db] = lambda: db
+    async with AsyncClient(transport=ASGITransport(app=app), base_url="http://test") as c:
+        yield c
+    app.dependency_overrides.clear()
+
+# tests/test_users.py
+import pytest
+
+@pytest.mark.anyio
+async def test_create_user(client):
+    response = await client.post("/api/v1/users/", json={"email": "a@test.com", "password": "pass123"})
+    assert response.status_code == 201
+    assert response.json()["email"] == "a@test.com"
+
+@pytest.mark.anyio
+async def test_create_user_duplicate(client):
+    await client.post("/api/v1/users/", json={"email": "a@test.com", "password": "pass123"})
+    response = await client.post("/api/v1/users/", json={"email": "a@test.com", "password": "pass123"})
+    assert response.status_code == 409
+```
+
+---
+
+## Hard rules
+
+- All route handlers must be `async def` — never mix sync I/O in async routes
+- Business logic goes in `services/`, not in route handlers
+- Always use Pydantic schemas for both input validation and response serialization
+- Always use `response_model` in route decorators — never return raw dicts
+- Use `Depends()` for all cross-cutting concerns (auth, db, rate limiting)
+- Use `select_related` equivalent (`selectinload`/`joinedload`) to avoid N+1
+- Never catch bare `Exception` — catch specific error types