Trilha de aprendizado · Nível 15 · Tutorial 7

Gerar e inspecionar wheel e sdist

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.

  • Nível: Intermediário
  • Duração: 20 min
  • 8 passos
Gerar e inspecionar wheel e sdist

O que você vai percorrer

  1. O que cada formato entrega Diferencie os dois formatos de distribuição e o que ainda é necessário para usar cada um. 2 min
  2. 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
  3. 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
  4. 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
  5. 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
  6. 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
  7. 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
  8. 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

O que você vai aprender

  • Distinguir uma wheel de uma distribuição de código-fonte.
  • Gerar os dois formatos com a ferramenta build em ambiente de construção isolado.
  • Inspecionar os arquivos incluídos e corrigir omissões ou inclusões indevidas.
  • Confirmar que a distribuição de código-fonte contém o necessário para gerar a wheel.

Antes de começar

  • Configurar uma distribuição com pyproject.toml

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.

Do projeto aos dois artefatos

Dois formatos, papéis diferentes

Depois de configurar o projeto, ele pode ser distribuído em dois formatos principais:

  • sdist (source distribution): um arquivo com as fontes necessárias para construir o pacote.
  • wheel: um pacote já preparado para uma ferramenta de instalação colocar no ambiente Python.

Os dois representam a mesma aplicação, mas atendem a etapas diferentes.

Comparação dos formatos

A sdist preserva os materiais de construção; a wheel organiza o resultado destinado à instalação.

Diagrama comparando a árvore de fontes de um projeto, uma sdist com fontes e arquivos de configuração, e uma wheel com pacote Python, recursos e metadados.

A wheel não precisa reproduzir a árvore do projeto; ela carrega o que será instalado.

Wheel: pronta para instalar

O que uma wheel entrega

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

Leitura prática

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.

Sdist: fontes para construir

O que uma sdist entrega

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.

Associe formato e característica

Relacione cada elemento à sua característica principal.

Toque em um item e depois no par correspondente.

Passo 2 de 8

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.

Quem coordena a construção

Frontend e backend

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.

Papéis separados na construção

A construção passa por camadas com responsabilidades diferentes.

Diagrama com três blocos conectados: ambiente de trabalho com build, ambiente temporário de construção com setuptools e dependências, e artefatos wheel e sdist como saída.

O build coordena; o backend executa a construção com as dependências declaradas; o resultado são os artefatos.

Instale a ferramenta no ambiente de trabalho

Uma instalação para iniciar a construção

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.

Instalação de build

Com o ambiente virtual de trabalho ativo, execute:

bash
python -m pip install build

Dica

Use o mesmo interpretador

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.

O que o isolamento faz — e o que não faz

Ambiente temporário de construção

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

Isolado não significa seguro

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.

Verifique sua interpretação

Papel de build

A ferramenta build atua como frontend e aciona o backend declarado em pyproject.toml para gerar os artefatos.

Limites do isolamento

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

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.

Projeto de referência para a prática

Crie uma árvore pequena e controlada

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.

Arquivos do projeto

Crie os arquivos mostrados nesta árvore; os blocos seguintes trazem seus conteúdos.

text
agenda-cli/
├── pyproject.toml
├── README.md
├── dados-locais-ficticios.json
└── src/
    └── agenda_cli/
        ├── __init__.py
        ├── __main__.py
        ├── cli.py
        └── recursos/
            └── mensagem.txt

Configuração e arquivos da raiz

toml
# 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"
}

Pacote, comando e recurso

python
# 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.

Construir a partir da raiz

Limpe somente saídas antigas

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.

Limpar e construir

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.

bash
python -c "import shutil; shutil.rmtree('dist', ignore_errors=True)"
python -m build

O fluxo esperado de construção

Diagrama mostrando a árvore do projeto entrando na construção; primeiro sai um arquivo sdist .tar.gz e, a partir dele, é produzida uma wheel .whl no diretório dist.

Na construção padrão, a sdist é criada primeiro; depois, a wheel é construída a partir dessa sdist.

Dica

Leia a execução atual

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.

Reconheça a ordem padrão

Ordene o fluxo

Coloque as ações na ordem em que ocorrem na construção padrão.

  1. Gravar os dois artefatos atuais em dist/
  2. Criar a sdist em dist/
  3. Construir a wheel usando a sdist produzida

