
Passo 1 de 8
O que cada formato entrega
Diferencie os dois formatos de distribuição e o que ainda é necessário para usar cada um.
Trilha de aprendizado · Nível 15 · Tutorial 7
Construir os artefatos da aplicação e conferir se contêm os arquivos e metadados necessários para distribuição, sem incluir dados locais indevidos.
O que cada formato entrega
Diferencie os dois formatos de distribuição e o que ainda é necessário para usar cada um. 2 min
Entender a construção isolada
Entenda como a ferramenta build coordena o backend do projeto em um ambiente temporário de construção e quais limites esse isolamento possui. 2 min
Gerar e identificar os artefatos atuais
Monte um projeto de referência, execute a construção padrão e registre exatamente quais artefatos foram gerados nesta execução. 3 min
Inspecionar o conteúdo da wheel
Liste e leia o conteúdo da wheel atual sem extraí-la nem instalar a aplicação. 3 min
Conferir os arquivos da sdist
Liste e examine a distribuição de fontes para confirmar o que será entregue para construção, identificando fontes necessárias e dados locais indevidos. 3 min
Corrigir omissões e inclusões indevidas
Ajuste regras de seleção no setuptools e confirme a correção reconstruindo e comparando os dois artefatos. 4 min
Reconstruir a wheel usando apenas a sdist
Use a distribuição de fontes já inspecionada para gerar uma nova wheel fora da árvore original do projeto. 2 min
Revisão final dos artefatos
Consolide evidências da wheel e da sdist corrigidas antes de encaminhá-las para a próxima validação. 2 min

Passo 1 de 8
Diferencie os dois formatos de distribuição e o que ainda é necessário para usar cada um.
Depois de configurar o projeto, ele pode ser distribuído em dois formatos principais:
Os dois representam a mesma aplicação, mas atendem a etapas diferentes.
A sdist preserva os materiais de construção; a wheel organiza o resultado destinado à instalação.

A wheel não precisa reproduzir a árvore do projeto; ela carrega o que será instalado.
Uma wheel é um arquivo de distribuição preparado para instalação. Ela pode conter módulos .py, recursos do pacote — como arquivos de texto — e metadados que descrevem a distribuição.
Ela não é um executável autônomo: para funcionar, ainda precisa de um interpretador Python compatível. As dependências de execução também não são copiadas automaticamente para dentro dela; elas são declaradas como requisitos para serem obtidas no ambiente de destino.
Dica
Pense na wheel como o pacote que a ferramenta de instalação sabe posicionar no ambiente. Ela entrega sua aplicação, não um computador Python completo.
A sdist é uma distribuição de código-fonte. Ela inclui as fontes e os arquivos necessários para uma construção posterior, como a configuração do projeto e documentos por ela referenciados.
Antes de instalar a aplicação a partir de uma sdist, normalmente é necessário construir uma wheel. Por isso, a sdist é especialmente importante para verificar se o material de origem distribuído é suficiente para gerar o pacote de instalação.
Relacione cada elemento à sua característica principal.
Toque em um item e depois no par correspondente.

Passo 2 de 8
Entenda como a ferramenta build coordena o backend do projeto em um ambiente temporário de construção e quais limites esse isolamento possui.
No projeto configurado anteriormente, o comando de construção é coordenado pelo pacote build. Ele é um frontend: lê a configuração do projeto e chama o backend declarado em pyproject.toml.
Neste projeto, o backend é setuptools.build_meta, informado em [build-system]. O frontend não substitui o backend: ele organiza o processo e solicita que o backend gere os artefatos.
A construção passa por camadas com responsabilidades diferentes.

