Como modernizar um projeto baseado em setup.py
?#
pyproject.toml
deve ser adicionado?#
Um arquivo pyproject.toml é fortemente recomendado. A presença de um arquivo pyproject.toml
em si não traz muita coisa. [1] O que é realmente recomendado é a tabela [build-system]
no pyproject.toml
.
Deve o setup.py
ser excluído?#
Não, setup.py
pode existir em um projeto moderno baseado em Setuptools. O arquivo setup.py é um arquivo de configuração válido para setuptools que foi escrito em Python. No entanto, os seguintes comandos for descontinuados e NÃO DEVEM ser mais executados, e seus comandos de substituição recomendados devem ser usados:
Descontinuado |
Recomendação |
---|---|
|
|
|
|
|
|
|
Para mais detalhes:
Onde começar?#
O projeto deve conter um arquivo pyproject.toml
na raiz de sua árvore de fontes que contém uma tabela [build-system]
como esta:
[build-system]
requires = ["setuptools"]
build-backend = "setuptools.build_meta"
Este é o método padronizado para permitir que frontends de construção saibam que Setuptools é o backend de construção para este projeto.
Observe que a presença de um arquivo pyproject.toml
(mesmo que vazio) aciona pip para alterar seu comportamento padrão para usar isolamento de construção.
Para mais detalhes:
Como lidar com dependências de tempo de construção adicionais?#
Além do próprio setuptools, se setup.py
depende de outras bibliotecas de terceiros (fora da biblioteca padrão do Python), elas devem ser listadas na lista requires
do [build-system ]
tabela, para que o frontend de construção saiba instalá-los ao construir as distribuições.
Por exemplo, um arquivo setup.py
como este:
import setuptools
import some_build_toolkit # comes from the `some-build-toolkit` library
def get_version():
version = some_build_toolkit.compute_version()
return version
setuptools.setup(
name="my-project",
version=get_version(),
)
requer um arquivo pyproject.toml
como este (setup.py
permanece inalterado):
[build-system]
requires = [
"setuptools",
"some-build-toolkit",
]
build-backend = "setuptools.build_meta"
Para mais detalhes:
Qual é o recurso de isolamento de compilação?#
Frontends de construção normalmente criam um ambiente virtual efêmero onde instalam apenas as dependências de construção (e suas dependências) listadas em build-system.requires
e acionam a construção nesse ambiente.
Para alguns projetos este isolamento é indesejado e pode ser desativado da seguinte forma:
python -m build --no-isolation
python -m pip install --no-build-isolation
Para mais detalhes:
Como lidar com metadados de empacotamento?#
Todos os metadados estáticos podem opcionalmente ser movidos para uma tabela [project]
em pyproject.toml
.
Por exemplo, um arquivo setup.py
como este:
import setuptools
setuptools.setup(
name="my-project",
version="1.2.3",
)
pode ser totalmente substituído por um arquivo pyproject.toml
como este:
[build-system]
requires = ["setuptools"]
build-backend = "setuptools.build_meta"
[project]
name = "my-project"
version = "1.2.3"
Leia Declaring project metadata: the [project] table para a especificação completa do conteúdo permitido na tabela [project]
.
Como lidar com metadados dinâmicos?#
Se alguns campos de metadados de empacotamento não forem estáticos, eles precisam ser listados como dynamic
nesta tabela [project]
.
Por exemplo, um arquivo setup.py
como este:
import setuptools
import some_build_toolkit
def get_version():
version = some_build_toolkit.compute_version()
return version
setuptools.setup(
name="my-project",
version=get_version(),
)
pode ser modernizado desta forma:
[build-system]
requires = [
"setuptools",
"some-build-toolkit",
]
build-backend = "setuptools.build_meta"
[project]
name = "my-project"
dynamic = ["version"]
import setuptools
import some_build_toolkit
def get_version():
version = some_build_toolkit.compute_version()
return version
setuptools.setup(
version=get_version(),
)
Para mais detalhes:
E se alguma coisa que não possa ser alterar esperar um arquivo setup.py
?#
Por exemplo, existe um processo que não pode ser alterado facilmente e precisa executar um comando como python setup.py --name
.
É perfeitamente normal deixar um arquivo setup.py
na árvore de fontes do projeto mesmo depois de todo o seu conteúdo ter sido movido para pyproject.toml
. Este arquivo pode ser tão minimalista quanto este:
import setuptools
setuptools.setup()