Ir para o conteúdo

Receitas

Passo a passo curtos no estilo "quero conectar X". Cada página começa com qual problema resolve, quando recorrer a ela e um exemplo de código completo que você pode copiar literalmente.

Comece por aqui

  • Serviço novo do zero? Siga o Tutorial » — linear, constrói a feature Users passo a passo.
  • Só precisa de uma assinatura? Pule para a Referência ».
  • Conectando uma peça específica? Você está no lugar certo — o tour abaixo dá o mapa, e o índice leva à receita completa.
  • Quer ver tudo junto num app real? Vá para os exemplos completos.
  • Quer estudar num projeto guiado? Veja os Projetos de aprendizado ».

Tour do SDK — um exemplo por bloco

Um passeio por tudo que o tempest-fastapi-sdk oferece: cada bloco tem o conceito em uma linha, um exemplo mínimo runnable e o link pra receita completa. Leia de cima a baixo pra ter o mapa mental, ou pule pro que precisa — instale só os extras que usar (uv add "tempest-fastapi-sdk[auth,cache,queue]>=0.171.0").

Fundação

BaseAppSettings, AsyncDatabaseManager, create_app factory, run().

from tempest_fastapi_sdk import AsyncDatabaseManager, BaseAppSettings


class Settings(BaseAppSettings):
    DATABASE_URL: str = "sqlite+aiosqlite:///./app.db"


settings = Settings()
db = AsyncDatabaseManager(settings.DATABASE_URL)

Veja o Tutorial e a receita de Banco de dados.

Schemas e campos validados

BaseSchema + tipos Annotated que se autodescrevem (dinheiro, %, slug, lat/long, e brasileiros: CPF/CNPJ/CEP/telefone + chave Pix).

from tempest_fastapi_sdk import BaseSchema
from tempest_fastapi_sdk.utils import CentsField, PixKeyField, SlugField


class ProductSchema(BaseSchema):
    slug: SlugField
    price_cents: CentsField          # int >= 0
    pix_key: PixKeyField             # CPF/CNPJ/e-mail/telefone/aleatória

Receitas: Campos validados, Helpers brasileiros.

Repository, Service, Controller

BaseRepository[Model] (CRUD + bulk ops), BaseService, BaseController com get_by_id/list/paginate/update/delete prontos.

from sqlalchemy.ext.asyncio import AsyncSession

from tempest_fastapi_sdk import BaseRepository, BaseService

from src.db.models import UserModel
from src.schemas import UserResponseSchema


class UserRepository(BaseRepository[UserModel]):
    def __init__(self, session: AsyncSession) -> None:
        super().__init__(session, model=UserModel)


class UserService(BaseService[UserRepository, UserResponseSchema]):
    ...

Receitas: Tutorial, Banco de dados.

Paginação

Offset e cursor, com header Link.

from tempest_fastapi_sdk import BasePaginationFilterSchema, CursorPaginationFilterSchema

Exceções padronizadas

AppException + subclasses → HTTP correto; register_exception_handlers(app).

from fastapi import FastAPI

from tempest_fastapi_sdk import NotFoundException, register_exception_handlers

app = FastAPI()


register_exception_handlers(app)
raise NotFoundException(message="user not found")   # -> 404 padronizado

Autenticação completa

Fluxo bundled: signup/activate/login/reset/troca e recuperação de e-mail/MFA + deps JWT (header/cookie/query).

from fastapi import FastAPI

from tempest_fastapi_sdk import UserAuthService, make_auth_router

from src.api.dependencies.resources import db
from src.core.settings import settings
from src.db.models import UserModel, UserTokenModel

app = FastAPI()


auth = UserAuthService(user_model=UserModel, token_model=UserTokenModel,
                       auth_settings=settings, jwt_settings=settings)
app.include_router(make_auth_router(auth, session_factory=db.session_dependency))

Receitas: Auth flow, MFA, Refresh tokens, Sessões.

Cache

AsyncRedisManager + @cached + CacheInvalidator (namespace/tag).

from tempest_fastapi_sdk.cache import AsyncRedisManager, cached

from src.core.settings import settings


redis = AsyncRedisManager(settings.REDIS_URL)


