mihailtd/skills

Programação Python — Abordagem Geral

Este é o skill mestre de referência Python. Ele captura os padrões inegociáveis e a filosofia "functional-lite" usada em todo o código Python neste projeto. Leia isto primeiro; siga os skills de domínio vinculados para uma orientação mais aprofundada.

---

Stack Principal

Componente	Escolha
Gerenciador de pacotes e executor de tarefas	uv
Manifesto de empacotamento	Apenas pyproject.toml
Linter / Formatador	ruff
Verificador de tipos	ty
Biblioteca de processamento de dados	polars (não pandas)
Framework Backend	FastAPI
Banco de Dados	PostgreSQL
ORM	SQLAlchemy (assíncrono)
Migrações	Alembic
Modelo de execução	asyncio — sempre async
Estilo de programação	Functional-lite

---

Gerenciamento de Pacotes — Sempre uv

Nunca use pip, pip-tools, poetry, ou pipenv diretamente. Toda instalação, execução e script usam uv e seus comandos nativos.

# Instalar dependências
uv sync

# Adicionar uma dependência
uv add <pacote>

# Adicionar uma dependência de desenvolvimento
uv add --dev <pacote>

# Executar um script ou módulo
uv run python script.py
uv run alembic upgrade head
uv run pytest

# Atualizar dependências
uv lock --upgrade

Trave todas as dependências de produção com == para builds reproduzíveis. Não use requirements.txt, requirements-dev.txt ou qualquer diretório de requisitos para gerenciamento de dependências. Todos os metadados do pacote e configuração de dependências pertencem ao pyproject.toml. Use uv para todas as operações que envolvam pacotes, ferramentas ou builds. Nunca execute pip, pip install, python -m pip, poetry, ou pipenv diretamente neste projeto. Consulte o skill upgrade-dependencies para o fluxo de trabalho completo de atualização: .github/skills/upgrade-dependencies/SKILL.md Para orientação específica sobre bibliotecas, consulte .github/skills/python-library-creation/SKILL.md.

---

Linting e Formatação — Stack Astral Obrigatório

O stack Astral é obrigatório para projetos Python neste repositório. O ruff é o linter e formatador canônico.

• Adicione ruff como uma dependência de desenvolvimento: uv add --dev ruff
• Use uv run ruff format para formatar código.
• Use uv run ruff check --fix para executar linting e corrigir problemas automaticamente quando possível.
• Documente esses comandos nos scripts do seu projeto ou no README.

ruff é a única fonte da verdade para formatação e consistência de estilo em código, testes e configuração.

---

Verificação de Tipos — ty Preferido

Anotações de tipo são obrigatórias. O ty é o verificador de tipos preferido para este repositório.

• Adicione ty como uma dependência de desenvolvimento: uv add --dev ty
• Execute verificações de tipo com uv run ty check
• Use uv run --with ty ty check para validar a toolchain, se quiser comparar comportamentos.

O repositório ainda pode experimentar com outros verificadores, como mypy ou pyrefly, mas o ty é o verificador principal preferido e deve ser o aplicado no CI.

---

Processamento de Dados — Polars vs DuckDB

Este repositório prefere polars para engenharia de dados em processo e DuckDB para análises SQL-first e consulta a grandes arquivos.

• Use Polars quando o agente estiver atuando como um Speedster:

  • Processamento de DataFrames multithread, baseado em Rust, em uma única máquina.
  • Melhor para encadeamento de pipelines complexos, engenharia de features, junções, funções de janela e transformações programáticas.
  • Prioriza throughput e velocidade de computação, com segurança de esquema e tipos mais rigorosa.
  • Excelente para pré-processamento de modelos e integração com ferramentas de ML em Python.

• Use DuckDB quando o agente estiver atuando como um Bibliotecário:

  • Banco de dados SQL em processo otimizado para consultas analíticas OLAP.
  • A intenção SQL-first é mais confiável para traduzir linguagem natural em código.
  • Melhor para cargas de trabalho com restrição de memória: DuckDB impõe limites de memória rigorosos e pode consultar com segurança conjuntos de dados muito grandes.
  • Ideal para consulta direta a arquivos remotos em S3 ou Google Cloud via URL, sem ETL.