O build coordena; o backend executa a construção com as dependências declaradas; o resultado são os artefatos.
No ambiente virtual que você usa para trabalhar no projeto, instale o frontend build. Execute o comando na raiz ou em outro diretório qualquer: ele instala uma ferramenta no ambiente ativo, não dentro do pacote da sua aplicação.
Com o ambiente virtual de trabalho ativo, execute:
python -m pip install buildDica
Prefira python -m pip a um pip isolado. Assim, a instalação fica associada ao interpretador Python e ao ambiente virtual que você verificou como ativos.
Ao construir, o build normalmente cria um ambiente temporário separado. Nele, disponibiliza as dependências de construção declaradas em [build-system] e as dependências adicionais que o backend solicitar.
Esse ambiente é diferente tanto do seu ambiente de trabalho quanto do ambiente futuro em que alguém instalará e executará a aplicação. Em geral, obter dependências de construção exige acesso à rede. Construir não significa instalar sua aplicação para uso nem executar seus testes.
Atenção
O isolamento separa dependências de construção; ele não é uma sandbox de segurança. O backend e etapas de construção podem executar código do projeto. Construa apenas projetos e dependências em que você confia.
A ferramenta build atua como frontend e aciona o backend declarado em pyproject.toml para gerar os artefatos.
Como a construção ocorre em ambiente isolado, é seguro construir código não confiável e o processo já valida a aplicação instalada.

