Stack Python — InfoWhere

Template de stack para projetos Python
Última atualização: 25/01/2026
Nível de experiência: ⭐⭐⭐ Crescendo

1. Visão Geral

Stack para projetos de IA/ML, MCPs, automações e APIs rápidas.

2. Versões

3. Dependências Core

3.1 API Framework

# pyproject.toml
[project]
dependencies = [
    "fastapi>=0.115.0",
    "uvicorn[standard]>=0.32.0",
    "pydantic>=2.9.0",
    "pydantic-settings>=2.6.0",
]

3.2 Database

[project.optional-dependencies]
db = [
    "sqlalchemy>=2.0.0",
    "asyncpg>=0.30.0",          # PostgreSQL async
    "alembic>=1.14.0",          # Migrations
]

mongo = [
    "motor>=3.6.0",             # MongoDB async
    "beanie>=1.27.0",           # MongoDB ODM
]

3.3 Autenticação

auth = [
    "python-jose[cryptography]>=3.3.0",   # JWT
    "passlib[bcrypt]>=1.7.4",             # Password hashing
    "httpx>=0.28.0",                       # HTTP client (Keycloak)
]

3.4 IA / LLM

ai = [
    "langchain>=0.3.0",
    "langchain-openai>=0.2.0",
    "langchain-anthropic>=0.3.0",
    "openai>=1.57.0",
    "anthropic>=0.40.0",
]

3.5 MCP (Model Context Protocol)

mcp = [
    "mcp>=1.0.0",
    "httpx>=0.28.0",
]

3.6 Utilitários

utils = [
    "python-dotenv>=1.0.0",
    "loguru>=0.7.0",            # Logging melhorado
    "rich>=13.9.0",             # CLI bonito
    "typer>=0.15.0",            # CLI framework
]

4. Testes

[project.optional-dependencies]
test = [
    "pytest>=8.3.0",
    "pytest-asyncio>=0.24.0",
    "pytest-cov>=6.0.0",
    "httpx>=0.28.0",            # TestClient
    "faker>=33.0.0",            # Dados fake
]

Cobertura mínima: 80%

5. Autenticação / Autorização

Configuração típica

from fastapi import Depends, HTTPException, status
from fastapi.security import HTTPBearer, HTTPAuthorizationCredentials
from jose import jwt, JWTError

security = HTTPBearer()

async def get_current_user(
    credentials: HTTPAuthorizationCredentials = Depends(security)
) -> dict:
    token = credentials.credentials
    try:
        payload = jwt.decode(
            token,
            settings.jwt_public_key,
            algorithms=["RS256"],
            audience=settings.jwt_audience,
        )
        return payload
    except JWTError:
        raise HTTPException(
            status_code=status.HTTP_401_UNAUTHORIZED,
            detail="Invalid token"
        )

6. Database

Convenções

• Tabelas: snake_case plural (users, invoices)
• Colunas: snake_case (created_at, user_id)
• Models: PascalCase singular (User, Invoice)

7. Estrutura do Projeto

Nível Script (PoCs, MCPs, automações)

{projeto}/
├── main.py              # Tudo junto
├── requirements.txt     # ou pyproject.toml
├── .env
└── README.md

Ou se precisar separar minimamente:

{projeto}/
├── main.py              # Entry point
├── services.py          # Lógica de negócio
├── schemas.py           # Pydantic DTOs
├── pyproject.toml
└── README.md

Quando usar: PoCs, scripts, MCPs, projetos que não vão crescer.

Nível Médio (APIs que podem crescer)

{projeto}/
├── app/
│   ├── __init__.py
│   ├── main.py              # FastAPI app
│   ├── config.py            # Settings (pydantic-settings)
│   ├── routers/             # Endpoints (controllers)
│   │   ├── __init__.py
│   │   └── users.py
│   ├── services/            # Lógica de negócio + acesso a dados
│   │   ├── __init__.py
│   │   └── user_service.py
│   ├── schemas/             # Pydantic DTOs
│   │   ├── __init__.py
│   │   └── user.py
│   ├── models/              # SQLAlchemy entities
│   │   ├── __init__.py
│   │   └── user.py
│   ├── core/
│   │   ├── __init__.py
│   │   ├── security.py
│   │   └── exceptions.py
│   └── db/
│       ├── __init__.py
│       └── session.py
├── tests/
│   ├── conftest.py
│   └── test_users.py
├── alembic/
├── pyproject.toml
├── Dockerfile
└── README.md

Quando usar: APIs que podem crescer, projetos com múltiplos endpoints.

Nota: Sem Facade, sem Repository separado — Service acessa ORM direto.

---

## 8. Padrões e Convenções

### 8.1 API REST

- Versionamento: `/api/v1/`
- Formato: JSON
- Naming: `snake_case` para URLs (`/api/v1/user_profiles`)
- Async: Sempre que possível
- Docs: Auto-gerado pelo FastAPI (`/docs`, `/redoc`)

### 8.2 Schemas (Pydantic)

```python
# Request
class UserCreate(BaseModel):
    email: EmailStr
    name: str

# Response
class UserResponse(BaseModel):
    id: UUID
    email: EmailStr
    name: str
    created_at: datetime

    model_config = ConfigDict(from_attributes=True)

# Update (partial)
class UserUpdate(BaseModel):
    email: EmailStr | None = None
    name: str | None = None

8.3 Exceptions

# Custom exception
class ResourceNotFoundError(Exception):
    def __init__(self, resource: str, id: str):
        self.resource = resource
        self.id = id

# Handler
@app.exception_handler(ResourceNotFoundError)
async def not_found_handler(request, exc):
    return JSONResponse(
        status_code=404,
        content={"detail": f"{exc.resource} {exc.id} not found"}
    )

8.4 Logs

• Framework: Loguru
• Formato: JSON em produção

from loguru import logger

logger.info("User created", user_id=user.id)

9. Infraestrutura

Dockerfile típico

FROM python:3.12-slim

WORKDIR /app

# Instalar UV
RUN pip install uv

# Copiar dependências
COPY pyproject.toml .
RUN uv pip install --system -e ".[all]"

# Copiar código
COPY src/ src/

EXPOSE 8000

CMD ["uvicorn", "src.{projeto}.main:app", "--host", "0.0.0.0", "--port", "8000"]

10. O que NÃO usar

11. Checklist de Novo Projeto

• Criar projeto com uv init
• Configurar pyproject.toml com dependências
• Criar estrutura de pastas
• Configurar config.py com pydantic-settings
• Configurar autenticação JWT/Keycloak
• Configurar Alembic (se SQL)
• Criar Dockerfile
• Criar docker-compose.yml para dev
• Configurar pytest com fixtures
• Criar README.md com instruções

12. Links de Referência

• FastAPI Docs
• Pydantic Docs
• SQLAlchemy Docs
• UV Docs
• Loguru Docs

Nota: Este template é a base. Cada projeto pode ter ajustes específicos documentados no technical_context.md do projeto.