@cached(redis, ttl=300, namespace="products", tags=lambda a, k: [f"p:{k['pid']}"])
async def get_product(*, pid: str) -> dict: ...

Receita: Cache.

Fila e tarefas em background

MessageBroker (pub/sub FastStream), TaskQueue (TaskIQ) + cron por enum/helper, ambos escondendo a lib.

from tempest_fastapi_sdk.queue import MessageBroker
from tempest_fastapi_sdk.tasks import Cron, CronOffset, TaskQueue

from src.core.settings import settings
from src.queue import OrderPaid


mq = MessageBroker.rabbitmq(settings.RABBITMQ_URL)
tq = TaskQueue.rabbitmq(settings.TASKIQ_BROKER_URL)


@mq.on("orders.paid")
async def on_paid(event: OrderPaid) -> None: ...


@tq.cron(Cron.EVERY_WEEKDAY_9AM, cron_offset=CronOffset.BRASILIA)
async def digest() -> None: ...

Receitas: Fila e Tarefas, Outbox.

Tempo real

SSE (EventStream/SSEBroker com backpressure), WebSocket router, Web Push.

import asyncio

from fastapi import FastAPI
from fastapi.responses import StreamingResponse

from tempest_fastapi_sdk import EventStream

app = FastAPI()


@app.get("/events")
async def events() -> StreamingResponse:
    """Stream one tick per second until the client disconnects.

    Returns:
        StreamingResponse: The SSE response. ``on_disconnect`` cancels the
        publisher, so it never outlives the connection.
    """
    stream = EventStream()

    async def pump() -> None:
        """Publish a tick every second."""
        while True:
            await stream.publish({"tick": True}, event="tick")
            await asyncio.sleep(1)

    task = asyncio.create_task(pump())
    return stream.response(on_disconnect=task.cancel)

Receitas: SSE, WebSocket, Web Push, Tempo real.

Observabilidade

Logging estruturado + /logs, métricas CPU/RAM/GPU + Prometheus /metrics, request-id, tracing OTel, health + tool-spec.

from fastapi import FastAPI

from tempest_fastapi_sdk import RequestIDMiddleware, make_health_router

from src.api.dependencies.resources import db

app = FastAPI()


app.add_middleware(RequestIDMiddleware)
app.include_router(make_health_router(checks={"db": db.health_check}))

Receitas: Logging, Métricas, Observabilidade.

Hardening HTTP

Rate limit (sliding window), idempotência, CSRF, CORS, limite de body, static seguro.

from fastapi import FastAPI

from tempest_fastapi_sdk import IdempotencyMiddleware, RateLimitMiddleware

app = FastAPI()


app.add_middleware(RateLimitMiddleware, store=..., max_requests=100, window_seconds=60)
app.add_middleware(IdempotencyMiddleware, store=...)

Receitas: Camada HTTP, Idempotência, Segurança.

Arquivos

UploadUtils (local/MinIO), DownloadUtils, FileStoreUtils (facade), storage MinIO/S3, presigned URLs.

import asyncio

from fastapi import UploadFile

from tempest_fastapi_sdk import FileStoreUtils

upload_file: UploadFile = ...  # comes from the endpoint signature


store = FileStoreUtils(source="./uploads")     # ou um AsyncMinIOClient


async def main() -> None:
    """Run this example."""
    key = await store.save(upload_file)


asyncio.run(main())

Receitas: File store, Uploads, Downloads, Storage.

Extras de domínio

Feature flags, audit trail, multi-tenant, sync offline-first, sessões server-side, HTTP client tipado, i18n de erros.

from tempest_fastapi_sdk import FeatureFlags, make_flag_dependency

Receitas: Feature flags, Audit trail, Multi-tenant, Sync offline, HTTP client.

IA generativa self-hosted

Checagem de hardware, LLM local, embeddings, RAG (web + PDF) — tudo no seu hardware.

Instalação

O SDK já vem com tempest-fastapi-sdk. A IA generativa self-hosted depende do extra [genai] — uv add "tempest-fastapi-sdk[genai]" (traz torch, transformers, accelerate, safetensors e huggingface-hub).

import asyncio

