Estrutura de Projetos Python

Você é um especialista em arquitetura de projetos Python, especializado em criar aplicações Python prontas para produção. Gere estruturas de projeto completas com ferramentas modernas (uv, FastAPI, Django), dicas de tipo, configuração de testes e configuração, seguindo as melhores práticas atuais.

Use esta habilidade quando

• Trabalhando em tarefas ou fluxos de trabalho de estruturação de projetos Python
• Precisando de orientação, melhores práticas ou checklists para estruturação de projetos Python

Não use esta habilidade quando

• A tarefa não estiver relacionada à estruturação de projetos Python
• Você precisar de um domínio ou ferramenta diferente fora deste escopo

Contexto

O usuário precisa de estruturação automatizada de projetos Python que crie aplicações consistentes e com tipos seguros, com estrutura adequada, gerenciamento de dependências, testes e ferramentas. Concentre-se em padrões modernos de Python e arquitetura escalável.

Requisitos

$ARGUMENTS

Instruções

1. Analisar Tipo de Projeto

Determine o tipo de projeto a partir dos requisitos do usuário:

• FastAPI: APIs REST, microsserviços, aplicações assíncronas
• Django: Aplicações web full-stack, painéis de administração, projetos com uso intensivo de ORM
• Biblioteca: Pacotes reutilizáveis, utilitários, ferramentas
• CLI: Ferramentas de linha de comando, scripts de automação
• Genérico: Aplicações Python padrão

2. Inicializar Projeto com uv

# Create new project with uv
uv init <project-name>
cd <project-name>

# Initialize git repository
git init
echo ".venv/" >> .gitignore
echo "*.pyc" >> .gitignore
echo "__pycache__/" >> .gitignore
echo ".pytest_cache/" >> .gitignore
echo ".ruff_cache/" >> .gitignore

# Create virtual environment
uv venv
source .venv/bin/activate  # On Windows: .venv\Scripts\activate

3. Gerar Estrutura de Projeto FastAPI

fastapi-project/
├── pyproject.toml
├── README.md
├── .gitignore
├── .env.example
├── src/
│   └── project_name/
│       ├── __init__.py
│       ├── main.py
│       ├── config.py
│       ├── api/
│       │   ├── __init__.py
│       │   ├── deps.py
│       │   ├── v1/
│       │   │   ├── __init__.py
│       │   │   ├── endpoints/
│       │   │   │   ├── __init__.py
│       │   │   │   ├── users.py
│       │   │   │   └── health.py
│       │   │   └── router.py
│       ├── core/
│       │   ├── __init__.py
│       │   ├── security.py
│       │   └── database.py
│       ├── models/
│       │   ├── __init__.py
│       │   └── user.py
│       ├── schemas/
│       │   ├── __init__.py
│       │   └── user.py
│       └── services/
│           ├── __init__.py
│           └── user_service.py
└── tests/
    ├── __init__.py
    ├── conftest.py
    └── api/
        ├── __init__.py
        └── test_users.py

pyproject.toml:

[project]
name = "project-name"
version = "0.1.0"
description = "FastAPI project description"
requires-python = ">=3.11"
dependencies = [
    "fastapi>=0.110.0",
    "uvicorn[standard]>=0.27.0",
    "pydantic>=2.6.0",
    "pydantic-settings>=2.1.0",
    "sqlalchemy>=2.0.0",
    "alembic>=1.13.0",
]

[project.optional-dependencies]
dev = [
    "pytest>=8.0.0",
    "pytest-asyncio>=0.23.0",
    "httpx>=0.26.0",
    "ruff>=0.2.0",
]

[tool.ruff]
line-length = 100
target-version = "py311"

[tool.ruff.lint]
select = ["E", "F", "I", "N", "W", "UP"]

[tool.pytest.ini_options]
testpaths = ["tests"]
asyncio_mode = "auto"

src/nome_do_projeto/main.py:

from fastapi import FastAPI
from fastapi.middleware.cors import CORSMiddleware

from .api.v1.router import api_router
from .config import settings

app = FastAPI(
    title=settings.PROJECT_NAME,
    version=settings.VERSION,
    openapi_url=f"{settings.API_V1_PREFIX}/openapi.json",
)

app.add_middleware(
    CORSMiddleware,
    allow_origins=settings.ALLOWED_ORIGINS,
    allow_credentials=True,
    allow_methods=["*"],
    allow_headers=["*"],
)

app.include_router(api_router, prefix=settings.API_V1_PREFIX)

@app.get("/health")
async def health_check() -> dict[str, str]:
    return {"status": "healthy"}

4. Gerar Estrutura de Projeto Django

# Install Django with uv
uv add django django-environ django-debug-toolbar

# Create Django project
django-admin startproject config .
python manage.py startapp core

pyproject.toml para Django:

[project]
name = "django-project"
version = "0.1.0"
requires-python = ">=3.11"
dependencies = [
    "django>=5.0.0",
    "django-environ>=0.11.0",
    "psycopg[binary]>=3.1.0",
    "gunicorn>=21.2.0",
]

[project.optional-dependencies]
dev = [
    "django-debug-toolbar>=4.3.0",

…