CS Fundamentals Trainer · Guias

Empacotamento, ambientes e imports em Python

Como um import encontra e executa um módulo, sys.path e ofuscação, imports relativos e circulares, o que um ambiente virtual realmente é, pyproject.toml e instalações editáveis, especificadores de versão, arquivos de lock e segurança de dependências.

20 min de leitura

"Na minha máquina funciona" é a frase mais cara do software, e em Python ela costuma ter uma de três causas: um interpretador diferente, versões diferentes dos pacotes instalados, ou uma ideia diferente de onde vem um import. Este guia explica os mecanismos por trás das três: como o Python encontra e executa módulos, por que os ambientes virtuais existem e o que realmente são, o que é um pacote e como o pyproject.toml descreve um, como especificadores de versão e arquivos de lock tornam as instalações repetíveis, e quais são os riscos da cadeia de suprimentos. Cada parte foi executada no CPython 3.13 (scripts no apêndice). Ele se apoia em como o Python funciona e se liga aos conselhos sobre dependências em segurança de aplicações web.

Um limite: o ambiente onde rodei isto não tinha acesso ao Python Package Index (PyPI), então nada aqui foi baixado. Usei apenas o interpretador, o venv, o pip e o setuptools já instalados, e tudo o que se refere a resolvedores, arquivos de lock e ferramentas como uv, poetry ou pip-tools vem da documentação deles, não de uma execução.

1. Como um import funciona

import shop.prices faz quatro coisas, em ordem:

  1. Olha em sys.modules, o dicionário dos módulos já carregados. Se o nome está lá, devolve aquele módulo e para.
  2. Caso contrário, encontra o módulo: percorre as pastas de sys.path procurando shop/ (um pacote) ou shop.py.
  3. Executa o código do módulo de cima para baixo, em um novo espaço de nomes. Os nomes que ele define viram atributos do módulo.
  4. Guarda o módulo em sys.modules e liga o nome no código que importou.

Testei o primeiro passo. Importar shop.prices três vezes imprimiu shop.prices runs uma vez, e 'shop.prices' in sys.modules foi True. O código de nível superior de um módulo roda uma vez por processo, então mantenha os efeitos colaterais (abrir conexões, ler arquivos, iniciar threads) fora do momento do import; faça-os em funções chamadas a partir de main. O mesmo módulo importado com dois nomes diferentes (por exemplo por um caminho relativo e por um absoluto) pode ser carregado duas vezes como dois objetos, uma fonte clássica de bugs confusos.

O terceiro passo também explica o cache de bytecode: depois de importar shop.prices, a pasta shop/__pycache__/ continha __init__.cpython-313.pyc e prices.cpython-313.pyc. O bytecode compilado é salvo ali para que a próxima partida possa pular a compilação; apague a pasta à vontade, ela é regenerada.

sys.path: onde o Python procura

sys.path é uma lista comum de pastas. Em ordem, ela contém a pasta do script em execução (ou '' para a pasta atual com -c e no prompt interativo), as pastas da variável de ambiente PYTHONPATH, a biblioteca padrão e a pasta site-packages onde os pacotes instalados ficam. Confirmei cada uma: python whereami.py pôs a pasta do próprio script em primeiro, python -c pôs '' em primeiro, e uma pasta citada em PYTHONPATH apareceu na lista.

A primeira correspondência vence, o que leva ao bug mais desconcertante desta área. Criei um arquivo chamado random.py ao lado do meu script que definia uma função random() retornando 'not random'. import random carregou o meu arquivo em vez da biblioteca padrão, porque a pasta do script vem primeiro. Nunca dê aos seus módulos o nome de módulos da biblioteca padrão (random.py, json.py, email.py, test.py, types.py), e se um import devolve algo estranho, imprima module.__file__ para ver de onde ele veio.

Pacotes e imports relativos

Uma pasta com um __init__.py é um pacote (uma pasta sem ele ainda pode funcionar como "pacote de espaço de nomes", mas acrescente o arquivo para código normal). Dentro de um pacote você pode importar irmãos com um ponto na frente: from .prices import gross.

Imports relativos só funcionam quando o módulo é importado como parte do seu pacote. Rodei o mesmo arquivo de dois jeitos:

ComandoResultado
python shop/cli.pyImportError: attempted relative import with no known parent package
python -m shop.cligross(100) = 120.0

