Como Escrever, Empacotar e Distribuir uma Biblioteca em Python

() translation by (you can also view the original English article)

Python é uma ótima linguagem de programação, mas empacotamento é um dos seus pontos fracos. Esse é um fato já conhecido pela comunidade. A instalação, importação, uso e criação de pacotes melhorou muito ao longo dos anos, mas ainda não está no mesmo nível que novas linguagens de programação como Go e Rust que aprenderam muito com as batalhas do Python e de outras linguagens mais maduras.

Nesse tutorial, nós vamos aprender tudo que você precisa saber para escrever, empacotar e distribuir seus próprios pacotes.

Como Escrever uma Biblioteca em Python

Uma biblioteca Python é uma coleção coerente de módulos Python que são organizados como um pacote Python. No geral, isso significa que todos os módulos vivem dentro do mesmo diretório e que esse diretório está armazenado em um dos caminhos de busca que o Python realiza para carregá-lo.

Vamos, rapidamente, escrever um pacote em Python 3 para ilustrar todos esses conceitos.

O Pacote "Pathology"

Python 3 tem um excelente objeto Path, que é uma melhora incrível sobre as fraquezas que o módulo os.path no Python 2 apresentava. Mas ainda falta uma funcionalidade crucial - encontrar o caminho o script atual. Isso é muito importante quando você quer localizar arquivos de acesso relativos ao script que você está editando.

Em muitos casos, o script pode ser instalado em qualquer local, então você não pode utilizar caminhos absolutos, e o diretório de trabalho pode ser configurado para qualquer valor, e por isso você não pode utilizar caminhos relativos. Se você quiser acessar um arquivo em um sub-diretório ou em um diretório-pai, você precisa descobrir onde o script está localizado.

Aqui está como você pode fazer isso em Python:

1	import pathlib
2
3	script_dir = pathlib.Path(__file__).parent.resolve()