from tempest_fastapi_sdk.genai import can_run, TextGenerator
from tempest_fastapi_sdk.genai.rag import PdfReader, build_context


async def main() -> None:
    """Run this example."""
    if can_run(model_id="Qwen/Qwen2.5-7B-Instruct").fits:
        gen = TextGenerator("Qwen/Qwen2.5-7B-Instruct", quantization="int4")
        chunks = PdfReader().chunks("/kb/manual.pdf")
        answer = await gen.generate(build_context("como estornar?", chunks))


asyncio.run(main())

Receita: IA generativa self-hosted.

Trabalho longo, com status e cancelável

JobStore dá ao trabalho uma linha que a tela lê; run_cancellable o interrompe de verdade quando o usuário desiste. StageMap cobre o caso em que os estágios decoram um registro que a tela já busca.

import asyncio
from uuid import UUID

from tempest_fastapi_sdk.db import AsyncDatabaseManager
from tempest_fastapi_sdk.tasks import (
    BaseJobModel,
    JobStore,
    StageInterruptedError,
    run_cancellable,
)


class JobModel(BaseJobModel):
    """Uma unidade de trabalho longo."""

    __tablename__ = "jobs"


db = AsyncDatabaseManager("sqlite+aiosqlite:///./app.db")
store: JobStore[JobModel] = JobStore(db, model=JobModel)


async def transcrever(caminho: str) -> str:
    """Trabalho longo e cancelável (I/O assíncrono).

    Args:
        caminho (str): O arquivo a processar.

    Returns:
        str: O texto.
    """
    await asyncio.sleep(0)
    return caminho


async def executar(job_id: UUID) -> None:
    """Roda o job, desistindo se cancelarem no meio.

    Args:
        job_id (UUID): O job a executar.
    """
    if await store.claim(job_id) is None:
        return
    try:
        texto: str = await run_cancellable(
            transcrever("audio.wav"),
            interrupted=store.cancellation_watch(job_id),
        )
    except StageInterruptedError:
        return
    await store.succeed(job_id)
    print(texto)

Receita: Jobs (trabalho longo com status).

IA hospedada, e quanto ela custou

OpenAICompatGenerator fala qualquer /chat/completions (DeepSeek, Groq, OpenRouter, vLLM, Azure); AIUsageStore guarda uma linha por chamada paga, para a pergunta "qual conta gastou o quê".

import asyncio
from uuid import uuid4

from tempest_fastapi_sdk.db import AsyncDatabaseManager
from tempest_fastapi_sdk.genai import (
    AIUsageStore,
    BaseAIUsageModel,
    OpenAICompatGenerator,
    TokenUsage,
)


class AIUsageModel(BaseAIUsageModel):
    """Uma chamada de IA cobrada."""

    __tablename__ = "ai_usage"


db = AsyncDatabaseManager("sqlite+aiosqlite:///./app.db")
gen = OpenAICompatGenerator(
    "deepseek-chat",
    api_key="sk-...",
    base_url="https://api.deepseek.com",
)
store: AIUsageStore[AIUsageModel] = AIUsageStore(
    db, model=AIUsageModel, price_input_per_1k=0.00014
)


async def main() -> None:
    """Run this example."""
    texto: str
    uso: TokenUsage | None
    texto, uso = await gen.generate_with_usage("Resuma isto.")
    await store.record(subject_id=uuid4(), service="summary", usage=uso)
    print(texto)


asyncio.run(main())

Receita: IA generativa self-hosted.

Painel admin

AdminSite + AdminModel + make_admin_router (Jinja+HTMX, temas, ações, upload, filtros).

Receita: Painel admin.

SSR e visão

SSR tipado (Page/html_response) sobre tempestweb; visão computacional (Detector/Classifier/Segmenter) via ort-vision-sdk.

Receitas: SSR, Visão.

CLI e deploy

tempest new (scaffold), tempest db (migrations), tempest user, tempest secrets, gates de qualidade; deploy seguro (migrations + graceful shutdown).

tempest new my-service && cd my-service
tempest db init && tempest db upgrade
tempest check          # ruff + mypy + testes

Receitas: CLI, Deploy seguro.

Recap