Rodar um arquivo como script o torna o __main__ de nível superior sem nenhum pacote em volta; python -m package.module o roda como membro do pacote. Use -m para qualquer coisa dentro de um pacote ou, melhor, instale o projeto (seção 3) e exponha um script de console. É também para isso que serve a guarda if __name__ == "__main__":: __name__ é "__main__" apenas quando o arquivo é executado diretamente, então o código sob a guarda não roda quando o módulo é importado.

Imports circulares

Se a importa b e b importa a, um deles vê o outro pela metade, porque o módulo é guardado em sys.modules antes de seu código terminar. Duas variações que executei:

ImportsResultado
import b dentro de a.py, import a dentro de b.py, usando a.fa() só dentro de uma funçãofunciona (a está totalmente carregado quando a função é chamada)
from c import fc dentro de d.py, e from d import fd dentro de c.pyImportError: cannot import name 'fd' from 'd' (o erro também sugere renomear o arquivo, o que não é a causa aqui)

O estilo import module tolera ciclos porque o atributo é buscado depois; from module import name precisa que o nome exista naquele momento. Correções, da melhor para a pior: reestruture para que a parte compartilhada viva em um terceiro módulo que os dois importam; mova o import para dentro da função que precisa dele; ou importe o módulo em vez do nome. Um ciclo costuma ser sinal de que dois módulos na verdade são um só, ou de que uma dependência aponta para o lado errado.

Custo do import

Imports não são de graça. Uma partida do interpretador vazio levou cerca de 14 ms na minha máquina e uma partida que importou o numpy levou cerca de 92 ms; python -X importtime -c "import json" imprimiu um detalhamento por módulo, com o json custando cerca de 9 ms cumulativos (principalmente json.decoder e re) numa partida a frio. Para ferramentas de linha de comando e funções serverless, o tempo de inicialização é visível para o usuário. Importe bibliotecas pesadas de forma preguiçosa, dentro da função que as usa, e use -X importtime para achar o que é lento.

2. Ambientes virtuais

O problema

Todos os programas Python de uma máquina compartilham um único site-packages, a menos que se diga o contrário. O projeto A precisa de library==1.4, o projeto B precisa de library==2.0, e as ferramentas do próprio sistema operacional precisam de mais uma. Instalar globalmente também arrisca quebrar o sistema (muitas distribuições Linux agora se recusam a fazer pip install no Python do sistema por esse motivo). Um ambiente virtual dá a cada projeto o seu próprio site-packages.

O que é um venv

Não é uma máquina virtual nem uma cópia do Python. Criei um com python3 -m venv .venv e olhei dentro:

Assim, um venv é uma pasta com um lançador que aponta para um interpretador real e um lugar privado para instalar pacotes. Isso tem consequências: você não move nem copia um venv para outra máquina (os caminhos são absolutos); você o recria a partir de um arquivo de requisitos. Também não precisa "ativá-lo": rodar .venv/bin/python diretamente já o usa, e o activate basicamente edita o PATH por conveniência. Não coloque .venv/ no controle de versão; coloque os arquivos que o descrevem (seção 4). Use um venv por projeto e deixe-o fora do contexto de build das imagens Docker.

Interpretadores

Um venv está preso à versão menor do Python que o criou (3.13 aqui). Declare as versões suportadas no pyproject.toml (requires-python), teste em cada uma e fixe a que você implanta. Ferramentas como pyenv ou uv python instalam e escolhem versões do interpretador; em contêineres, quem faz isso é a imagem base.

3. Pacotes e pyproject.toml

Um pacote de distribuição é o que você instala (pip install shop-demo); ele contém um ou mais pacotes de import (import shop). Os metadados que o descrevem ficam no pyproject.toml, o arquivo de configuração padrão (PEP 518 e PEP 621):

[build-system]
requires = ["setuptools>=61"]
build-backend = "setuptools.build_meta"

[project]
name = "shop-demo"
version = "0.1.0"
requires-python = ">=3.9"
dependencies = []

[project.scripts]
shop-hello = "shop.cli:main"

