A Practical Guide to Using Setup.py

Quando você estiver usando python profissionalmente, compensa configurar seus projetos
de uma maneira consistente. Isto ajuda os seus colaboradores a compreender rapidamente a estrutura de um projecto e facilita a montagem do projecto na sua máquina. A chave para configurar seu projeto é o arquivo .setup.py
Neste blog vou entrar nos detalhes deste arquivo.

Onde começamos

Aqui eu assumo que você já tem um pacote que você quer configurar.
Este não precisa ser um pacote acabado – idealmente você deve criar o arquivo
setup.py muito antes do seu projeto estar terminado. Pode até mesmo ser um pacote vazio;
> apenas certifique-se que a pasta do pacote existe
e contém um arquivo chamado init.py (que pode estar vazio).

Se você seguir a estrutura do meu colega Henk
para o seu projeto, sua situação inicial deve se parecer com a seguinte:

example_project/├── exampleproject/ Python package with source code.│ ├── __init__.py Make the folder a package.│ └── example.py Example module.└── README.md README with info of the project.

Você pode ter outros arquivos ou pastas na sua estrutura, por exemplo
pastas com o nome notebooks/, tests/ ou data/, mas estes não são necessários.

O caso de um setup.py

Após ter criado um pacote como este, então é provável que você
use algum do código em outros lugares. Por exemplo, você pode querer
para fazer isso em um notebook:

from exampleproject.example import example_function

Isso funcionaria se seu diretório de trabalho atual fosse example_project/, mas em
todos os outros casos o python lhe dará saída como:

ModuleNotFoundError: No module named 'exampleproject'

Você poderia dizer a python onde procurar o pacote, definindo a variável PYTHONPATH
ambiente ou adicionando o caminho para sys.path,
mas isso está longe de ser o ideal: isso exigiria ações diferentes em plataformas diferentes
, e o caminho que você precisa definir depende da localização do seu código.
Uma maneira muito melhor é instalar seu pacote usando um setup.py e pip,
desde que pip é a maneira padrão de instalar todos os outros pacotes, e é limitado
funciona da mesma maneira em todas as plataformas.

Um exemplo mínimo

Então como é um arquivo setup.py? Aqui está um exemplo mínimo0:

from setuptools import setup, find_packagessetup( name='example', version='0.1.0', packages=find_packages(include=))

Aqui especificamos três coisas:

• O nome do pacote, que é o nome que pip usará para o seu pacote.
  Isso não tem que ser o mesmo nome da pasta que o pacote vive
  em, embora possa ser confuso se não for. Um exemplo de onde o pacote
  nome e o diretório não correspondem é Scikit-Learn: você o instala
  usando pip install scikit-learn, enquanto você o usa importando de sklearn.
• A versão do seu pacote. Esta é a versão pip irá relatar, e é usada
  por exemplo quando você publica o seu pacote em PyPI1.
• Que pacotes incluir; no nosso caso isto é apenas exampleproject/.
  Aqui deixamos setuptools descobrir isto
  automaticamente2. Enquanto você poderia, em princípio, usar find_packages()
  sem quaisquer argumentos, isto pode potencialmente resultar em pacotes indesejados para
  serem incluídos. Isto pode acontecer, por exemplo,
  se você incluir um __init__.py no seu tests/
  directório. Alternativamente, você também pode usar o argumento exclude para explicitamente
  prevenir a inclusão de testes no pacote, mas isto é ligeiramente
  sem robustez.

Agora tudo que você precisa fazer para instalar seu pacote é executar o seguinte
de dentro do diretório example_project/3:

pip install -e .

O . aqui se refere ao diretório de trabalho atual, que eu assumo ser o diretório
onde o setup.py pode ser encontrado. A bandeira -e especifica que queremos instalar o
em modo editável, o que significa
que quando editamos os ficheiros no nosso pacote não precisamos de reinstalar o
package antes das alterações entrarem em vigor. Você precisará ou reiniciar o
pacote ou recarregar o pacote!

Quando você edita a informação no próprio setup.py você precisará reinstalar o
pacote na maioria dos casos, e também se você adicionar novos (sub)pacotes.
Quando em dúvida, nunca pode fazer mal reinstalar. Basta correr pip install -e . novamente.

Requisitos