Para acessar o arquivo chamado 'file.txt' que está localizado em um sub-diretório de onde o script está, chamado de 'data', você pode utilizar a seguinte linha de código: print(open(str(script_dir/'data/file.txt').read())

Com o pacote pathology, você tem um método script_dir, e pode utilizá-lo da seguinte forma:

1	from pathology.Path import script_dir
2
3	print(open(str(script_dir()/'data/file.txt').read())
4

Sim, é bem fácil. O pacote 'pathology' é muito simples. Ele chama a própria classe Path - a partir do módulo pathlib, e adiciona uma método estático script_dir() que sempre retorna o caminho do script considerado.

Aqui está a implementação:

import pathlib
import inspect

class Path(type(pathlib.Path())):
    @staticmethod
    def script_dir():
        print(inspect.stack()[1].filename)
        p = pathlib.Path(inspect.stack()[1].filename)
        return p.parent.resolve()

Devido à implementação multi-plataforma da pathlib.Path, você pode derivar a sua implementação diretamente dela a partir de uma sub-classe específica (PosixPath ou WindowsPath). A resolução do diretório do script usa o módulo 'inspect' para descobir o nome do arquivo.

Testando o Pacote "Pathology"

Sempre que você escrever algo mais complexo, você deve testá-lo. O módulo pathology não é exceção. Aqui está os testes utilizando o framework padrão para testes unitários:

import os
import shutil 
from unittest import TestCase
from pathology.path import Path


class PathTest(TestCase):
    def test_script_dir(self):
        expected = os.path.abspath(os.path.dirname(__file__))
        actual = str(Path.script_dir())
        self.assertEqual(expected, actual)

    def test_file_access(self):
        script_dir = os.path.abspath(os.path.dirname(__file__))
        subdir = os.path.join(script_dir, 'test_data')
        if Path(subdir).is_dir():
            shutil.rmtree(subdir)
        os.makedirs(subdir)
        file_path = str(Path(subdir)/'file.txt')
        content = '123'
        open(file_path, 'w').write(content)
        test_path = Path.script_dir()/subdir/'file.txt'
        actual = open(str(test_path)).read()

        self.assertEqual(content, actual)

O Caminho Python

Pacotes Python devem ser instalados em algum lugar que faça parte do caminho de busca que o Python realiza para carregar novos módulos. Essa lista de caminhos é uma lista de diretórios e está disponível em sys.path. Aqui está o meu atual sys.path:

>>> print('\n'.join(sys.path))

/Users/gigi.sayfan/miniconda3/envs/py3/lib/python36.zip
/Users/gigi.sayfan/miniconda3/envs/py3/lib/python3.6
/Users/gigi.sayfan/miniconda3/envs/py3/lib/python3.6/lib-dynload
/Users/gigi.sayfan/miniconda3/envs/py3/lib/python3.6/site-packages
/Users/gigi.sayfan/miniconda3/envs/py3/lib/python3.6/site-packages/setuptools-27.2.0-py3.6.egg 

Note que a primeira linha vazia representa o diretório atual, então você pode sempre importar módulos que estão no diretório atual de trabalho. Além disso você pode adicionar ou remover diretórios do sys.path.

Você também pode definir uma variável de ambiente PYTHONPATH, e existem alguns modos de controlá-la. O site-packages está incluso por padrão, e pra lá que vão os pacotes que você instala utilizando o PIP.

Como Empacotar uma Biblioteca em Python

Agora que você tem seu código testado, vamos empacotar isso tudo em uma biblioteca. Python provê um jeito fácil de fazer isso via o módulo setup. Você cria um arquivo chamado setup.py no diretório raiz do seu pacote. Então, para criar um código de distribuição, você roda: python setup.py sdist

Para criar um arquivo binário chamado de 'wheel', você roda: python setup.py bdist_wheel

Aqui está o arquivo setup.py da nossa biblioteca pathology:

from setuptools import setup, find_packages

setup(name='pathology',
      version='0.1',
      url='https://github.com/the-gigi/pathology',
      license='MIT',
      author='Gigi Sayfan',
      author_email='the.gigi@gmail.com',
      description='Add static script_dir() method to Path',
      packages=find_packages(exclude=['tests']),
      long_description=open('README.md').read(),
      zip_safe=False)

Ele inclui algumas informações em adição ao item 'packages' que usa a função find_packages() importada do setuptools para encontrar sub-pacotes.

Vamos construir uma fonte de distribuição:

$ python setup.py sdist
running sdist
running egg_info
creating pathology.egg-info
writing pathology.egg-info/PKG-INFO
writing dependency_links to pathology.egg-info/dependency_links.txt
writing top-level names to pathology.egg-info/top_level.txt
writing manifest file 'pathology.egg-info/SOURCES.txt'
reading manifest file 'pathology.egg-info/SOURCES.txt'
writing manifest file 'pathology.egg-info/SOURCES.txt'
warning: sdist: standard file not found: should have one of README, README.rst, README.txt

running check
creating pathology-0.1
creating pathology-0.1/pathology
creating pathology-0.1/pathology.egg-info
copying files to pathology-0.1...
copying setup.py -> pathology-0.1
copying pathology/__init__.py -> pathology-0.1/pathology
copying pathology/path.py -> pathology-0.1/pathology
copying pathology.egg-info/PKG-INFO -> pathology-0.1/pathology.egg-info
copying pathology.egg-info/SOURCES.txt -> pathology-0.1/pathology.egg-info
copying pathology.egg-info/dependency_links.txt -> pathology-0.1/pathology.egg-info
copying pathology.egg-info/not-zip-safe -> pathology-0.1/pathology.egg-info
copying pathology.egg-info/top_level.txt -> pathology-0.1/pathology.egg-info
Writing pathology-0.1/setup.cfg
creating dist
Creating tar archive
removing 'pathology-0.1' (and everything under it)

O aviso (em inglês: 'warning') é porque eu utilizei um arquivo README.md não padrão. O resultado é um arquivo tar-gzipped dentro do diretório de distribuição:

$ ls -la dist
total 8
drwxr-xr-x   3 gigi.sayfan  gigi.sayfan   102 Apr 18 21:20 .
drwxr-xr-x  12 gigi.sayfan  gigi.sayfan   408 Apr 18 21:20 ..
-rw-r--r--   1 gigi.sayfan  gigi.sayfan  1223 Apr 18 21:20 pathology-0.1.tar.gz

E aqui está uma distribuição binária:

$ python setup.py bdist_wheel
running bdist_wheel
running build
running build_py
creating build
creating build/lib
creating build/lib/pathology
copying pathology/__init__.py -> build/lib/pathology
copying pathology/path.py -> build/lib/pathology
installing to build/bdist.macosx-10.7-x86_64/wheel
running install
running install_lib
creating build/bdist.macosx-10.7-x86_64
creating build/bdist.macosx-10.7-x86_64/wheel
creating build/bdist.macosx-10.7-x86_64/wheel/pathology
copying build/lib/pathology/__init__.py -> build/bdist.macosx-10.7-x86_64/wheel/pathology
copying build/lib/pathology/path.py -> build/bdist.macosx-10.7-x86_64/wheel/pathology
running install_egg_info
running egg_info
writing pathology.egg-info/PKG-INFO
writing dependency_links to pathology.egg-info/dependency_links.txt
writing top-level names to pathology.egg-info/top_level.txt
reading manifest file 'pathology.egg-info/SOURCES.txt'
writing manifest file 'pathology.egg-info/SOURCES.txt'
Copying pathology.egg-info to build/bdist.macosx-10.7-x86_64/wheel/pathology-0.1-py3.6.egg-info
running install_scripts
creating build/bdist.macosx-10.7-x86_64/wheel/pathology-0.1.dist-info/WHEEL

O pacote pathology contém só módulos puramente escritos em Python, então um pacote universal pode ser construído. Se o seu pacote inclui arquivos em C, você vai ter que construir um 'wheel' separada para cada plataforma:

$ ls -la dist
total 16
drwxr-xr-x   4 gigi.sayfan  gigi.sayfan   136 Apr 18 21:24 .
drwxr-xr-x  13 gigi.sayfan  gigi.sayfan   442 Apr 18 21:24 ..
-rw-r--r--   1 gigi.sayfan  gigi.sayfan  2695 Apr 18 21:24 pathology-0.1-py3-none-any.whl
-rw-r--r--   1 gigi.sayfan  gigi.sayfan  1223 Apr 18 21:20 pathology-0.1.tar.gz

Para um mergulho mais profundo no assunto de empacotamento de bibliotecas Python, confira Como Escrever Seus Próprios Pacotes em Python.

Como Distribuir um Pacote Python

Python tem uma central de repositórios chamada PyPI (Python Packages Index). Quando você instala um pacote utilizando PIP, ele irá baixar o pacote do PyPI (a menos que você determine um repositório diferente). Para distribuir nosso pacote, nós precisamos fazer o upload dele para o PyPI e prover algumas informações extras. Os passos são:

Criar uma conta no PyPI (somente uma).
Registrar seu pacote.
Fazer o upload do seu pacote.

Criar uma Conta

Você pode criar uma conta no website do PyPI. Então, crie um arquivo .pypirc no seu diretório inicial.

[distutils] 
index-servers=pypi
 
[pypi]
repository = https://pypi.python.org/pypi
username = the_gigi

A título de teste, você pode adicionar um "'pypitext' index server" no seu arquivo .pypirc:

[distutils]
index-servers=
    pypi
    pypitest

[pypitest]
repository = https://testpypi.python.org/pypi
username = the_gigi

[pypi]
repository = https://pypi.python.org/pypi
username = the_gigi

Registrar seu Pacote

Se essa é a primeira versão do seu pacote, você precisa registrá-lo dentro do PyPI. Use o comando de registro do setup.py. Ele vai pedir por sua senha. Note que eu o apontei para o repositório de teste aqui:

$ python setup.py register -r pypitest
running register
running egg_info
writing pathology.egg-info/PKG-INFO
writing dependency_links to pathology.egg-info/dependency_links.txt
writing top-level names to pathology.egg-info/top_level.txt
reading manifest file 'pathology.egg-info/SOURCES.txt'
writing manifest file 'pathology.egg-info/SOURCES.txt'
running check
Password:
Registering pathology to https://testpypi.python.org/pypi
Server response (200): OK

Fazer o Upload do seu Pacote

Agora que o seu pacote está registrado, nós podemos fazer o upload dele. Eu recomendo usar o twine, que é mais seguro. Instale-o usualmente através do pip install twine. Então, faça o upload do seu pacote utilizando o twine e fornecendo a sua senha:

1	$ twine upload -r pypitest -p <redacted> dist/*
2	Uploading distributions to https://testpypi.python.org/pypi
3	Uploading pathology-0.1-py3-none-any.whl
4	[================================] 5679/5679 - 00:00:02
5	Uploading pathology-0.1.tar.gz
6	[================================] 4185/4185 - 00:00:01

Para um mergulho mais profundo nesse tópico de distruição de pacotes, confira Como Compartilhar seus Pacotes Python.

Conclusão

Nesse tutorial, nós passamos por todo o processo de escrever uma biblioteca Python, empacotá-la, e distribuí-la no PyPI. Nesse ponto, você deve ter todas as ferramentas necessárias para escrever e compartilhar suas bibliotecas com o mundo.

Em adição, não se hesite em conferir o que nós temos disponível para venda e estudo no nosso maketplace, e por favor, envie qualquer dúvida e dê seu feedback utilizando a seção abaixo.