Passo 3 de 8
Monte um projeto de referência, execute a construção padrão e registre exatamente quais artefatos foram gerados nesta execução.
Em uma pasta nova chamada agenda-cli, crie exatamente a estrutura abaixo. Ela usa o layout src, um recurso textual e um arquivo local inteiramente fictício. O arquivo local existe para que você aprenda, nas próximas etapas, a conferir se dados que não pertencem à distribuição foram incluídos por engano.
Use estes conteúdos completos antes de construir.
Crie os arquivos mostrados nesta árvore; os blocos seguintes trazem seus conteúdos.
agenda-cli/
├── pyproject.toml
├── README.md
├── dados-locais-ficticios.json
└── src/
└── agenda_cli/
├── __init__.py
├── __main__.py
├── cli.py
└── recursos/
└── mensagem.txt# pyproject.toml
[build-system]
requires = ["setuptools>=68"]
build-backend = "setuptools.build_meta"
[project]
name = "agenda-cli-exemplo"
version = "0.1.0"
description = "CLI mínima para praticar a geração de artefatos"
readme = "README.md"
requires-python = ">=3.10"
[project.scripts]
agenda-exemplo = "agenda_cli.cli:main"
[tool.setuptools]
package-dir = {"" = "src"}
[tool.setuptools.packages.find]
where = ["src"]
# README.md
# Agenda CLI — exemplo
Projeto mínimo usado para praticar a construção de wheel e sdist.
# dados-locais-ficticios.json
{
"usuario_teste": "ana-exemplo",
"preferencia": "apenas-dado-ficticio"
}# src/agenda_cli/__init__.py
"""Pacote de exemplo para construção."""
# src/agenda_cli/__main__.py
from .cli import main
if __name__ == "__main__":
raise SystemExit(main())
# src/agenda_cli/cli.py
def main() -> int:
print("Agenda de exemplo pronta.")
return 0
# src/agenda_cli/recursos/mensagem.txt
Mensagem de recurso da Agenda CLI.
No terminal, entre em agenda-cli: a pasta que contém pyproject.toml. Antes de cada construção, remova somente o diretório de saída dist. Não apague src, os arquivos da raiz nem seu ambiente virtual.
O comando abaixo não falha se dist ainda não existir.
Execute estes comandos na raiz do projeto. Caso ainda não tenha instalado a ferramenta, faça isso no ambiente de trabalho com python -m pip install build.
python -c "import shutil; shutil.rmtree('dist', ignore_errors=True)"
python -m build
Na construção padrão, a sdist é criada primeiro; depois, a wheel é construída a partir dessa sdist.
Dica
A saída costuma indicar a criação da distribuição de fontes e, depois, a criação da wheel. Procure as mensagens finais de sucesso e os caminhos exibidos. Para esta versão, os nomes esperados em dist são agenda_cli_exemplo-0.1.0.tar.gz e agenda_cli_exemplo-0.1.0-py3-none-any.whl.
Coloque as ações na ordem em que ocorrem na construção padrão.
Liste o diretório dist e registre os dois caminhos completos da execução que você acabou de fazer. Não use curingas, como dist/*, nem escolha o primeiro arquivo encontrado: nome e versão identificam o artefato que será conferido nas próximas etapas.
Este comando usa a biblioteca padrão e mostra apenas arquivos diretamente dentro de dist.
python -c "from pathlib import Path; [print(p.resolve()) for p in sorted(Path('dist').iterdir()) if p.is_file()]"Após executar a construção, informe os caminhos exatos da sua .tar.gz e da sua .whl. Em uma frase, relate qual artefato a saída mostrou primeiro e se a execução terminou com sucesso.
Escreva pelo menos 80 caracteres (0/80).

Passo 4 de 8
Liste e leia o conteúdo da wheel atual sem extraí-la nem instalar a aplicação.
A wheel (.whl) é um arquivo ZIP preparado para instalação. Para examinar a wheel que você acabou de gerar, use o caminho exato que registrou no step anterior — não escolha o primeiro arquivo encontrado em dist.
Por exemplo, se o artefato atual for dist/agenda_cli-0.1.0-py3-none-any.whl, execute na raiz do projeto:
python -m zipfile -l dist/agenda_cli-0.1.0-py3-none-any.whl
O diretório src organiza o desenvolvimento; dentro da wheel, o pacote aparece diretamente pelo nome importável.
Dica
Confira se os módulos do pacote e cada recurso necessário aparecem com seus caminhos internos. A wheel não precisa reproduzir a árvore do projeto: é esperado que src/ não apareça nela.
Além do pacote, a wheel contém um diretório terminado em .dist-info. Ele descreve a distribuição instalada:
METADATA: nome, versão, versão mínima de Python e dependências declaradas.WHEEL: informações sobre o formato e a compatibilidade da wheel.RECORD: relação dos membros distribuídos; nesta etapa, use-o como inventário, sem tentar verificá-lo criptograficamente.entry_points.txt: associação entre o comando instalado e uma função Python, quando o projeto declara um ponto de entrada.A existência de entry_points.txt mostra o que será criado na instalação, mas ainda não demonstra que o comando funciona.
Exemplo
Em uma wheel que declara o comando agenda, entry_points.txt pode conter:
[console_scripts]
agenda = agenda_cli.cli:mainIsso associa o comando agenda à função main do módulo agenda_cli.cli. Compare esse valor com o ponto de entrada que você declarou no seu pyproject.toml.
O que a presença de entry_points.txt na wheel permite concluir?
A listagem revela os caminhos; o script abaixo lê apenas os membros textuais relevantes diretamente da wheel. Ajuste somente a variável wheel_path para o caminho exato do seu artefato atual e, se necessário, os nomes esperados em expected_members.
from pathlib import Path
from zipfile import ZipFile
wheel_path = Path("dist/agenda_cli-0.1.0-py3-none-any.whl")
expected_members = {
"agenda_cli/__init__.py",
"agenda_cli/__main__.py",
"agenda_cli/cli.py",
"agenda_cli/resources/mensagem.txt",
}
with ZipFile(wheel_path) as wheel:
members = set(wheel.namelist())
print(f"Wheel: {wheel_path}")
print("\nMembros esperados:")
for member in sorted(expected_members):
status = "OK" if member in members else "AUSENTE"
print(f"- {status}: {member}")
dist_info_dirs = sorted(
name for name in members if ".dist-info/" in name
)
if not dist_info_dirs:
raise SystemExit("Nenhum diretório .dist-info foi encontrado.")
dist_info = dist_info_dirs[0].split("/", 1)[0]
print(f"\nDiretório de metadados: {dist_info}")
for filename in ("METADATA", "WHEEL", "entry_points.txt"):
member = f"{dist_info}/{filename}"
print(f"\n--- {member} ---")
if member in members:
print(wheel.read(member).decode("utf-8"))
else:
print("Não presente nesta wheel.")
record = f"{dist_info}/RECORD"
print(f"\nRECORD presente: {record in members}")Atenção
Se o script indicar que um módulo, recurso ou metadado esperado está ausente, registre a divergência para corrigir a configuração depois. Não edite manualmente o conteúdo compactado da wheel. E, mesmo que tudo esteja presente, ainda não conclua que a aplicação instalada funciona.
Com base na wheel atual, informe: (1) dois módulos ou caminhos do pacote que estão presentes; (2) um recurso esperado que está presente ou ausente; (3) o Name, a Version e o Requires-Python lidos em METADATA; e (4) o comando e a função indicados em entry_points.txt. Termine explicando por que isso ainda não valida a execução da aplicação.
Escreva pelo menos 120 caracteres (0/120).

Passo 5 de 8
Liste e examine a distribuição de fontes para confirmar o que será entregue para construção, identificando fontes necessárias e dados locais indevidos.
Na raiz do projeto, use o caminho exato do artefato atual:
python -m tarfile -l dist/lista_tarefas-1.0.0.tar.gzA listagem de uma sdist costuma começar por um diretório de topo, como lista_tarefas-1.0.0/. Todos os membros ficam abaixo dele. Isso evita que os arquivos sejam soltos diretamente no diretório onde o arquivo fosse extraído.

Procure a raiz comum antes de comparar os caminhos internos com os arquivos necessários do projeto.
Dica
A sdist não precisa repetir a estrutura interna da wheel. Ela pode incluir fontes, documentação e arquivos de construção que não aparecem como equivalentes diretos na wheel. Avalie se cada membro é necessário para construir ou documentar a distribuição — não apenas se ele também existe na wheel.
Você pode abrir membros textuais diretamente no .tar.gz, sem extrair a sdist inteira. Ajuste apenas o nome do arquivo se a sua versão for diferente. O script abaixo mostra pyproject.toml, README.md e PKG-INFO quando eles existem.
from pathlib import Path
import tarfile
sdist = Path("dist/lista_tarefas-1.0.0.tar.gz")
membros_desejados = {
"pyproject.toml",
"README.md",
"PKG-INFO",
}
with tarfile.open(sdist, "r:gz") as arquivo:
membros = arquivo.getmembers()
nomes = [membro.name for membro in membros]
raiz = nomes[0].split("/", 1)[0]
print(f"Diretório de topo: {raiz}")
for membro in membros:
nome_curto = membro.name.removeprefix(f"{raiz}/")
if nome_curto not in membros_desejados:
continue
conteudo = arquivo.extractfile(membro)
if conteudo is None:
continue
print(f"\n--- {membro.name} ---")
print(conteudo.read().decode("utf-8"))Em pyproject.toml, confirme que os arquivos referenciados — por exemplo, README.md — também estão na sdist. Confira ainda os módulos em src/ e qualquer recurso textual que a aplicação distribui.
PKG-INFO é um metadado gerado para a sdist. Compare nele Name: e Version: com os valores da wheel atual. A presença de PKG-INFO não é uma inclusão indevida só por ele não ser um arquivo-fonte.
Atenção
Revise a listagem em busca de ambientes virtuais, credenciais, configurações privadas e dados de usuários. Nos exemplos, trate qualquer dado local apenas como fictício. Um arquivo como dados_locais.json pode existir durante o desenvolvimento, mas não deve seguir na sdist se não fizer parte do produto.
Associe cada membro ao tratamento adequado em uma sdist do projeto de referência.
Toque em um item e depois no par correspondente.
Na sdist de referência, a inspeção encontrou pyproject.toml, README.md, os módulos em src/ e PKG-INFO. Porém, o recurso necessário src/lista_tarefas/recursos/mensagem.txt está ausente e dados_locais.json foi incluído por engano.
Em poucas frases, registre quais membros são necessários, qual está faltando e qual deve ser removido da futura distribuição.
Escreva pelo menos 40 caracteres (0/40).

Passo 6 de 8
Ajuste regras de seleção no setuptools e confirme a correção reconstruindo e comparando os dois artefatos.
A listagem anterior é o diagnóstico: um arquivo presente na árvore do projeto pode ficar fora da wheel ou da sdist; outro pode entrar por uma regra ampla demais.
Neste caso controlado, o recurso necessário é src/tarefas/resources/aviso.txt, mas ele não apareceu na wheel. Já dados-locais-ficticios.txt, localizado na raiz, apareceu indevidamente na sdist. O nome é fictício: nunca use dados reais de usuários, credenciais ou configurações privadas para testar esse cenário.

A regra deve incluir o recurso do pacote e excluir o dado local fictício nos artefatos em que ele não pertence.
Dica
Arquivos ignorados pelo controle de versão não são automaticamente excluídos dos artefatos. Do mesmo modo, um arquivo versionado não é automaticamente incluído. Confira sempre as regras de empacotamento e as listagens geradas.
Use package-data para declarar o recurso que pertence ao pacote e deve chegar à wheel. Use MANIFEST.in de forma pontual para compor a sdist e excluir o arquivo local.
Aqui, include-package-data = false deixa a seleção da wheel deliberada: a wheel receberá o recurso declarado em package-data, não inclusões incidentais guiadas pelo manifesto. Como o fluxo padrão constrói a wheel a partir da sdist, o recurso também precisa estar disponível na sdist.
Substitua os blocos de configuração do setuptools por estes, preservando os demais metadados já configurados no seu pyproject.toml.
[tool.setuptools]
package-dir = {"" = "src"}
include-package-data = false
[tool.setuptools.packages.find]
where = ["src"]
[tool.setuptools.package-data]
tarefas = ["resources/*.txt"]Crie ou substitua o arquivo MANIFEST.in na raiz do projeto por este conteúdo. A regra específica inclui o recurso nas fontes; a exclusão protege contra a presença do dado local fictício.
include README.md
recursive-include src/tarefas/resources *.txt
exclude dados-locais-ficticios.txtConfirme que o recurso existe exatamente neste caminho. Se você estiver reproduzindo o caso controlado, crie-o com este conteúdo simples.
# src/tarefas/resources/aviso.txt
Lembrete: revise suas tarefas pendentes.Atenção
Não extraia, edite e compacte manualmente uma wheel ou sdist. A próxima construção descartaria essa alteração. Primeiro separe as saídas antigas; remova cache de empacotamento somente se você o tiver identificado, como build/ ou src/tarefas.egg-info/.
Na raiz do projeto, execute este script apenas se esses caminhos forem os caches e saídas identificados no seu projeto. Ele não toca em src/, no ambiente virtual nem nos seus arquivos de trabalho.
from pathlib import Path
import shutil
for caminho in (
Path("dist"),
Path("build"),
Path("src/tarefas.egg-info"),
):
if caminho.exists():
print(f"Removendo: {caminho}")
shutil.rmtree(caminho)
# Depois, no terminal da mesma raiz:
# python -m buildExemplo
Após executar python -m build, espere dois arquivos novos em dist/: uma sdist como tarefas_cli-0.1.0.tar.gz e uma wheel como tarefas_cli-0.1.0-py3-none-any.whl (os nomes refletem o nome e a versão do seu projeto).
A construção padrão gera a sdist e então gera a wheel a partir dela. Se falhar por falta de um arquivo, ajuste a configuração ou o arquivo-fonte correspondente; não copie arquivos manualmente para dentro de dist/.
Troque os dois nomes pelos caminhos exatos mostrados em dist/ após esta reconstrução. Não use curingas nem reutilize um artefato antigo.
python -m zipfile -l dist/tarefas_cli-0.1.0-py3-none-any.whl
python -m tarfile -l dist/tarefas_cli-0.1.0.tar.gzNa wheel, procure tarefas/resources/aviso.txt. Na sdist, procure o caminho sob o diretório de topo, como tarefas_cli-0.1.0/src/tarefas/resources/aviso.txt. Em ambas as listagens, dados-locais-ficticios.txt não deve aparecer.
Compare também nome e versão com os artefatos anteriores: a mudança deve afetar a seleção de arquivos, não trocar acidentalmente o artefato avaliado.
Depois de aplicar a correção e reconstruir, relate a evidência observada nas duas listagens: onde o recurso necessário apareceu e se o arquivo local fictício deixou de aparecer.
Escreva pelo menos 80 caracteres (0/80).

Passo 7 de 8
Use a distribuição de fontes já inspecionada para gerar uma nova wheel fora da árvore original do projeto.
A construção padrão já gerou a wheel a partir da sdist. Agora, repita essa evidência de forma independente: extraia a sdist corrigida e conhecida em uma pasta nova, fora do projeto, e construa apenas a wheel a partir dali.
Se funcionar, há evidência de que a sdist contém as fontes e arquivos de construção necessários. Isso não testa a instalação nem a execução da aplicação; essa validação virá depois.

Use somente a sdist corrigida como origem; não copie arquivos da árvore original.
Atenção
Extraia apenas uma sdist que você mesmo acabou de gerar ou cuja procedência conhece. O isolamento de construção organiza dependências de construção, mas não é uma sandbox: o backend e o projeto podem executar código durante a build.
Também será necessário ter Python, a ferramenta build e as dependências de construção declaradas disponíveis — normalmente obtidas pela rede. A sdist não inclui automaticamente esses elementos.
Partindo da raiz do projeto, substitua minha_app-0.1.0.tar.gz pelo nome exato da sua sdist atual. Os comandos abaixo usam ../verificacao-sdist, uma pasta irmã do projeto, para evitar qualquer dependência acidental das fontes originais.
python -m tarfile -e dist/minha_app-0.1.0.tar.gz ../verificacao-sdistcd ../verificacao-sdist/minha_app-0.1.0
python -m build --wheel --outdir ../wheel-reconstruidaDica
Não copie módulos, recursos, README ou arquivos de configuração da árvore original para a pasta extraída. Se a construção só funcionar após uma cópia, a sdist está incompleta e deve ser corrigida na configuração de empacotamento, não no arquivo compactado.
Ao terminar sem erro, localize o arquivo exato em ../verificacao-sdist/wheel-reconstruida. Liste seu conteúdo sem instalar nada. Confira os módulos e recursos esperados, além do diretório .dist-info e seus metadados.
A wheel pode ter nome semelhante à anterior, mas foi produzida fora da árvore original: registre também esse caminho para não confundir os artefatos.
python -m zipfile -l ../verificacao-sdist/wheel-reconstruida/minha_app-0.1.0-py3-none-any.whlAtenção
Uma build bem-sucedida mostra que as fontes declaradas bastaram para criar a wheel. Ela pode não revelar um recurso que só é acessado durante a execução. Por isso, mantenha a inspeção de módulos, recursos e metadados; o teste da aplicação instalada em ambiente limpo é uma etapa posterior.
Relate: qual foi o caminho da sdist usada; onde ela foi extraída; onde a nova wheel foi gerada; e quais módulos, recursos ou metadados você confirmou. Finalize distinguindo essa evidência de um teste de execução.
Escreva pelo menos 120 caracteres (0/120).

Passo 8 de 8
Consolide evidências da wheel e da sdist corrigidas antes de encaminhá-las para a próxima validação.
A revisão final não é apenas confirmar que existe algo em dist/. Registre os caminhos exatos da wheel corrigida e da sdist corrigida, incluindo nome e versão. Assim, você não confunde uma saída atual com um arquivo antigo que tenha permanecido no diretório.
Use a mesma sequência de evidências para os dois formatos: identificar o arquivo, listar o conteúdo, conferir metadados e registrar a conclusão.

A decisão depende dos artefatos identificados e das evidências registradas para eles.
Dica
Para a wheel, confira módulos, recursos do pacote, .dist-info e ponto de entrada quando houver. Para a sdist, confira fontes, pyproject.toml, README e demais arquivos referenciados. Em ambas, procure dados locais indevidos, como ambientes virtuais, credenciais, configurações privadas ou dados de usuários.
Registre que você extraiu a sdist corrigida em um diretório novo, construiu uma wheel a partir dela e inspecionou a wheel resultante. A evidência esperada é: a construção terminou com sucesso e a nova wheel contém os módulos, recursos e metadados esperados — sem copiar arquivos manualmente da árvore original.
Resumo
Produza um relato de revisão em 3 a 6 frases. Identifique a wheel e a sdist revisadas, cite evidências de conteúdo e da reconstrução a partir da sdist, declare se encontrou inclusão indevida e indique a próxima conclusão correta.
Escreva pelo menos 180 caracteres (0/180).
Atenção
Uma construção bem-sucedida e uma inspeção correta não provam que a aplicação instalada funciona. Elas também podem não revelar um recurso usado somente durante a execução. A próxima etapa é validar o artefato instalado em um ambiente limpo, separada da árvore de desenvolvimento.
Resumo
Agora você consegue tratar wheel e sdist como entregas rastreáveis: gerar, identificar, abrir, conferir, corrigir e reconstruir antes da validação de execução.
Parabéns! Você concluiu: Gerar e inspecionar wheel e sdist
Milhares de cursos online em vídeo, ebooks e áudiobooks.
Para testar seus conhecimentos no decorrer dos cursos online
Gerado diretamente na galeria de fotos do seu celular e enviado ao seu e-mail
Baixe nosso aplicativo pelo QR Code ou pelos links abaixo:.
+ de 10 milhões
de alunos
Certificado grátis e
válido em todo o Brasil
60 mil exercícios
gratuitos
4,8/5 classificação
nas lojas de apps
Cursos gratuitos em
vídeo, ebooks e audiobooks