A maioria dos projetos tem algumas dependências. Você provavelmente já usou
a requirements.txt
file antes, ou um ambiente.yml
se você estiver usando conda. Agora que você está criando um setup.py, você pode especificar suas
dependências no argumento install_requires.
Por exemplo, para um projeto típico de ciência de dados você pode ter:

setup( name='example', version='0.1.0', packages=find_packages(include=), install_requires=)

Você pode especificar requisitos sem uma versão (PyYAML), colocar um pin numa versão (pandas==0.23.3), especificar um mínimo
versão ('numpy>=1.14.5) ou definir um intervalo de versões (matplotlib>=2.2.0,<3.0.0). Estes
requisitos serão automaticamente instalados por pip quando você instalar seu pacote.

Extras-requisitos

Por vezes você pode ter dependências que são necessárias apenas em certas situações. Como cientista de dados
Eu frequentemente faço pacotes que eu uso para treinar um modelo. Quando eu trabalho em tal modelo interativamente
Eu posso precisar ter matplotlib e jupyter instalado para trabalhar interativamente com os
dados e para criar visualizações
do desempenho do modelo. Por outro lado, se o modelo funciona em produção, eu não quero
quer instalar matplotlib nem jupyter na máquina (ou recipiente) onde eu treino
ou fazer inferências. Felizmente setuptools permite especificar dependências opcionais em extras_require:

setup( name='example', version='0.1.0', packages=find_packages(include=), install_requires=, extras_require={ 'interactive': , })

Agora se instalarmos o pacote normalmente (pip install example do PyPI ou pip install -e . localmente)
só instalará as dependências PyYAML, pandas e numpy. Entretanto, quando especificamos
que queremos as dependências opcionaisinteractive (pip install example
ou pip install -e .),
então matplotlib e jupyter também serão instaladas.

Scripts e pontos de entrada

O principal caso de uso da maioria dos pacotes python que você instala a partir do PyPI é para fornecer funcionalidade
que pode ser usada em outro código python. Em outras palavras, você pode import a partir desses pacotes.
Como um cientista de dados eu frequentemente faço pacotes que não são destinados a ser usados por outros códigos python mas
são destinados a fazer algo, por exemplo, para treinar um modelo. Como tal, muitas vezes tenho um script python que
Eu quero executar a partir da linha de comando.

A melhor maneira4 de expor a funcionalidade do seu pacote à linha de comando é definir
an entry_point como tal:

setup( # ..., entry_points={ 'console_scripts': })

Agora você pode usar o comando my-command a partir da linha de comando, que por sua vez executará a main
função dentro de exampleproject/example.py. Não se esqueça de reinstalar – senão o comando
não será registrado.

Testes

Quando você escrever qualquer código, eu recomendo fortemente que você também escreva testes para este código. Para testes
com python sugiro que você use pytest. Claro que você não quer adicionar pytest às suas dependências
em install_requires: não é requerido pelos usuários do seu pacote. Para tê-lo instalado
automaticamente quando você executar testes você pode adicionar o seguinte ao seu setup.py:

setup( # ..., setup_requires=, tests_require=,)

Adicionalmente você terá que criar um arquivo chamado setup.cfg com o seguinte conteúdo:

test=pytest

Agora você pode simplesmente executar python setup.py test e setuptools irá garantir as dependências necessárias
são instaladas e executar pytest para você! Dê uma olhada aqui se
você quiser fornecer argumentos ou definir opções de configuração para pytest.

Se você tiver quaisquer requisitos adicionais para testes (por exemplo, pytest-flask) você pode adicioná-los a tests_require.

Flake8

Pessoalmente eu acho que é uma boa idéia executar Flake8 a
marque a formatação do seu código. Assim como com pytest, você não quer adicionar flake8 à
install_requires dependências: ele não precisa ser instalado para usar o seu
package. Ao invés disso, você pode adicioná-lo a setup_requires:

setup( # ..., setup_requires=)

Agora você pode simplesmente executar python setup.py flake8. É claro que você também pode colocar um pin na versão
de flake8 (ou qualquer outro pacote) em setup_requires.

Se você quiser alterar alguns dos parâmetros de configuração do Flake8 você pode adicionar uma seção a
a sua setup.cfg. Por exemplo:

max-line-length=120

Dados do pacote

Algumas vezes você pode querer incluir alguns arquivos não-python no seu pacote. Estes
podem ser, por exemplo, arquivos de esquemas ou uma pequena tabela de pesquisa. Esteja ciente de que tais arquivos
serão empacotados junto com seu código, então é em geral uma má idéia incluir
quaisquer arquivos grandes.

Suponha que tenhamos um schema.json em nosso projeto, que colocamos em exampleproject/data/schema.json.
Se quisermos incluir isso em nosso pacote, devemos usar o argumento package_data de setup:

setup( # ..., package_data={'exampleproject': })

Isso vai garantir que o arquivo seja incluído no pacote. Também podemos optar por incluir
todos os arquivos baseados em um padrão, por exemplo:

setup( # ..., package_data={'': })

Isso irá adicionar todos os arquivos *.json em qualquer pacote que encontrar.

Agora não tente descobrir a localização dos ficheiros instalados, pois
pkg_resources tem algumas funções de conveniência muito úteis:

• pkg_resources.resource_stream dar-lhe-á um fluxo do ficheiro, tal como o
  objecto que obtém quando chama open(),
• pkg_resources.resource_string dar-lhe-á o conteúdo do ficheiro como uma string,
• pkg_resources.resource_filename dar-lhe-á o nome do ficheiro (e extrai
  para um temporário se estiver incluído num pacote zipado) para se as duas opções
  acima não se adequarem às suas necessidades.

Por exemplo, poderíamos ler no nosso esquema usando:

from json import loadfrom pkg_resources import resource_streamschema = load(resource_stream('exampleproject', 'data/schema.json'))

Metadata

Se vai publicar o seu pacote, então provavelmente quer dar aos seus
utilizadores potenciais mais alguma informação sobre o seu pacote, incluindo uma descrição,
o nome do autor ou mantenedor, e a url para a página inicial do pacote.
Você pode encontrar uma lista completa de todos os metadados permitidos no arquivo setuptools
docs.

Adicionalmente, se você vai publicar no PyPI, então você pode querer
carregar automaticamente o conteúdo do seu README.md
para o long_description,
e fornecer classificadores para dizer pip até mesmo
mais sobre o seu pacote.

>

Embrulho

Este blog deve ser um bom ponto de partida para configurar a maioria dos seus projetos python.
Se você quiser ler mais sobre embalagens python dê uma olhada
nos docs. Aqui está um exemplo setup.py
que combina todas as partes mostradas neste blog:

from setuptools import setup, find_packagessetup( name='example', version='0.1.0', description='Setting up a python package', author='Rogier van der Geer', author_email='[email protected]', url='https://blog.godatadriven.com/setup-py', packages=find_packages(include=), install_requires=, extras_require={'plotting': }, setup_requires=, tests_require=, entry_points={ 'console_scripts': }, package_data={'exampleproject': })

e os acompanhantes setup.cfg:

test=pytestmax-line-length=120

Aprimore suas habilidades em Python, aprenda com os especialistas!

Na GoDataDriven oferecemos uma série de cursos de Python de iniciante a especialista, ensinados pelos melhores profissionais da área. Junte-se a nós e melhore seu jogo Python:

• Python Essentials – Ótimo se você está apenas começando com Python.
• Certified Data Science with Python Foundation – Quer passar da análise e visualização de dados para a verdadeira ciência de dados? Este é o curso certo.
• Ciência de Dados Avançada com Python – Aprenda a produzir seus modelos como um profissional e use Python para o aprendizado de máquinas.

Notas de rodapé

0: Neste blog eu usei as ferramentas de configuração
para configurar meu projeto de exemplo. Alternativamente
você também poderia usar distutils,
que é a ferramenta padrão para empacotamento em python, mas falta-lhe características
como a função find_packages() e entry_points.
como o uso de setuptools é muito comum hoje em dia e muitas de suas características
podem ser particularmente úteis, eu sugiro que você use setuptools.

1: Se você quiser que a versão de seu pacote também esteja disponível dentro do python,
dê uma olhada aqui.

2: Você também poderia listar seus pacotes manualmente, mas isto é particularmente propenso a erros.

3: Alternativamente você poderia rodar python setup.py install, mas usando pip tem
many benefits, entre os quais estão a instalação automática de dependências e a
abilidade de desinstalar ou atualizar seu pacote.

4: Você também poderia usar o argumento scripts (veja por
examplo aqui)
mas como isto requer que você crie um script python shell pode não funcionar
como bem (ou de todo) no Windows.