Registre os artefatos desta execução

Evite confundir arquivos antigos

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.

Listar caminhos sem ambiguidade

Este comando usa a biblioteca padrão e mostra apenas arquivos diretamente dentro de dist.

bash
python -c "from pathlib import Path; [print(p.resolve()) for p in sorted(Path('dist').iterdir()) if p.is_file()]"

Seu registro de construção

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

Inspecionar o conteúdo da wheel

Liste e leia o conteúdo da wheel atual sem extraí-la nem instalar a aplicação.

Veja o que há dentro da wheel

A wheel é um arquivo ZIP

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:

Listar membros da wheel

bash
python -m zipfile -l dist/agenda_cli-0.1.0-py3-none-any.whl

Caminhos internos não repetem o layout src

Comparação entre uma árvore de projeto com src/agenda_cli e uma wheel cujo conteúdo começa diretamente em agenda_cli, ao lado do diretório agenda_cli-0.1.0.dist-info.

O diretório src organiza o desenvolvimento; dentro da wheel, o pacote aparece diretamente pelo nome importável.

Dica

O que procurar na listagem

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.

Interprete os metadados de distribuição

O papel de .dist-info

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

Exemplo de associação de comando

Em uma wheel que declara o comando agenda, entry_points.txt pode conter:

[console_scripts]
agenda = agenda_cli.cli:main

Isso 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.

Limite da inspeção

O que a presença de entry_points.txt na wheel permite concluir?

Leia membros sem extrair nem instalar

Inspeção textual direcionada

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.

inspecionar_wheel.py

python
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

Não confunda inspeção com teste

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.

Registre sua evidência

Leitura da sua wheel atual

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

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.

A sdist tem uma raiz própria

Liste sem extrair

Na raiz do projeto, use o caminho exato do artefato atual:

python -m tarfile -l dist/lista_tarefas-1.0.0.tar.gz

A 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.

Leia a árvore da sdist

Diagrama de uma sdist tar.gz contendo um diretório de topo e, abaixo dele, pyproject.toml, README.md, fontes em src, um recurso textual, PKG-INFO e um arquivo local suspeito.

Procure a raiz comum antes de comparar os caminhos internos com os arquivos necessários do projeto.

Dica

Compare pelo papel do arquivo

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.

Leia arquivos internos sem descompactar

Inspeção textual dirigida

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.

inspecionar_sdist.py

python
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"))

O que conferir na leitura

Fontes, referências e metadados

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

Procure dados que não pertencem à distribuiçã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.

Classifique os membros

Associe cada membro ao tratamento adequado em uma sdist do projeto de referência.

Toque em um item e depois no par correspondente.

Registre o diagnóstico antes de corrigir

Achados da sdist de referência

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

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.

Diagnóstico: o artefato é a evidência

Existir no projeto não basta

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.

Seleção correta de arquivos

Diagrama mostrando uma árvore de projeto com o arquivo aviso.txt dentro do pacote seguindo para sdist e wheel, enquanto dados-locais-ficticios.txt fica fora dos dois artefatos.

A regra deve incluir o recurso do pacote e excluir o dado local fictício nos artefatos em que ele não pertence.

Dica

Não conclua pela aparência da árvore

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.

Torne a inclusão do recurso explícita

Responsabilidades das regras

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.

Blocos do pyproject.toml

Substitua os blocos de configuração do setuptools por estes, preservando os demais metadados já configurados no seu pyproject.toml.

toml
[tool.setuptools]
package-dir = {"" = "src"}
include-package-data = false

[tool.setuptools.packages.find]
where = ["src"]

[tool.setuptools.package-data]
tarefas = ["resources/*.txt"]

MANIFEST.in corrigido

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.

text
include README.md
recursive-include src/tarefas/resources *.txt
exclude dados-locais-ficticios.txt

Recurso esperado

Confirme que o recurso existe exatamente neste caminho. Se você estiver reproduzindo o caso controlado, crie-o com este conteúdo simples.

text
# src/tarefas/resources/aviso.txt
Lembrete: revise suas tarefas pendentes.

Reconstrua sem editar os arquivos compactados

Atenção

Corrija a configuração, não o ZIP ou o TAR

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/.

Limpar saídas e construir novamente

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.

python
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 build

