Melhores Práticas de Ambientes

Regras práticas para manter ambientes Python isolados, reproduzíveis e amigáveis para a equipe.

Como Usar Esta Lista

Aplique estas regras ao iniciar um novo repositório ou ao integrar um novo membro na equipe.
Reforce os itens relacionados a CI nas verificações de pull request.
Revise trimestralmente à medida que as ferramentas (uv, ruff) evoluem.

A - Isolamento

Um ambiente virtual por projeto. Nunca instale dependências de projeto no Python do sistema.
Commite .python-version ou fixe em pyproject.toml. Todos executam o mesmo interpretador.
Adicione .venv/ ao .gitignore. Ambientes são reproduzíveis a partir de lockfiles, não copiados.
Documente os três comandos de bootstrap no README. Clone, sincronize, teste - nada mais é necessário.

B - Reprodutibilidade

Commite o lockfile (uv.lock, poetry.lock ou pdm.lock). CI e produção instalam pacotes idênticos.
Use uv sync --frozen (ou equivalente) em CI. Builds falham se o lockfile estiver desatualizado.
Declare requires-python em pyproject.toml. Bloqueie instalações em interpretadores não suportados.
Separe grupos de dependências de desenvolvimento e produção. Contêineres de produção excluem pytest, ruff, mypy.

C - Estrutura do Projeto

Use o layout src/ com instalações editáveis. Testes importam o pacote instalado, não a raiz do repositório.
Mantenha toda a configuração em pyproject.toml. Um arquivo para metadados, dependências, ruff, pytest, mypy.
Prefira uv para novos projetos. Instalações rápidas, lockfile integrado, gerenciamento de versão Python.
Use o modo workspace para monorepos. Pacotes locais se referenciam sem hacks de caminho.

D - Segurança e Acesso

Nunca commite credenciais ou tokens. Use variáveis de ambiente, segredos de CI ou ~/.netrc.
Audite dependências regularmente. Execute pip-audit ou uv pip audit em CI semanalmente.
Fixe pacotes internos em um índice privado. Documente a URL do índice e a autenticação para CI.
Use HTTPS para todos os índices de pacotes. Sem HTTP simples em pipelines de produção.

E - Fluxo de Trabalho da Equipe

Padronize um gerenciador de pacotes por repositório. Não misture lockfiles de pip, Poetry e uv.
Execute uv lock após qualquer alteração de dependência. Mantenha pyproject.toml e o lockfile sincronizados.
Exporte requirements.txt apenas para estágios legados do Docker. O lockfile é a fonte da verdade.
Teste o bootstrap do README em uma máquina limpa trimestralmente. Capture desvios na documentação antes que novos contratados o façam.

FAQs

Bibliotecas devem commitar lockfiles?

Bibliotecas publicam intervalos de versão. Aplicações e serviços devem commitar lockfiles.

uv ou Poetry para uma nova equipe?

uv para velocidade e simplicidade. Poetry se a equipe já tiver fluxos de trabalho e treinamento maduros com Poetry.

Como migro de requirements.txt?

Crie pyproject.toml, importe dependências com uv add ou pdm import, gere um lockfile, exclua requirements.txt.

O que vai em .gitignore além de .venv?

__pycache__/, *.egg-info/, .mypy_cache/, .ruff_cache/, dist/, .env.

A CI deve criar o venv ou usar um cache?

Cache o venv com hash do lockfile como chave. Recrie quando o hash mudar.

Como lidar com dependências específicas da plataforma?

Use marcadores de ambiente em pyproject.toml: sys_platform == 'win32'.

Um venv global para todos os projetos?

Não. O isolamento evita conflitos de versão entre projetos.

Quando devo atualizar o Python?

Quando o suporte de segurança para sua versão atual terminar ou quando você precisar de novos recursos da linguagem. Teste em um branch primeiro.

Como compartilho variáveis de ambiente com segurança?

.env.example com valores fictícios no repositório. .env real ignorado pelo git. CI usa armazenamentos de segredos.

E sobre Docker e venvs?

No Docker, instale dependências globalmente no contêiner (nenhum venv é necessário). No host, sempre use um venv.

Relacionados

Noções Básicas de Ambientes e Empacotamento - para começar
uv - A Toolchain Rápida - toolchain recomendada
Resolução de Dependências e Lockfiles - política de fixação
Gerenciando Versões do Python - estratégia de versão

Versões da Stack: Esta página foi escrita para Python 3.14.0, 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+.

Melhores Práticas de Ambientes