Heurística de decisão

Se a tarefa for:

• Explorar novos arquivos ou armazenamento em nuvem → DuckDB
  • Melhor para varredura direta de arquivos e exploração SQL.
• Filtrar ou classificar conjuntos de dados massivos → Polars
  • Frequentemente domina em velocidade bruta de filtragem e carregamento em nós únicos.
• Colaboração ou entrega → DuckDB
  • SQL é mais fácil para humanos e agentes manterem e depurarem.
• Pré-processamento de modelos → Polars
  • Melhor integração com ferramentas de ML em Python e pipelines seguros quanto ao esquema.

---

Backend — FastAPI

FastAPI é o único framework backend suportado. Convenções principais:

• Sempre use async def para manipuladores de rota e dependências.
• Use modelos Pydantic v2 para todas as formas de requisição/resposta.
• Declare dependências com Depends() — nunca acesse estado global dentro dos manipuladores.
• Retorne modelos de resposta tipados; nunca retorne dicionários brutos de manipuladores de rota.
• Roteadores vivem em seus próprios módulos; main.py apenas monta roteadores e configura middleware.

# ✅ Padrão correto
@router.get("/items/{item_id}", response_model=ItemResponse)
async def get_item(item_id: int, db: AsyncSession = Depends(get_db)) -> ItemResponse:
    return await item_service.get(db, item_id)

Para estruturação, testes, segurança e documentação OpenAPI, consulte os skills de domínio FastAPI:

• .github/skills/python-fastapi-project-structuring/SKILL.md
• .github/skills/python-fastapi-routing-validation/SKILL.md
• .github/skills/python-fastapi-dependency-injection/SKILL.md
• .github/skills/python-fastapi-response-error-handling/SKILL.md
• .github/skills/python-fastapi-security-authentication/SKILL.md
• .github/skills/python-fastapi-security-attack-resistance/SKILL.md
• .github/skills/python-fastapi-api-testing/SKILL.md
• .github/skills/python-fastapi-openapi-documentation/SKILL.md

---

Banco de Dados — PostgreSQL + SQLAlchemy (assíncrono)

PostgreSQL é o único banco de dados suportado. SQLAlchemy é o ORM.

• Sempre use o engine e a sessão assíncronos (AsyncEngine, AsyncSession).
• Nunca chame APIs SQLAlchemy síncronas a partir de código assíncrono.
• Use select(), insert(), update(), delete() do sqlalchemy — não strings SQL brutas.
• Gerencie o ciclo de vida da sessão com async with AsyncSession(engine) as session.
• Defina modelos com DeclarativeBase; use anotações de coluna tipadas com Mapped[T] (estilo SQLAlchemy 2.x).

from sqlalchemy.ext.asyncio import AsyncSession, create_async_engine
from sqlalchemy.orm import DeclarativeBase, Mapped, mapped_column

engine = create_async_engine("postgresql+asyncpg://...", echo=False)

class Base(DeclarativeBase):
    pass

class Item(Base):
    __tablename__ = "items"
    id: Mapped[int] = mapped_column(primary_key=True)
    name: Mapped[str]

---

Migrações de Banco de Dados — Alembic

Alembic gerencia todas as alterações de esquema. Nunca mude o esquema do banco de dados manualmente.

Regras principais:

• Migrações são imutáveis uma vez aplicadas a qualquer ambiente não local.
• Cada migração deve ser idempotente sempre que possível.
• Use uv run alembic para todos os comandos Alembic.

uv run alembic revision --autogenerate -m "add_items_table"
uv run alembic upgrade head
uv run alembic history
uv run alembic current

Para regras completas de criação de migrações e aplicação de RLS, consulte: .github/skills/python-alembic-migrations/SKILL.md

Para fazer rebase de ramos de migração apenas locais, consulte: .github/skills/python-alembic-migration-rebase/SKILL.md

---

Async — Sempre

