Python Academy · Aula

Compilação com build

Crie wheels e sdists

Compilação com build é uma aula grátis de Python Academy no CoddyKit. Esta é a aula 2 de 4. Você pode ler a aula completa abaixo gratuitamente — depois pratica ao vivo no navegador com um editor de código integrado e um tutor de IA 24/7. Faz parte do caminho de aprendizado de Python Academy, e seu progresso é sincronizado entre a web e o app CoddyKit. O curso de Python Academy inclui 4 aulas no total.

O que significa compilar

Seu código-fonte precisa ser transformado em artefatos de distribuição que o pip possa instalar. A ferramenta moderna para isso é build, executada como python -m build.

Ela produz dois tipos de arquivos: uma distribuição de código-fonte e uma distribuição binária.

sdist versus distribuição binária

Há dois tipos de artefato:

sdist (.tar.gz), um arquivo de código-fonte; o pip o compila durante a instalação
distribuição binária (.whl), um arquivo pré-compilado; o pip apenas o descompacta

As distribuições binárias são instaladas mais rapidamente e são preferidas. A sdist é a alternativa e a fonte oficial.

Instalando a ferramenta de compilação

Instale-a uma vez com pip install build. Ela é uma interface simples: lê seu pyproject.toml, configura um ambiente isolado e chama o sistema de compilação para criar os artefatos.

Você não chama o sistema de compilação diretamente; build coordena esse processo.

Executando a compilação

Na raiz do projeto, execute python -m build. Por padrão, ele cria uma sdist e uma distribuição binária e coloca ambas em um novo diretório dist/.

Use --wheel ou --sdist para compilar apenas uma delas.

args = []
targets = []
if '--sdist' in args:
    targets.append('sdist')
if '--wheel' in args:
    targets.append('wheel')
if not targets:
    targets = ['sdist', 'wheel']
print('Will build:', targets)

Nomes de arquivos de distribuições binárias

Os nomes das distribuições binárias codificam metadados: mytool-0.1.0-py3-none-any.whl significa nome mytool, versão 0.1.0, Python 3, nenhuma exigência de ABI e qualquer plataforma. Pacotes compostos apenas de Python recebem py3-none-any.

name = 'mytool'
version = '0.1.0'
wheel = name + '-' + version + '-py3-none-any.whl'
print(wheel)
print('Parts:', wheel[:-4].split('-'))

Isolamento da compilação

Por padrão, build cria um ambiente virtual novo, instala os itens de requires da sua seção [build-system] e compila nesse ambiente. Isso garante que a compilação não dependa acidentalmente de pacotes que estejam apenas por acaso no seu ambiente.

Inspecionando a pasta dist

Depois de uma compilação, dist/ contém seus artefatos. Listá-la confirma o que foi produzido antes do envio. Trata-se de uma listagem comum de diretório.

dist = ['mytool-0.1.0.tar.gz', 'mytool-0.1.0-py3-none-any.whl']
for f in dist:
    kind = 'sdist' if f.endswith('.tar.gz') else 'wheel'
    print(kind.ljust(6), f)

Verificando uma distribuição binária

Uma distribuição binária é apenas um arquivo ZIP. Você pode descompactá-la para verificar se seus módulos e arquivos de dados estão presentes e se nada importante ficou de fora. Se um arquivo estiver ausente aqui, também estará ausente depois da instalação.

Compilações limpas

Arquivos antigos em build/ ou dist/ podem produzir resultados confusos. Exclua esses diretórios antes de uma compilação de lançamento, para publicar exatamente o que o código-fonte atual produz.

stale_dirs = ['build', 'dist', 'mytool.egg-info']
for d in stale_dirs:
    print('Remove before clean build:', d)

Compilações reproduzíveis

O mesmo código-fonte deve sempre produzir os mesmos artefatos. Fixe as versões do sistema de compilação em [build-system] requires e evite obter valores do ambiente em execução. Reprodutibilidade significa que um colega ou servidor de integração contínua obterá uma saída idêntica.

Junto com as compilações limpas, isso elimina as surpresas de algo funcionar apenas na minha máquina.

Compilação em integração contínua

A maioria dos projetos é compilada em um servidor de integração contínua, e não em um laptop. Uma tarefa de integração contínua obtém o código, executa python -m build e armazena os artefatos. Isso garante que os lançamentos venham sempre de um estado conhecido e limpo.

O mesmo comando exato que você executa localmente é executado na integração contínua.

Verificação rápida

Teste seus conhecimentos sobre compilação.

Recapitulação

Você aprendeu a criar artefatos:

pip install build e, em seguida, python -m build
Produz uma sdist (.tar.gz) e uma distribuição binária (.whl) em dist/
As compilações acontecem em um ambiente isolado, usando os requisitos de [build-system]
Inspecione a distribuição binária e faça compilações limpas antes de publicar

Perguntas Frequentes

A aula “Compilação com build” é grátis?

Sim — o texto completo de “Compilação com build” é grátis para ler aqui na web. Para praticá-la interativamente (um editor de código integrado e um tutor de IA 24/7) e desbloquear o restante do curso de Python Academy, atualize para CoddyKit PRO. O curso de Python Academy inclui 4 aulas no total.

O que vou aprender em “Compilação com build”?

Crie wheels e sdists Você pratica Python Academy com código prático que executa diretamente no navegador, e um tutor de IA 24/7 responde suas dúvidas enquanto trabalha na aula.

Preciso ter experiência prévia para começar Python Academy?

Nenhuma experiência prévia é necessária. Python Academy no CoddyKit é estruturado para alunos iniciantes até avançados, então você pode começar aqui ou desde o início e aprender no seu ritmo. Esta é a aula 2 de 4.

Quanto tempo leva a aula “Compilação com build”?

A maioria das aulas CoddyKit leva cerca de 5–10 minutos. Cada uma é compacta e interativa, então você faz progresso constante e retoma exatamente de onde parou entre web e app.

Posso escrever e executar código nesta aula de Python Academy?

Sim. Cada aula de Python Academy inclui um editor de código integrado, então você escreve e executa código real direto no navegador e recebe feedback de IA instantaneamente — nenhuma configuração local necessária.

Todas as aulas deste curso

← Voltar para Python Academy