Regras práticas para manter ambientes Python isolados, reproduzíveis e amigáveis para a equipe.

Como Usar Esta Lista

Aplique estas regras ao iniciar um novo repositório ou ao integrar um novo membro na equipe.
Reforce os itens relacionados a CI nas verificações de pull request.
Revise trimestralmente à medida que as ferramentas (uv, ruff) evoluem.

A - Isolamento

Um ambiente virtual por projeto. Nunca instale dependências de projeto no Python do sistema.
Commite .python-version ou fixe em pyproject.toml. Todos executam o mesmo interpretador.
Adicione .venv/ ao .gitignore. Ambientes são reproduzíveis a partir de lockfiles, não copiados.
Documente os três comandos de bootstrap no README. Clone, sincronize, teste - nada mais é necessário.

B - Reprodutibilidade

Commite o lockfile (uv.lock, poetry.lock ou pdm.lock). CI e produção instalam pacotes idênticos.
Use uv sync --frozen (ou equivalente) em CI. Builds falham se o lockfile estiver desatualizado.
Declare requires-python em pyproject.toml. Bloqueie instalações em interpretadores não suportados.
Separe grupos de dependências de desenvolvimento e produção. Contêineres de produção excluem pytest, ruff, mypy.

C - Estrutura do Projeto

Use o layout src/ com instalações editáveis. Testes importam o pacote instalado, não a raiz do repositório.
Mantenha toda a configuração em pyproject.toml. Um arquivo para metadados, dependências, ruff, pytest, mypy.
Prefira uv para novos projetos. Instalações rápidas, lockfile integrado, gerenciamento de versão Python.
Use o modo workspace para monorepos. Pacotes locais se referenciam sem hacks de caminho.

D - Segurança e Acesso

Nunca commite credenciais ou tokens. Use variáveis de ambiente, segredos de CI ou ~/.netrc.
Audite dependências regularmente. Execute pip-audit ou uv pip audit em CI semanalmente.
Fixe pacotes internos em um índice privado. Documente a URL do índice e a autenticação para CI.
Use HTTPS para todos os índices de pacotes. Sem HTTP simples em pipelines de produção.

E - Fluxo de Trabalho da Equipe

Padronize um gerenciador de pacotes por repositório. Não misture lockfiles de pip, Poetry e uv.
Execute uv lock após qualquer alteração de dependência. Mantenha pyproject.toml e o lockfile sincronizados.
Exporte requirements.txt apenas para estágios legados do Docker. O lockfile é a fonte da verdade.
Teste o bootstrap do README em uma máquina limpa trimestralmente. Capture desvios na documentação antes que novos contratados o façam.

FAQs

Bibliotecas devem commitar lockfiles?

Bibliotecas publicam intervalos de versão. Aplicações e serviços devem commitar lockfiles.

uv ou Poetry para uma nova equipe?

uv para velocidade e simplicidade. Poetry se a equipe já tiver fluxos de trabalho e treinamento maduros com Poetry.

Como migro de requirements.txt?

Crie pyproject.toml, importe dependências com uv add ou pdm import, gere um lockfile, exclua requirements.txt.

O que vai em .gitignore além de .venv?

__pycache__/, *.egg-info/, .mypy_cache/, .ruff_cache/, dist/, .env.

A CI deve criar o venv ou usar um cache?

Cache o venv com hash do lockfile como chave. Recrie quando o hash mudar.

Como lidar com dependências específicas da plataforma?

Use marcadores de ambiente em pyproject.toml: sys_platform == 'win32'.

Um venv global para todos os projetos?

Não. O isolamento evita conflitos de versão entre projetos.

Quando devo atualizar o Python?

Quando o suporte de segurança para sua versão atual terminar ou quando você precisar de novos recursos da linguagem. Teste em um branch primeiro.

Como compartilho variáveis de ambiente com segurança?

.env.example com valores fictícios no repositório. .env real ignorado pelo git. CI usa armazenamentos de segredos.

E sobre Docker e venvs?

No Docker, instale dependências globalmente no contêiner (nenhum venv é necessário). No host, sempre use um venv.

Relacionados

Noções Básicas de Ambientes e Empacotamento - para começar
uv - A Toolchain Rápida - toolchain recomendada
Resolução de Dependências e Lockfiles - política de fixação
Gerenciando Versões do Python - estratégia de versão

Versões da Stack: Esta página foi escrita para Python 3.14.0, 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+.

Melhores Práticas de Ambientes

Buscar na documentação

Melhores Práticas de Ambientes