Toda operação de I/O deve ser assíncrona. Não há lugar para chamadas bloqueantes no caminho da requisição.

• Use asyncio.gather() para corrotinas independentes concorrentes.
• Use asyncio.TaskGroup (Python 3.11+) quando concorrência estruturada e propagação de erros forem importantes.
• Use asyncio.Queue ou asyncio.Semaphore para back-pressure e limitação de taxa.
• Nunca chame time.sleep() — use await asyncio.sleep().
• Nunca use requests — use httpx.AsyncClient ou aiohttp.

Orientação mais aprofundada:

• .github/skills/python-asyncio/asyncio-concurrent-web-requests/SKILL.md
• .github/skills/python-concurrent-processing/SKILL.md (trabalho CPU-bound → ProcessPoolExecutor + integração asyncio)
• .github/skills/python-asyncio/asyncio-synchronization/SKILL.md

---

Estilo Functional-Lite

A base de código usa uma abordagem "functional-lite": aplique técnicas funcionais onde elas reduzirem complexidade e melhorarem a clareza, mas não force pureza teórica por si só.

O que FAZEMOS

Técnica	Quando usar
Funções puras	Padrão para lógica de negócios. Sem efeitos colaterais, a menos que necessário.
Dados imutáveis	Use dataclasses congeladas / modelos Pydantic para objetos de valor.
Funções de ordem superior	Prefira map, filter, functools.reduce em vez de loops imperativos para pipelines de dados.
Geradores / sequências lazy	Conjuntos de dados grandes ou streaming — evite construir listas completas em memória.
Utilitários functools	lru_cache, cache, partial, wraps — use livremente.
Composição de funções	Encadeie funções pequenas e focadas em pipelines de transformação de dados.
Decoradores descritivos	Expresse preocupações transversais (autenticação, caching, retentativas) como decoradores.

O que NÃO forçamos

Técnica	Razão para evitar, a menos que claramente benéfico
Mônadas (Maybe, Either, Result)	Adiciona sobrecarga cognitiva; use exceções + retornos tipados.
Estilo point-free	Prejudica a legibilidade para a maioria dos colegas.
Imutabilidade rigorosa em tudo	Modelos SQLAlchemy e estado assíncrono são inerentemente mutáveis — combata isso apenas onde importa.
Biblioteca pymonad / returns	Opt-in apenas; não imponha em código compartilhado sem acordo da equipe.

# ✅ Functional-lite: pipeline de funções puras focadas
from functools import reduce

def parse_items(raw: list[dict]) -> list[Item]:
    return [Item(**r) for r in raw if r.get("active")]

def enrich(item: Item, overrides: dict) -> Item:
    return item.model_copy(update=overrides.get(item.id, {}))

def process(raw: list[dict], overrides: dict) -> list[Item]:
    return [enrich(item, overrides) for item in parse_items(raw)]

Orientação mais aprofundada — skills funcionais consolidados e especializados:

• .github/skills/python-higher-order-functools/SKILL.md (map, filter, max/min, @cache, partial, reduce, @singledispatch)
• .github/skills/python-lazy-evaluation-pipelines/SKILL.md (yield, yield from, generator pipelines, map/filter/reduce)
• .github/skills/python-immutable-data-design/SKILL.md (NamedTuple, frozen dataclass, pyrsistent, context managers)
• .github/skills/python-functional-programming/python-decorator-design/SKILL.md
• .github/skills/python-functional-programming/python-functional-web-services/SKILL.md (handlers funcionais FastAPI)
• .github/skills/python-functional-programming/python-toolz-composition/SKILL.md
• .github/skills/python-functional-programming/python-itertools-combinatorics/SKILL.md
• .github/skills/python-functional-programming/python-recursion-tco/SKILL.md
• .github/skills/python-functional-programming/python-pymonad-strict-evaluation/SKILL.md ← opt-in apenas

---

Convenções Gerais de Código