Instalei esse projeto minúsculo em modo editável em um venv novo (pip install -e ., com --no-build-isolation porque o ambiente não conseguia baixar as ferramentas de build) e funcionou: o comando shop-hello imprimiu hello from an installed console script, e importlib.metadata.version('shop-demo') retornou 0.1.0. Uma instalação editável liga o venv à sua pasta de código-fonte, então as edições valem sem reinstalar; esse é o jeito normal de trabalhar em um projeto. Um pip install . simples falhou no ambiente só porque o "isolamento de build" padrão baixa o backend de build do PyPI, que não estava acessível; numa máquina normal funciona.

As distribuições são publicadas em duas formas: uma wheel (.whl, um arquivo pronto para desempacotar, rápido de instalar) e um sdist (código-fonte, construído na instalação). Prefira wheels. Bibliotecas e aplicações são diferentes: uma biblioteca deve declarar faixas de dependência folgadas para poder coexistir com outras; uma aplicação deve instalar versões exatas e fixadas para que seu ambiente seja reproduzível.

4. Versões, requisitos e arquivos de lock

Especificadores de versão

As dependências carregam uma restrição de versão escrita na sintaxe da PEP 440. Avaliei seis especificadores contra as versões disponíveis 1.9.0, 2.0.0, 2.1.0, 2.1.5, 2.2.0, 3.0.0 com a biblioteca packaging, a que o próprio pip usa:

EspecificadorCorresponde a
==2.1.02.1.0
==2.1.*2.1.0, 2.1.5
~=2.1 ("versão compatível")2.1.0, 2.1.5, 2.2.0
~=2.1.02.1.0, 2.1.5
>=2.0,<32.0.0, 2.1.0, 2.1.5, 2.2.0
!=2.1.5,>=2.02.0.0, 2.1.0, 2.2.0, 3.0.0

Dois detalhes pegam as pessoas. ~=2.1 permite qualquer 2.x a partir de 2.1, enquanto ~=2.1.0 permite apenas 2.1.x: o número de componentes decide. E versões não são strings: "10.0" < "9.0" é True, mas Version("10.0") < Version("9.0") é False. Nunca compare números de versão como texto (e não os analise com split improvisado); use packaging.version.

Instalações reproduzíveis

As restrições dizem quais versões são aceitáveis; um arquivo de lock registra as versões exatas (e os hashes) que foram escolhidas, inclusive as dependências indiretas. Sem um, duas instalações com uma semana de diferença podem pegar versões diferentes e se comportar de forma diferente, e uma versão quebrada de uma dependência profunda quebra seu build da noite para o dia. As formas de obter um:

AbordagemO que dá
pip freeze > requirements.txtas versões exatas instaladas agora (listei um venv e obtive linhas como anyio==4.15.1); simples, mas mistura dependências diretas e indiretas e não tem hashes
pip-tools (pip-compile)um requirements.txt fixado, gerado a partir de um arquivo de entrada curto, com hashes opcionais
uv, poetry, pdmuma ferramenta de projeto com seu próprio arquivo de lock (uv.lock, poetry.lock, pdm.lock) e um gerenciador de ambientes
Um arquivo de restrições ou o modo de verificação de hashespip install --require-hashes -r requirements.txt recusa qualquer arquivo cujo hash seja diferente

(Da documentação das ferramentas; não pude rodá-las offline.) Qualquer que seja a sua escolha, faça commit do arquivo de lock, instale a partir dele na CI e em produção, atualize-o de propósito (um pull request que sobe versões, com os testes rodando) e mantenha as ferramentas de desenvolvimento (executor de testes, linters) em um grupo separado das dependências de execução. Em um contêiner, instale as dependências em uma camada anterior à do seu código, para que editar um arquivo-fonte não reinstale tudo (veja contêineres e Kubernetes).

5. Segurança das dependências

Uma instalação executa código de outras pessoas, às vezes na hora de instalar. Os riscos e os controles:

6. Erros comuns

7. Perguntas que os entrevistadores gostam de fazer

"O que é um ambiente virtual e por que usar um?"

Um diretório com seu próprio site-packages e um lançador que aponta para um interpretador real, de modo que cada projeto tem dependências isoladas. sys.prefix difere de sys.base_prefix dentro dele. Não é uma VM e deve ser recriado a partir de um arquivo de lock, não copiado.

"O que acontece quando você faz import de um módulo?"

Verifica sys.modules; caso contrário, o encontra ao longo de sys.path, executa seu código uma vez em um novo espaço de nomes, guarda-o em sys.modules e liga o nome. É por isso que o código de nível de módulo roda uma vez e por que um arquivo local pode ofuscar um módulo padrão.