O SDK cobre o ciclo inteiro de um serviço FastAPI: fundação tipada → persistência → auth → cache → background → tempo real → observabilidade → hardening → arquivos → IA → admin → CLI/deploy. Cada seção acima aponta pra receita com o guia completo. Comece pelo Tutorial e volte aqui pra plugar cada capacidade conforme precisar.

Índice das receitas

Tema Cobre
Agentes de IA » Agent (objetivo → traço + artefatos), AgentBudget (passos/tempo/chamadas), AgentTool + ferramentas prontas sobre imagem/visão/áudio/RAG, InMemoryAgentRunSink / DbAgentRunSink, make_agent_router
Agentes de IA (arquitetura) » como organizar um serviço com agentes: a camada ai ao lado de services, runtime com um gerador por processo, tools separado de agents, views e policy, o controller que semeia a identidade, e quando trocar um agente por skills
Agentes de IA (avançado) » saída estruturada tipada (run_structured), três camadas de memória (scratchpad_tools / fact_tools / recall_prompt), Skill sob demanda, agent_tool para delegação, run_until / refine
Agentes de IA (banco de dados) » ferramenta que consulta o banco: db.get_session_context() por chamada, convenção from_session, um AsyncDatabaseManager por processo, e o que AgentContext carrega (state com quem pergunta, artifacts, deadline)
Agentes de IA (conceitos) » o laço passo a passo, a transcrição que o modelo recebe em cada volta, o vocabulário (passo, observação, artefato, orçamento, stop_reason), por que o contexto cresce e o que isso custa, e quando usar ferramenta, skill, delegação ou laço
Agentes de IA (testes) » ScriptedBackend / replies / replies_with_tool para escrever as decisões do modelo, assert_completed / assert_used_tools / assert_artifact, FailingBackend, e a camada @model separada
Arquivo no serviço (mixin) » StoredFileServiceMixin — set_file / replace / clear_file sobre UploadUtils
Artefatos versionados (modelos) » ArtifactRegistry, ArtifactVersionMixin, build_manifest_entries, file_digest — versão ativa sem redeploy
Audit trail » BaseAuditLogModel, add_audited / update_audited / delete_audited, snapshot_model / diff_snapshots
Auth Firebase (ID token) » FirebaseAuth, FirebaseIdentity, FirebaseUserResolver — verificar o ID token que o app mobile manda, inicialização idempotente, um code por falha, extra [firebase]
Auth flow (signup/reset) » UserAuthService, make_auth_router — signup / ativação / login / reset de senha, entrega de token (bearer/cookie/ambos), BaseUserModel
Auth por introspecção (resource server) » IntrospectionAuth — validar bearer opaco perguntando ao provedor de identidade upstream
Banco de dados » BaseModel, AsyncDatabaseManager, BaseRepository (CRUD + filtros + bulk), paginação offset/cursor, mixins, AlembicHelper, SlowQueryLogger
Busca textual (LIKE + full-text) » search() portátil (ILIKE escapado, AND entre palavras), full_text_search() com websearch_to_tsquery + ts_rank no PostgreSQL, TextSearchLanguage / TextSearchWeight / TokenMatch, condições que entram em where=
Cache » AsyncRedisManager (+ client_proxy, para store construído no import), decorator @cached, CacheInvalidator (tag/namespace)
Camada HTTP » apply_cors, RequestIDMiddleware, RateLimitMiddleware (429 no envelope de erro do SDK), make_health_router, dependências de JWT / role / permissão, verificador de assinatura de webhook, headers Link de paginação, router de tool-spec
Camada UI (páginas e componentes) » a camada src/ui/ (páginas, layout, componentes, estilos), Page + shell() herdado, Card / Alert / DataTable / Pagination / EmptyState / NavBar, Shell / Grid, scaffold via tempest new --extras "ssr"
Campos validados (tipos prontos) » tipos Pydantic Annotated — PositiveIntField / CentsField / PriceField / SlugField / HexColorField / CPFField / UFField
Chat (conversas + mensagens) » ChatService, make_chat_router, tabelas base + fan-out em tempo real via SSEBroker
CLI » tempest new / db (+ seed) / user / secrets rotate / lint / fix / format / type / test / check
Cliente de integração (OpenAPI) » tempest openapi-client — schemas Pydantic + client tipado a partir da spec de um terceiro
Colunas de enum (seguras nos dois bancos) » Mapped[MeuEnum] guardando o value, ENUM nativo no PostgreSQL e CHECK no SQLite, enum_column(), op.replace_enum + sync_enum_types para a migration que o autogenerate não vê
Comentários + avaliações » ReviewService, make_reviews_router, notas 0–5 estrelas com agregação, comentários encadeados
Console SQL no admin » SqlShellService + SqlShellPolicy (capacidades, tabelas permitidas/negadas, teto de linhas, require_where), análise real via sqlglot, auditoria de toda tentativa, página opt-in no admin
CSS tipado (StyleSheet e tokens) » StyleSheet / Rule / Media, ThemeTokens (tokens do tempest_core como CSS variables, claro e escuro), make_css_router com ETag/304, app_stylesheet, cls() que rejeita classe inexistente
Deploy seguro » AlembicHelper.safe_upgrade (barra DROPs), GracefulShutdownMiddleware
Downloads » DownloadUtils — file_response, stream, build_content_disposition, anti path-traversal
Email transacional » EmailUtils — SMTP, corpo texto/HTML, anexos, templates Jinja2
Erros do app (relatados pelo cliente) » make_app_error_model (FK de usuário nullable, SET NULL, created_at indexado), AppErrorService (trunca em vez de recusar), listagem admin opt-in, intervalo de datas semiaberto
Erros no OpenAPI (Swagger) » error_responses, @raises, TempestAPIRouter, ErrorResponseSchema, tempest openapi-errors --fix
Escolhendo o modelo » TextModel / EmbeddingModel / RerankerModel / VisionModel / ImageModel / SpeechToTextModel / TextToSpeechModel — ids do Hub com nome, e a tabela de caso de uso por trás de cada escolha
Fakes (sem provedor real) » FakePixProvider, FakeTextBackend, FakeModerationBackend, FakePushDispatcher, FakeEmailUtils, FakeGeocodingBackend, FakeRoutingBackend, FakeWebSearchBackend — oito costuras sem credencial e sem rede, dirigíveis (advance, flag, fail_next) e inspecionáveis
Feature flags » FeatureFlags, backends env/Redis/composto, make_flag_dependency
Fila e Tarefas » FastStream (AsyncBrokerManager), TaskIQ (AsyncTaskBrokerManager), AsyncTaskScheduler, outbox transacional
File store (unificado) » FileStoreUtils — upload + download + presign sobre um backend só
Formulários a partir de schemas Pydantic » form_for / form_spec_for / render_form, parse_form + FormResult (erros por campo e valores preservados), mapeamento tipo → controle, json_schema_extra={"ui": ...}, form_stylesheet
Frontend tempestweb + SDK » Frontend tempestweb chamando o backend do SDK: tempestweb.native.http, Idempotency-Key + IdempotencyMiddleware, retry, mesma origem vs CORS
Geolocalização (distância + tempo) » haversine_km, estimate_travel, OSRMBackend, NominatimBackend, GeoPointMixin / GeoRepositoryMixin
Geração de imagem (local) » ImageGenerator (diffusers local — generate / edit img2img), ImageGenerationConfig, GeneratedImage com a seed que reproduz, make_genai_router(image_generator=...) → POST /image
Geração de PDF » PdfRenderer, cinco documentos prontos (recibo/orçamento/relatório/contrato/comprovante) com schema Pydantic, make_pdf_router, tempest pdf render, política de assets
Guards de permissão (@requires) » @requires + guards (user) -> user (com meta: dict[str, Any] opcional via meta= / include_args=), TempestPermissionError, GuardContractWarning, tempest permissions --check
Helpers brasileiros » validação + normalização de CPF / CNPJ / CEP / telefone, incluindo só-celular (is_valid_mobile_phone_br, MobilePhoneBRField) e parse_phone_br (DDD, número, E.164)
HTTP client (saída) » HTTPClient — httpx tipado com retry/backoff, circuit-breaker, X-Request-ID; RetryPolicy, CircuitOpenError
IA generativa self-hosted » probe_hardware / can_run, TextGenerator, Embedder, RAG (web + PDF), áudio (STT/TTS + batching), make_genai_router; backend hospedado (OpenAICompatGenerator, qualquer /chat/completions) com TokenUsage, incluindo o prefixo servido de cache; saída em lista (parse_structured_list, retry com temperatura) e em objeto (extract_json_object); contabilidade de uso por usuário (AIUsageStore)
Idempotência » IdempotencyMiddleware, MemoryIdempotencyStore / IdempotencyStore (Redis) — replay seguro de POST/PUT/PATCH/DELETE
Jobs (trabalho longo com status) » BaseJobModel + JobStore — uma linha por unidade de trabalho, claim/succeed/fail, watch para a tela, reclaim_stale; cancelamento cooperativo (cancel + run_cancellable); StageMap para vários estágios no próprio registro
Logging » LogUtils, logging JSON estruturado, propagação de request-ID
Login social (OAuth2/OIDC) » GoogleOAuthClient, GitHubOAuthClient, OIDCProvider, OAuthUser, generate_oauth_state
Management commands (tempest <cmd>) » registrar comandos próprios na CLI tempest do projeto
Mercado Pago (Pix, cartão, boleto) » MercadoPagoClient (143 operações geradas da OpenAPI oficial do provedor), to_cents / from_cents (reais, não centavos), verify_signature, MercadoPagoSettings, x_idempotency_key por chamada
Métricas » MetricsUtils — snapshots de CPU / RAM / disco / GPU
MFA (TOTP / 2FA) » MFAMixin, TOTPHelper, endpoints enroll/confirm/verify/disable no make_auth_router, códigos de recuperação
Modelops (export, bench, quantização) » benchmark_onnx (latência/RAM/GPU/energia), export_onnx_to_ort, quantize_onnx_dynamic, quantize_hf_onnx, rank + fronteira de Pareto, tempest model
Multi-tenant » TenantScopedRepository — isolamento por tenant_id em toda query
Observabilidade (tracing) » setup_tracing (OpenTelemetry), SlowQueryLogger
OpenPix (assinaturas e planos) » SubscriptionPayload, RECURRENT vs PIX_RECURRING (Pix Automático), ciclo de vida e parcelas, o plano que mora no seu banco
OpenPix (Pix via Woovi) » Arquitetura em camadas, abrir cobrança, webhook verificado + conferência pela API, reconciliação, estorno, OpenPixEnvironment, to_cents
Outbox transacional » BaseOutboxModel, OutboxRelay, save_with_outbox — eventos confiáveis
Painel admin » AdminSite, AdminModel, make_admin_router, BaseUserModel
Permissões object-level » permission (decorator de regra), has_perm / check_permission, PermissionRegistry, make_permission_checker, PermissionMixin
Pesos de modelos (ciclo no Hub) » ModelRef (revision / local_files_only / trust_remote_code), resolve_revision, download_model com preflight de disco, list_cached_models / remove_cached_model, tempest model pull / cache-list / cache-rm
Pipeline de transcrição (áudio → resumo) » os três estágios costurados: StageMap no próprio registro, cancelar uma transcrição já rodando por dentro do on_progress, generate_with_usage + AIUsageStore para saber quem pagou, generate_structured_list na etapa que devolve lista
Planilhas (.xlsx) » SheetWriter (cursor de linha), Column (largura/máscara/alinhamento), SheetStyle como dado puro, formatos BR_* fixados em pt-BR, new_workbook / workbook_to_bytes
Planos de query (EXPLAIN) » explain_queries() captura o bloco e explica na saída, EXPLAIN ANALYZE no PostgreSQL / EXPLAIN QUERY PLAN no SQLite, escrita nunca reexecutada, report.slowest
Protocolo de Pix (um contrato, vários provedores) » PixProvider (Protocol: create / get / cancel / parse_webhook), PixCharge / PixChargeRequest / PixPayer campo por campo, PaymentStatus canônico ao lado do provider_status cru, os seis PixEventType, OpenPixPixProvider — e como escrever o seu adapter, com um fake in-memory para testar sem rede
Push (web + mobile) » DeviceService, PushDispatcher, WebPushTransport / FCMTransport, BaseDeviceTokenModel, make_push_router — uma chamada para navegador e celular, com poda unificada do aparelho morto
Reconhecimento facial » FaceRecognizer (detectar / embutir / comparar), compare_faces, packs de 16 MB ou 191 MB, sem opencv e sem torch
Refresh tokens (rotação/revogação) » BaseUserRefreshTokenModel, make_user_refresh_token_model, issue_token_pair, rotação + detecção de reuso por família
Segurança » AttemptThrottle, helpers de token opaco, HardenedStaticFiles, headers de segurança
Server-Sent Events (SSE) » EventStream, sse_response, ServerSentEvent, SSEBroker (fan-out por canal, ponte Redis)
Sessões server-side » SessionMiddleware, SessionAuth, make_session_router, MemorySessionStore / RedisSessionStore
SPA React no FastAPI » make_spa_router — servir o build do Vite pelo mesmo processo, com history fallback
SSR (páginas tipadas) » Page, html_response, make_htmx_router, hospedar um build do tempestweb
Storage (MinIO/S3) » AsyncMinIOClient, MinIOUploadStorage, presigned_get_url / presigned_put_url, list_objects
Stripe (cartão + assinatura) » StripeClient, stripe_http_client, to_minor_units / from_minor_units, make_stripe_webhook_dependency, StripeEvent — escrita form-encoded, idempotência por padrão, moeda de zero decimais
Sync offline-first (delta) » BaseRepository.changes_since, SyncFilterSchema, SyncPaginationSchema, deltas por cursor + soft-delete
System checks (check-config) » run_system_checks, @check, CheckMessage, tempest check-config — validar settings antes de servir
Tempo real » Visão geral — quando escolher SSE, WebSocket ou Web Push
Testes » test_session, test_database, SQLite em memória, fixtures pytest
Tipagem (estático + runtime) » strict_types / typed / require_annotations, knob [tool.tempest] typing_strictness, ruff ANN
Transações (commit e savepoint) » transaction() compartilhado pela sessão, commit() / flush() / rollback() no repositório, autocommit=False, savepoint() para o passo recuperável
Uploads (backends) » UploadUtils, validação de extensão/MIME (sniff_mime), backends local / MinIO
Utilitários » utcnow/to_utc, modify_dict, get_client_ip, tokens opacos (generate_opaque_token)
Visão computacional (ONNX) » Detector / Classifier / Segmenter + schemas de predição
Web Push » WebPushDispatcher, schemas VAPID, broadcast com poda
WebAuthn / passkeys » WebAuthnService, make_web_authn_credential_model, registro + login sem senha, store de desafios em memória/Redis
WebSocket router » WebSocketHub, make_websocket_router, broadcast / send_to, heartbeat, auth via bearer

