1. Uma Introdução ao Distutils

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 (Legacy version).

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

• criando o fonte de uma distribuição

• (opcional) crie uma ou mais distribuições build (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 de código-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 fornecerás ao Distutils será fornecida como keyword argument pela 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 de fontes 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

For Windows, open a command prompt windows (Start ‣ Accessories) and change the command to:

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.

This simple example demonstrates some fundamental concepts of the Distutils. First, both developers and installers have the same basic user interface, i.e. the setup script. The difference is which Distutils commands they use: the sdist command is almost exclusively for module developers, while install is more often for installers (although most developers will want to install their own code occasionally).

If you want to make things really easy for your users, you can create one or more built distributions for them. For instance, if you are running on a Windows machine, and want to make things easy for other Windows users, you can create an executable installer (the most appropriate type of built distribution for this platform) with the bdist_wininst command. For example:

python setup.py bdist_wininst

will create an executable installer, foo-1.0.win32.exe, in the current directory.

Other useful built distribution formats are RPM, implemented by the bdist_rpm command, Solaris pkgtool (bdist_pkgtool), and HP-UX swinstall (bdist_sdux). For example, the following command will create an RPM file called foo-1.0.noarch.rpm:

python setup.py bdist_rpm

(The bdist_rpm command uses the rpm executable, therefore this has to be run on an RPM-based system such as Red Hat Linux, SuSE Linux, or Mandrake Linux.)

You can find out what distribution formats are available at any time by running

python setup.py bdist --help-formats

1.3. General Python terminology

If you’re reading this document, you probably have a good idea of what modules, extensions, and so forth are. Nevertheless, just to be sure that everyone is operating from a common starting point, we offer the following glossary of common Python terms:

module (módulo)

the basic unit of code reusability in Python: a block of code imported by some other code. Three types of modules concern us here: pure Python modules, extension modules, and packages.

pure Python module

a module written in Python and contained in a single .py file (and possibly associated .pyc and/or .pyo files). Sometimes referred to as a “pure module.”

extension module (módulo de extensão)

a module written in the low-level language of the Python implementation: C/C++ for Python, Java for Jython. Typically contained in a single dynamically loadable pre-compiled file, e.g. a shared object (.so) file for Python extensions on Unix, a DLL (given the .pyd extension) for Python extensions on Windows, or a Java class file for Jython extensions. (Note that currently, the Distutils only handles C/C++ extensions for Python.)

package (pacote)

a module that contains other modules; typically contained in a directory in the filesystem and distinguished from other directories by the presence of a file __init__.py.

root package

the root of the hierarchy of packages. (This isn’t really a package, since it doesn’t have an __init__.py file. But we have to call it something.) The vast majority of the standard library is in the root package, as are many small, standalone third-party modules that don’t belong to a larger module collection. Unlike regular packages, modules in the root package can be found in many directories: in fact, every directory listed in sys.path contributes modules to the root package.

1.4. Distutils-specific terminology

The following terms apply more specifically to the domain of distributing Python modules using the Distutils:

module distribution

a collection of Python modules distributed together as a single downloadable resource and meant to be installed en masse. Examples of some well-known module distributions are Numeric Python, PyXML, Pillow, or mxBase. (This would be called a package, except that term is already taken in the Python context: a single module distribution may contain zero, one, or many Python packages.)

pure module distribution

a module distribution that contains only pure Python modules and packages. Sometimes referred to as a “pure distribution.”

non-pure module distribution

a module distribution that contains at least one extension module. Sometimes referred to as a “non-pure distribution.”

distribution root

the top-level directory of your source tree (or source distribution); the directory where setup.py exists. Generally setup.py will be run from this directory.