"Por que imports circulares falham?"

Um módulo está em sys.modules antes de seu código terminar, então o outro módulo pode ver um incompleto. from x import name falha se o nome ainda não foi definido; import x muitas vezes funciona. Corrija reestruturando.

"O que faz o if __name__ == '__main__':?"

Roda o código apenas quando o arquivo é executado diretamente, não quando é importado.

"~=2.1 contra ==2.1.*?"

~=2.1 significa >=2.1, ==2.* (então 2.2 é permitido); ==2.1.* significa exatamente a série 2.1.

"Como você torna uma implantação Python reproduzível?"

Fixe a versão do interpretador, instale a partir de um arquivo de lock com hashes em um ambiente novo ou em uma camada de imagem, construa uma vez e promova o mesmo artefato, e atualize as dependências por mudanças revisadas.

"Qual é a diferença entre uma wheel e um sdist?"

Uma wheel é um arquivo pré-construído que é simplesmente desempacotado na instalação; um sdist é código-fonte que precisa ser construído, o que é mais lento e pode executar código de build arbitrário.

8. Coisas a mencionar em uma entrevista

Resumo rápido

Apêndice: o código dos experimentos

Python 3.13 em Linux, usando o interpretador, o venv, o pip e o setuptools que vieram com ele e a biblioteca packaging (instalada com o pip); nada foi baixado. Os caminhos e os tamanhos que você vir serão diferentes. venv_demo.sh e install_demo.sh são scripts bash; rode install_demo.sh a partir de uma pasta que contenha project_demo/ (o pyproject.toml acima mais src/shop/__init__.py e src/shop/cli.py com def main(): print('hello from an installed console script')).

imports_demo.py: monta um projeto descartável e roda os experimentos de import (cache, imports relativos, ciclos, ofuscação, sys.path, tempo de import, __pycache__):

"""Builds a throwaway project in a temp folder and runs small import experiments against it."""
import os, subprocess, sys, tempfile, textwrap, time

root = tempfile.mkdtemp()
def write(path, text):
    full = os.path.join(root, path); os.makedirs(os.path.dirname(full), exist_ok=True)
    open(full, "w").write(textwrap.dedent(text))
def run(*args, cwd=root, env=None):
    r = subprocess.run([sys.executable, *args], cwd=cwd, capture_output=True, text=True, env=env)
    return (r.stdout + r.stderr).strip()

write("shop/__init__.py", "print('  shop/__init__ runs')\n")
write("shop/prices.py", "print('  shop.prices runs')\nTAX = 0.2\ndef gross(p): return p * (1 + TAX)\n")
write("shop/cli.py", """
    from .prices import gross
    def main(): print('gross(100) =', gross(100))
    if __name__ == '__main__': main()
""")
write("a.py", "import b\ndef fa(): return 'a'\n")
write("b.py", "import a\ndef fb(): return a.fa() + 'b'\n")
write("c.py", "from d import fd\ndef fc(): return 'c'\n")
write("d.py", "from c import fc\ndef fd(): return fc()\n")

print("1. modules are executed once and cached in sys.modules")
print(run("-c", "import shop.prices, shop.prices, shop.prices; import sys; print('  cached:', 'shop.prices' in sys.modules)"))

print("2. relative imports need the package context")
print("  python shop/cli.py ->", run("shop/cli.py").splitlines()[-1])
print("  python -m shop.cli ->", run("-m", "shop.cli").splitlines()[-1])

print("3. circular imports")
print("  import a (module-style `import b`):", run("-c", "import a; print('  ok:', a.fa())"))
print("  import d (from-style `from c import fc`):", run("-c", "import d").splitlines()[-1])

print("4. a local file named like a standard module shadows it")
write("shadow/random.py", "def random(): return 'not random'\n")
print("  ", run("-c", "import random; print(random.__file__.split('/')[-2:], random.random())", cwd=os.path.join(root, "shadow")))

print("5. sys.path decides what `import x` finds")
write("whereami.py", "import sys; print(repr(sys.path[0]))\n")
print("  python whereami.py  -> sys.path[0] is the script's folder:", run("whereami.py") == repr(root))
print("  python -c ...       -> sys.path[0] is:", run("-c", "import sys; print(repr(sys.path[0]))"), "(the current folder)")
print("  PYTHONPATH adds a folder:", run("-c", "import sys; print(any(p.endswith('extra') for p in sys.path))", env={**os.environ, "PYTHONPATH": os.path.join(root, "extra")}))