Exemplo

O que procurar na nova construção

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/.

Compare as novas evidências

Liste os dois artefatos atuais

Troque os dois nomes pelos caminhos exatos mostrados em dist/ após esta reconstrução. Não use curingas nem reutilize um artefato antigo.

bash
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.gz

Critério de correção

Na 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.

Registre a evidência

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

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.

Evidência fora da árvore original

Por que reconstruir?

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.

Fluxo da reconstrução independente

Diagrama mostrando uma sdist tar.gz conhecida sendo extraída em uma pasta externa ao projeto e usada para gerar uma wheel em uma pasta de saída separada.

Use somente a sdist corrigida como origem; não copie arquivos da árvore original.

Atenção

Limite de segurança e de alcance

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.

Extrair e construir em locais separados

Escolha caminhos explícitos

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.

1. Extrair a sdist conhecida

bash
python -m tarfile -e dist/minha_app-0.1.0.tar.gz ../verificacao-sdist

2. Construir somente a wheel a partir das fontes extraídas

bash
cd ../verificacao-sdist/minha_app-0.1.0
python -m build --wheel --outdir ../wheel-reconstruida

Dica

Não complete a pasta manualmente

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.

Conferir a wheel reconstruída

O que o sucesso demonstra

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.

Listar membros da nova wheel

bash
python -m zipfile -l ../verificacao-sdist/wheel-reconstruida/minha_app-0.1.0-py3-none-any.whl

Atenção

Construir não é executar

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.

Registre a evidência

Seu relato de reconstrução

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

Revisão final dos artefatos

Consolide evidências da wheel e da sdist corrigidas antes de encaminhá-las para a próxima validação.

Uma decisão baseada em evidências

Revise os artefatos exatos

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.

Rastreabilidade da revisão

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.

Diagrama mostrando uma wheel e uma sdist passando por identificação do caminho, inspeção de conteúdo e metadados, até uma decisão de encaminhar ou corrigir.

A decisão depende dos artefatos identificados e das evidências registradas para eles.

Dica

Checklist mínimo

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.

Evidência da reconstrução

A sdist sustentou uma nova wheel?

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

Critérios para encaminhar

  • Os caminhos, nomes e versões da wheel e da sdist revisadas estão registrados.
  • A wheel contém os módulos, recursos e metadados esperados; o ponto de entrada está declarado quando aplicável.
  • A sdist contém as fontes e os arquivos de construção necessários, sem dados locais indevidos.
  • A wheel construída exclusivamente a partir da sdist foi inspecionada e tem o conteúdo esperado.
  • Qualquer divergência encontrada exige ajuste na configuração e nova construção; não edite o arquivo compactado manualmente.

Relato de revisão

Registre sua decisão

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).

Conclusão e próximo limite

Atenção

O que esta revisão ainda não prova

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

Você concluiu esta etapa

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.

  • Wheel é o pacote preparado para instalação; sdist fornece fontes para uma construção posterior.
  • A inspeção deve considerar conteúdo, metadados, recursos e exclusão de dados locais indevidos.
  • A reconstrução de uma wheel apenas a partir da sdist é evidência de suficiência das fontes distribuídas.
  • A próxima validação verifica instalação e execução em ambiente limpo; ela não foi substituída por esta revisão.

Tutorial concluído

Parabéns! Você concluiu: Gerar e inspecionar wheel e sdist

Muito bem! Você sabe gerar e inspecionar os artefatos, corrigir sua seleção de arquivos e demonstrar que a sdist pode gerar uma wheel. No próximo tutorial, você validará a aplicação instalada em um ambiente limpo.

Baixe o Aplicativo agora para ter acesso a + de 5000 cursos gratuitos, exercícios, certificado e muito conteúdo sem pagar nada!

  • Cursos online 100% gratuitos do início ao fim

    Milhares de cursos online em vídeo, ebooks e áudiobooks.

  • Mais de 60 mil exercícios gratuitos

    Para testar seus conhecimentos no decorrer dos cursos online

  • Certificado Digital gratuito válido em todo o Brasil

    Gerado diretamente na galeria de fotos do seu celular e enviado ao seu e-mail

Aplicativo Cursa na tela de ebook, na tela de curso em vídeo e na tela de exercícios do curso, mais o certificado de conclusão de curso