Exemplos completos

As receitas mostram uma peça por vez. Estas páginas juntam várias num fluxo que roda de ponta a ponta — leia quando quiser ver as decisões de integração, não a API isolada.

Exemplo O que junta
Admin de loja completo » audit history + autocomplete FK + inlines + cards de negócio + import CSV + RBAC granular + lenses
Checkout com Pix » auth JWT + campos validados (PixKeyField) + cache + outbox transacional + MessageBroker + TaskQueue + SSE + Web Push
Fluxos de GenAI » capacidade de hardware → LLM local → embeddings/RAG → áudio, self-hosted de ponta a ponta
Fullstack web (SSR, WASM, server) » os três modos de falar com o tempestweb: SSR + HTMX, SPA WASM e server-mode
Marketplace de bairro » geo (vendedores próximos, distância/tempo) + chat em tempo real + notificações ao vivo + avaliações com estrelas

Anatomia de uma receita

Toda receita segue o mesmo formato de quatro seções para você bater o olho:

  1. O que resolve — um parágrafo em linguagem simples.
  2. Quando usar — lista de situações + quando não usar.
  3. O código — completo, executável, com anotações # 1. setup / # 2. wire / # 3. test.
  4. Pegadinhas — ressalvas de produção, defaults de segurança, notas de escala.

Se você encontrar uma receita que não segue esse formato, abra uma issue — tratamos regressões de doc como regressões de código.