Checklist de Configuração de Ambiente
Configuração de Python 3.14, uv, editor e ferramentas - de clone a testes bem-sucedidos em minutos no macOS ou Linux.
Como Usar Este Checklist
- Complete em ordem em uma máquina nova ou em um clone de repositório novo.
- Marque cada caixa antes de passar para as etapas específicas do aplicativo.
- Se uma etapa falhar, pare e corrija - não pule as etapas de lockfile ou venv.
- Cole as versões exatas de
pyproject.tomlao relatar problemas de configuração.
Runtime Principal
- Instalar uv 0.6+:
curl -LsSf https://astral.sh/uv/install.sh | shou gerenciador de pacotes conforme a política da organização. - Instalar Python 3.14:
uv python install 3.14se não estiver instalado globalmente. - Clonar repositório: Chave SSH configurada;
git clone git@github.com:acme/service.git. - Entrar no projeto:
cd service- confirme a presença depyproject.tomleuv.lock. - Sincronizar dependências:
uv sync --all-extras(ou--extra devconforme o README).
Ferramentas de Qualidade
- Executar linter:
uv run ruff check .- zero erros no main limpo. - Verificar formatação:
uv run ruff format --check .ou formatar uma vez. - Executar testes:
uv run pytest -q- suíte completa ou subconjunto do README para a primeira passagem. - Verificação de tipos (se configurado):
uv run mypy src/ouuv run pyright. - Instalar pre-commit:
uv run pre-commit installe depoispre-commit run --all-files.
Configuração do Aplicativo
- Copiar template de env:
cp .env.example .env- preencha os valores locais do 1Password/documento de cofre. - Nunca commitar
.env: Confirme se está listado em.gitignore. - Banco de dados (se necessário): Docker compose
docker compose up -d dbou Postgres local documentado. - Migrações:
uv run alembic upgrade headoumigratedo Django conforme o projeto. - Iniciar servidor de desenvolvimento:
uv run uvicorn app.main:app --reload- curl/health.
Editor e Git
- Interpretador Python do Editor: Aponte para
.venv/bin/pythoncriado pelo uv. - Extensão Ruff: Formatar ao salvar alinhado com o
pyproject.tomlde comprimento de linha. - Identidade Git:
user.nameeuser.emaildefinidos (Configuração do Git). - GitHub CLI (opcional):
gh auth loginpara fluxo de trabalho de PR. - PATH do Shell:
~/.local/binpara ferramentas pipx (httpie, copier).
Portão de Verificação
- Repetir CI localmente: Mesmos comandos do
.github/workflows/pr.yml(ruff, pytest, mypy). - HTTP Smoke Test:
curl -sf http://localhost:8000/healthretorna 200. - Sanidade de Importação:
uv run python -c "import app"sem ImportError. - Documentar bloqueadores: Abrir um issue ou thread no Slack com a saída exata do erro se alguma etapa falhar.
- Assinar com um colega: Captura de tela ou colar o resumo do terminal no ticket de onboarding.
FAQs
uv sync falha no Apple Silicon?
Verifique os wheels para dependências nativas (torch, etc.) - use extras documentados ou índice apenas de CPU.
Versão Python errada selecionada?
uv python pin 3.14 no projeto ou arquivo .python-version conforme o README.
poetry.lock em branch antiga?
Siga a nota de migração do README - pode ser necessário fazer rebase em um commit de migração do uv primeiro.
Desenvolvedores Windows?
WSL2 Ubuntu recomendado; mesmo checklist dentro do WSL.
Relacionados
- uv - A Ferramenta Rápida - profundidade do uv
- Checklist de Onboarding de Desenvolvedores - rampa completa
- Python no Shell - uso do shell
- Gerenciando Versões Python - política de versão
Versões da Stack: Esta página foi escrita para Python 3.14.0 (3.14 estável, 3.13 de manutenção), FastAPI 0.115+, Django 5.2, Flask 3.1, Pydantic 2, PyTorch 2.6+, pandas 2.2+, Polars 1.x, ruff 0.9+ e uv 0.6+.