Builds complexas de pacotes Python#

Este guia é focado em pacotes que são puramente Python ou que possuem algumas extensões simples em outra linguagem, como C ou C++.

Para orientações abrangentes sobre packaging de projetos compilados com extensões em C/C++/Fortran/Rust, consulte o Scientific Python Development Guide sobre packaging de projetos compilados. Essa é a melhor referência para builds complexas e cobre scikit-build-core, meson-python, maturin e outros backends modernos de build.

Se você tiver dúvidas sobre esses tipos de pacote, abra uma issue especificamente sobre este guia no repositório GitHub deste guia. Existem muitas nuances relacionadas à build e distribuição de pacotes Python que possuem extensões compiladas e dependências não Python necessárias em tempo de build. Para uma visão geral e uma discussão detalhada dessas nuances, consulte este site.

Pacotes Python puros vs. pacotes com extensões em outras linguagens#

Você pode classificar a complexidade de pacotes Python em três categorias gerais. Essas categorias, por sua vez, podem ajudar você a selecionar as ferramentas corretas de frontend e backend para packaging.

  1. Pacotes Python puros: são pacotes que dependem apenas de Python para funcionar. Fazer a build de um pacote Python puro é mais simples. Assim, você pode escolher abaixo uma ferramenta que tenha os recursos desejados e finalizar sua decisão!

  2. Pacotes Python com extensões não Python: esses pacotes possuem componentes adicionais chamados extensões, escritos em outras linguagens (como C ou C++). Se você tiver um pacote com extensões não Python, então precisará selecionar uma ferramenta de backend de build que permita etapas adicionais de build necessárias para compilar o código da sua extensão. Além disso, se quiser usar uma ferramenta de frontend para dar suporte ao seu fluxo de trabalho, precisará escolher uma ferramenta que suporte configurações adicionais de build. Sugerimos que você escolha uma ferramenta de build que suporte etapas de build customizadas, como o Hatch.

  3. Pacotes Python que possuem extensões escritas em diferentes linguagens (por exemplo, Fortran e C++) ou que possuem dependências não Python difíceis de instalar (por exemplo, GDAL): esses pacotes frequentemente possuem etapas de build complexas (mais complexas do que um pacote com apenas algumas extensões em C, por exemplo). Assim, esses pacotes exigem ferramentas como scikit-build ou meson-python para build. OBSERVAÇÃO: você pode usar meson-python com PDM.

Misturando projetos frontend e backend#

Às vezes é necessário ou desejável usar um frontend de build com um backend de build alternativo. Isso acontece porque alguns frontends não possuem um backend padrão (build), deixando essa escolha para o mantenedor. Outros backends (hatch) possuem um backend preferido (hatchling), mas permitem que o mantenedor migre para outro, enquanto alguns backends (poetry) funcionam apenas com um único backend (poetry-core). Consulte (#python-package-build-tools) para mais informações sobre compatibilidade entre frontend e backend.

Neste guia de packaging recomendamos usar hatch junto com seu backend preferido hatchling. Embora isso seja adequado para a maioria dos pacotes, um backend alternativo pode ser usado com o Hatch, se necessário, ao criar um módulo de extensão. Um módulo de extensão Python é aquele composto, parcial ou totalmente, por código compilado. Nesse caso, o backend escolhido (como meson-python) precisa saber como compilar a linguagem da extensão e vinculá-la ao Python. O hatchling não sabe fazer isso sozinho e precisa usar plugins ou ser substituído por um backend que já seja capaz de construir módulos de extensão.

Para usar um backend diferente, você precisará editar o arquivo pyproject.toml do seu projeto. Se você tiver um pyproject.toml gerado pelo comando hatch, ou seguindo o tutorial de packaging, talvez precise fazer uma alteração como esta

 [build-system]
-requires = ["hatchling"]
+requires = ["meson-python"]
-build-backend = "hatchling.build"
+build-backend = "mesonpy"