1. Uma Introdução ao Distutils
******************************

Nota:

  Este documento está sendo mantido apenas até que a documentação do
  "setuptools" em
  https://setuptools.readthedocs.io/en/latest/setuptools.html cubra
  independentemente todas as informações relevantes atualmente
  incluídas aqui.

Este documento trata do uso do Distutils tornando possível a
distribuição dos seus módulos Python, podendo assim, concentrar-se no
seu papel de desenvolvedor/distribuidor: caso estejas procurando
informações sobre a instalação de módulos Python, deverás consultar o
capítulo Instalando módulos Python (versão legada).


1.1. Conceitos & Terminologias
==============================

Utilizar o Distutils é bastante simples, tanto para desenvolvedores de
módulos quanto para usuários/administradores que instalam módulos de
terceiros. Como desenvolvedor, suas responsabilidades (além de
escrever um código sólido, bem documentado e bem testado, é claro!)
são:

* escrever um script setup ("setup.py" através da conversão)

* (opcional) escrever um arquivo Setup de configuração

* criar uma distribuição de fontes

* (opcional) criar uma ou mais distribuições compiladas (binárias)

Cada uma dessas tarefas são tratadas neste documento.

Nem todos os desenvolvedores de módulos têm acesso a uma infinidade de
plataformas, portanto, nem sempre é possível esperar que eles criem
uma infinidade de distribuições construídas. Espera-se que uma classe
de intermediários, chamada *empacotadores*, surja para atender a essa
necessidade. Os empacotadores pegam as distribuições fonte lançadas
pelos desenvolvedores do módulo, as compilam em uma ou mais
plataformas e lançam as distribuições compiladas resultantes. Assim,
os usuários das plataformas mais populares poderão instalar as
distribuições mais populares de módulos Python da maneira mais natural
possível para sua plataforma, sem precisar executar um único script de
configuração ou compilar uma linha de código.


1.2. Um Exemplo Simples
=======================

O script de configuração geralmente é bastante simples, embora, como
esteja escrito em Python, não haja limites arbitrários para o que você
pode fazer com ele, mas você deve ter cuidado ao colocar operações
arbitrariamente caras em seu script de configuração. Ao contrário,
digamos, dos scripts de configuração no estilo Autoconf, o script de
instalação pode ser executado várias vezes no decorrer da compilação e
instalação da distribuição do módulo.

Se tudo o que você quer fazer é distribuir um módulo chamado "foo",
contido em um arquivo "foo.py", então seu script de instalação pode
ser tão simples quanto este:

   from distutils.core import setup
   setup(name='foo',
         version='1.0',
         py_modules=['foo'],
         )

Algumas observações:

* a maioria das informações que você fornecerá ao Distutils será
  fornecida como argumentos nomeados para a função "setup()"

* esses argumentos nomeados se enquadram em duas categorias: metadados
  do pacote (nome, número da versão) e informações sobre o conteúdo do
  pacote (uma lista de módulos Python puros, neste caso)

* módulos são especificados pelo nome do módulo, não pelo nome do
  arquivo (o mesmo se aplica aos pacotes e extensões)

* é recomendável que você forneça um pouco mais de metadados, em
  particular seu nome, endereço de e-mail e uma URL para o projeto
  (consulte a seção Escrevendo o Script de Configuração por exemplo)

Para criar uma distribuição fonte para este módulo, você deve criar um
script de instalação, "setup.py", contendo o código acima, e executar
este comando a partir de um terminal:

   python setup.py sdist

No Windows, abra uma janela do prompt de comando (Iniciar ‣
Acessórios) e altere o comando para:

   setup.py sdist

**sdist** criará um arquivo (por exemplo, tarball no Unix, arquivo ZIP
no Windows) contendo seu script de instalação "setup.py" e seu módulo
"foo.py". O arquivo será nomeado "foo-1.0.tar.gz" (ou ".zip") e será
descompactado em um diretório "foo-1.0".

Se um usuário final deseja instalar o seu módulo "foo", tudo o que
eles precisam fazer é baixar "foo-1.0.tar.gz" (ou ".zip"),
descompactá-lo, e --- no diretório "foo-1.0" --- executar:

   python setup.py install

que finalmente copiará "foo.py" para o diretório apropriado para
módulos de terceiros em sua instalação do Python.

Este exemplo simples demonstra alguns conceitos fundamentais dos
Distutils. Primeiro, desenvolvedores e instaladores têm a mesma
interface de usuário básica, ou seja, o script de instalação. A
diferença é que *comandos* do Distutils eles usam: o comando **sdist**
é quase exclusivamente para desenvolvedores de módulos, enquanto
**install** é mais frequentemente para instaladores (embora a maioria
dos desenvolvedores deseje instalar ocasionalmente seu próprio
código).