print("6. import time")
r = subprocess.run([sys.executable, "-X", "importtime", "-c", "import json"], capture_output=True, text=True)
rows = [l for l in r.stderr.splitlines() if l.startswith("import time:") and "|" in l][1:]
cum = sorted(((int(l.split("|")[1]), l.split("|")[2].strip()) for l in rows), reverse=True)[:3]
print("  slowest cumulative imports for `import json` (microseconds):", cum)
t = time.perf_counter(); subprocess.run([sys.executable, "-c", "pass"]); base = time.perf_counter() - t
t = time.perf_counter(); subprocess.run([sys.executable, "-c", "import numpy"]); np_ = time.perf_counter() - t
print(f"  interpreter start {base*1e3:.0f} ms | with `import numpy` {np_*1e3:.0f} ms")

print("7. bytecode cache")
run("-c", "import shop.prices")
print("  __pycache__ files:", sorted(os.listdir(os.path.join(root, "shop", "__pycache__"))))

venv_demo.sh: cria um venv e inspeciona seu layout, sys.prefix e o que ele enxerga:

#!/bin/bash
# Run from an empty scratch folder. Offline-friendly: no packages are downloaded.
set -e
W=$(mktemp -d); cd "$W"
python3 -m venv .venv
echo "--- venv layout"; ls .venv; cat .venv/pyvenv.cfg | sed 's/^/  /'
echo "--- inside the venv"
.venv/bin/python -c "import sys; print('prefix       :', sys.prefix); print('base_prefix  :', sys.base_prefix); print('in a venv    :', sys.prefix != sys.base_prefix)"
echo "--- venv size"; du -sh .venv | cut -f1
echo "--- packages visible"; echo -n "system: "; python3 -m pip list 2>/dev/null | tail -n +3 | wc -l; echo -n "venv  : "; .venv/bin/python -m pip list 2>/dev/null | tail -n +3 | wc -l
echo "--- sys.path in venv"; .venv/bin/python -c "import sys; print('\n'.join('  '+p for p in sys.path if p))"
rm -rf "$W"

install_demo.sh: uma instalação editável de um pequeno projeto local com um script de console:

#!/bin/bash
# Needs only the Python install itself and setuptools (no network): editable install of a tiny local project.
set -e
W=$(mktemp -d); cp -r project_demo "$W/p"; cd "$W/p"
python3 -m venv --system-site-packages .venv
.venv/bin/pip install --no-build-isolation --no-deps -q -e .
.venv/bin/shop-hello
.venv/bin/python -c "import importlib.metadata as m; print(m.version('shop-demo'))"
.venv/bin/pip show shop-demo | sed -n 1,2p

specifiers.py: especificadores de versão e comparação de versões com o packaging:

from packaging.specifiers import SpecifierSet
from packaging.version import Version

available = ["1.9.0", "2.0.0", "2.1.0", "2.1.5", "2.2.0", "3.0.0"]
for spec in ("==2.1.*", "~=2.1", "~=2.1.0", ">=2.0,<3", "!=2.1.5,>=2.0", "==2.1.0"):
    ok = SpecifierSet(spec)
    print(f"{spec:15s} ->", [v for v in available if Version(v) in ok])
print("string comparison '10.0' < '9.0':", "10.0" < "9.0", "| Version comparison:", Version("10.0") < Version("9.0"))

Fontes

  1. Documentação do Python, The import system, Modules e sys.path initialisation.
  2. Documentação do Python, venv: creation of virtual environments.
  3. Python Packaging User Guide, packaging.python.org: Writing your pyproject.toml, Installing packages, src layout vs flat layout e Version specifiers.
  4. Python Enhancement Proposals, PEP 440: Version Identification and Dependency Specification, PEP 518: Specifying Minimum Build System Requirements, PEP 621: Storing project metadata in pyproject.toml, PEP 427: The Wheel Binary Package Format e PEP 668: Marking Python base environments as externally managed.
  5. Documentação do pip, Secure installs and hash-checking mode e Repeatable installs.
  6. Documentação do uv, do pip-tools e do Poetry para arquivos de lock e gerenciamento de projetos; pip-audit para varredura de vulnerabilidades.

Pratique este tema: Python

Mais guias