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

python setup.py install

python -m pip install .

python setup.py develop

python -m pip install --editable .

python setup.py sdist

python -m build

python setup.py bdist_wheel

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

Onde posso ler mais sobre isso?#