Se você quiser facilitar as coisas para seus usuários, poderá criar
uma ou mais distribuições criadas para eles. Por exemplo, se você
estiver executando em uma máquina Windows e quiser facilitar as coisas
para outros usuários do Windows, poderá criar um instalador executável
(o tipo mais apropriado de distribuição integrada para esta
plataforma) com o comando **bdist_wininst** . Por exemplo:

   python setup.py bdist_wininst

irá criar um instalador executável, "foo-1.0.win32.exe", no diretório
atual.

Outros formatos de distribuição úteis úteis são o RPM, implementado
pelo comando **bdist_rpm**, **pkgtool** do Solaris (**bdist_pkgtool**)
e **swinstall** do HP-UX (**bdist_sdux**). Por exemplo, o seguinte
comando criará um arquivo RPM chamado "foo-1.0.noarch.rpm":

   python setup.py bdist_rpm

(O comando **bdist_rpm** usa o executável **rpm**, portanto, ele deve
ser executado em um sistema baseado em RPM, como Red Hat Linux, SuSE
Linux ou Mandrake Linux.)

Você pode descobrir quais formatos de distribuição estão disponíveis a
qualquer momento executando:

   python setup.py bdist --help-formats


1.3. Terminologia geral do Python
=================================

Se você está lendo este documento, provavelmente tem uma boa ideia do
que são módulos, extensões e assim por diante. No entanto, apenas para
ter certeza de que todos estão operando de um ponto de partida comum,
oferecemos o seguinte glossário de termos comuns do Python:

module (módulo)
   a unidade básica de reutilização de código em Python: um bloco de
   código importado por algum outro código. Três tipos de módulos nos
   importam aqui: módulos Python puros, módulos de extensão e pacotes.

pure Python module (módulo Python puro)
   um módulo escrito em Python e contido em um único arquivo ".py" (e
   possivelmente arquivos ".pyc" associados). Às vezes referido como
   um "módulo puro".

extension module (módulo de extensão)
   um módulo escrito na linguagem de baixo nível da implementação
   Python: C/C++ para Python, Java para Jython. Normalmente contido em
   um único arquivo pré-compilado carregável dinamicamente, por
   exemplo, um arquivo de objeto compartilhado (".so") para extensões
   Python no Unix, uma DLL (dada a extensão ".pyd") para extensões
   Python no Windows ou um arquivo de classe Java para extensões
   Jython. (Observe que, atualmente, o Distutils só lida com extensões
   C/C++ para Python.)

package (pacote)
   um módulo que contém outros módulos; tipicamente contido em um
   diretório no sistema de arquivos e diferenciado de outros
   diretórios pela presença de um arquivo "__init__.py".

root package (pacote raiz)
   a raiz da hierarquia de pacotes. (Este não é realmente um pacote,
   uma vez que não possui um arquivo "__init__.py". Mas temos que
   chamá-lo de alguma coisa.) A grande maioria da biblioteca padrão
   está no pacote raiz, assim como muitos módulos pequenos e
   independentes de terceiros que não pertencem a uma coleção de
   módulos maior. Ao contrário dos pacotes regulares, os módulos no
   pacote raiz podem ser encontrados em muitos diretórios: na verdade,
   cada diretório listado em "sys.path" contribui com módulos para o
   pacote raiz.


1.4. Terminologia específica do Distutils
=========================================

Os termos a seguir se aplicam mais especificamente ao domínio de
distribuição de módulos Python usando Distutils:

module distribution (distribuição de módulo)
   uma coleção de módulos Python distribuídos juntos como um único
   recurso para download e devem ser instalados *em massa*. Exemplos
   de algumas distribuições de módulos bem conhecidas são NumPy,
   SciPy, Pillow ou mxBase. (Isso seria chamado de *pacote*, exceto
   que o termo já é usado no contexto Python: uma distribuição de
   módulo único pode conter zero, um ou muitos pacotes Python.)

pure module distribution (distribuição de módulo pura)
   uma distribuição de módulo que contém apenas módulos e pacotes
   Python puros. Às vezes chamada de "distribuição pura".

non-pure module distribution (distribuição de módulo não pura)
   uma distribuição de módulo que contém pelo menos um módulo de
   extensão. Às vezes chamada de "distribuição não pura".

distribution root (raiz da distribuição)
   o diretório de nível superior de sua árvore de fontes (ou
   distribuição fonte); o diretório onde existe "setup.py".
   Geralmente, "setup.py" vai ser executado a partir deste diretório.
