first-plan-lens-python

name	first-plan-lens-python
description	Stack lens para Python. Use durante Discovery quando pyproject.toml, setup.py ou requirements.txt for detectado. Cobre FastAPI, Django, Flask, Litestar, Celery workers, data apps, packaging src/ vs flat.
version	0.1.0

Lens Python

Detecção fina

Sinal	Variante
manage.py na raiz	Django
fastapi em deps	FastAPI
flask em deps	Flask
litestar em deps	Litestar
celery em deps	Worker
streamlit em deps	Data app
dagster, airflow, prefect	Data pipeline
setup.py apenas	lib legacy
pyproject.toml com [tool.poetry]	Poetry
pyproject.toml com [tool.uv] ou uv.lock	uv
pyproject.toml com [build-system] setuptools	setuptools moderno
Pipfile	pipenv

Extração de padrões

Packaging

• Layout src/ vs flat
• Namespace package vs regular
• Versão Python suportada (requires-python)
• Optional dependencies / extras

Type checking

• mypy / pyright / pyre / ty
• Configuração strictness (strict = true?)
• Cobertura de tipos visível

Validação

• Pydantic (v1 ou v2?) - dominante em FastAPI
• attrs (validação opcional)
• marshmallow
• dataclasses + manual validation

Async

• asyncio direto
• anyio (compatibilidade)
• trio
• async libs (httpx vs requests, asyncpg vs psycopg)

Testing

• pytest (dominante) ou unittest stdlib
• conftest.py em pasta tests/ -> fixtures globais
• Markers customizados (pytest.mark.integration)
• Coverage tool (coverage.py)
• Mocks: unittest.mock, pytest-mock, responses (HTTP)

Web frameworks - padrões

FastAPI:

• Routers em app/routers/
• Dependency injection via Depends()
• Pydantic schemas em app/schemas/
• ORM tipicamente SQLAlchemy + Alembic migrations

Django:

• Apps em app/<name>/ com models.py, views.py, urls.py, admin.py
• Settings em <project>/settings.py
• Migrations geradas
• Templates em templates/

Flask:

• Application factory pattern (create_app())?
• Blueprints
• Extensions (Flask-SQLAlchemy, Flask-Login, etc)

ORM

• SQLAlchemy 1.x vs 2.x (style mudou drasticamente)
• Django ORM
• Tortoise ORM (async)
• Peewee
• Raw SQL via psycopg / sqlite3

Logging

• stdlib logging (dominante)
• structlog (estruturado)
• loguru (alternativa moderna)

Linters / formatters

• black + ruff (configuração comum)
• ruff replacing flake8/isort
• mypy / pyright

Workers / async tasks

• Celery (broker Redis ou RabbitMQ)
• Dramatiq
• arq (asyncio-based)
• RQ

Output em .first-plan/

Padrão. Adicional:

• 01-topology/boundaries.md - rotas FastAPI/Django/Flask, tasks Celery
• 02-conventions/di.md - Depends() vs constructor vs factory

Confidence rules

Aumentar:

• [tool.mypy] strict = true + arquivos sem # type: ignore -> alta confiança em "tipagem estrita"
• pyproject.toml bem definido com tools configuradas

Reduzir:

• Mistura de Python 2 e 3 styles (e.g., super(Cls, self).__init__() ao lado de super().__init__())
• Sem type hints em código novo

Anti-padrões comuns

• from x import * (smell)
• except: ou except Exception: sem logar nem re-raise
• Imports circulares mascarados com import dentro de função
• Mutable default args (def f(x=[]):)
• Mistura sync e async sem critério
• assert em produção (removido com python -O)