• Mínimo Python 3.11+. Use sintaxe moderna: match, TypeAlias, Self, etc.
• Anote tudo com tipos — assinaturas de funções, variáveis, tipos de retorno.
• Sem Any a menos que esteja integrando com uma fronteira de terceiros sem tipos.
• Prefira dataclass(frozen=True) ou Pydantic BaseModel para objetos de valor.
• Mantenha funções pequenas e de propósito único. Se uma função precisar de um comentário para explicar o que ela faz (não por que), divida-a.
• Evite estado mutável global. Passe dependências explicitamente (construtor ou Depends()).
• Use logging — não print. Configure na inicialização do aplicativo; nunca chame basicConfig() dentro do código da biblioteca. Consulte .github/skills/python-configuration-observability/SKILL.md para orientação completa sobre logging, tracing e configuração.

---

Mapa de Skills

python/SKILL.md  ← você está aqui (referência mestre)
│
├── Framework Backend
│   ├── python-fastapi-project-structuring/SKILL.md
│   ├── python-fastapi-routing-validation/SKILL.md
│   ├── python-fastapi-dependency-injection/SKILL.md
│   ├── python-fastapi-response-error-handling/SKILL.md
│   ├── python-fastapi-security-authentication/SKILL.md
│   ├── python-fastapi-security-attack-resistance/SKILL.md
│   ├── python-fastapi-api-testing/SKILL.md
│   └── python-fastapi-openapi-documentation/SKILL.md
│
├── Banco de Dados e Migrações
│   ├── python-alembic-migrations/SKILL.md
│   └── python-alembic-migration-rebase/SKILL.md
│
├── Padrões Assíncronos
│   ├── python-asyncio/asyncio-concurrent-web-requests/SKILL.md
│   └── python-asyncio/asyncio-synchronization/SKILL.md
│
├── Skills Centrais Consolidados
│   ├── python-configuration-observability/SKILL.md   (config + logging + tracing)
│   ├── python-data-structures-type-system/SKILL.md   (coleções + tipos + Pydantic)
│   ├── python-lazy-evaluation-pipelines/SKILL.md     (geradores + map/filter/reduce)
│   ├── python-higher-order-functools/SKILL.md        (HOFs + cache + partial + singledispatch)
│   ├── python-immutable-data-design/SKILL.md         (NamedTuple + DC congelada + context mgrs)
│   └── python-concurrent-processing/SKILL.md         (ProcessPool + integração asyncio)
│
├── Programação Funcional (especializada)
│   ├── python-functional-programming/python-decorator-design/SKILL.md
│   ├── python-functional-programming/python-functional-web-services/SKILL.md
│   ├── python-functional-programming/python-toolz-composition/SKILL.md
│   ├── python-functional-programming/python-itertools-combinatorics/SKILL.md
│   ├── python-functional-programming/python-recursion-tco/SKILL.md
│   └── python-functional-programming/python-pymonad-strict-evaluation/SKILL.md ← opt-in
│
├── Criação de Bibliotecas
│   ├── python-library-creation/SKILL.md
│   └── python-project-setup/SKILL.md
│
├── Polars
│   ├── python-polars-basic/SKILL.md
│   └── python-polars-advanced/SKILL.md
│
├── DuckDB
│   └── python-duckdb/SKILL.md
│
├── Pipelines de Dados
│   ├── python-data-pipeline/...
│   └── ...
│
├── Ferramentas e Utilitários
│   ├── python-command-line-interfaces/SKILL.md (CLIs com argparse, typer, click)
│   ├── python-serialization-schema/SKILL.md
│   ├── python-testing-pytest/SKILL.md
│   ├── python-logging/SKILL.md
│   └── python-code-generation/SKILL.md
│
├── Segurança
│   └── python-security/SKILL.md
│
├── DevOps / Deploy
│   ├── python-ci-cd/SKILL.md
│   └── python-containerization/SKILL.md
│
└── Skills OBSOLETOS / Descontinuados (não use)
    └── python-legacy/...

---

Aplicativos FastAPI de alto nível podem querer carregar este skill primeiro, em seguida, os skills de domínio relevantes listados acima para orientação aprofundada sobre cada tópico.