# 6. Exemplos de 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 capítulo fornece vários exemplos básicos para ajudar a começar com distutils. Informações adicionais sobre o uso de distutils podem ser encontradas no Distutils Cookbook.

Ver também

Distutils Cookbook

  Coleção de receitas mostrando como obter mais controle sobre distutils.

## 6.1. Distribuição Python pura (por módulo)

Se você está apenas distribuindo alguns módulos, especialmente se eles não residem em um pacote específico, você pode especificá-los individualmente usando a opção `py_modules` no script de instalação.

No caso mais simples, você terá dois arquivos com os quais se preocupar: um script de instalação e o único módulo que você está distribuindo `foo.py` neste exemplo:

    <root>/
            setup.py
            foo.py

(Em todos os diagramas desta seção, <root> se refere ao diretório raiz da distribuição.) Um script de instalação mínimo para descrever essa situação seria:

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

Observe que o nome da distribuição é especificado independentemente com a opção `name`, e não existe uma regra que diga que deve ser igual ao nome do único módulo na distribuição (embora seja provavelmente uma boa convenção a seguir ) No entanto, o nome da distribuição é usado para gerar nomes de arquivos, portanto, você deve usar letras, dígitos, sublinhados e hífenes.

Como `py_modules` é uma lista, é claro que você pode especificar vários módulos, por exemplo. se você estiver distribuindo os módulos `foo` e `bar`, sua configuração poderá ser assim:

    <root>/
            setup.py
            foo.py
            bar.py

e o script de configuração pode ser

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

Você pode colocar os arquivos fonte do módulo em outro diretório, mas se você tiver módulos suficientes para fazer isso, provavelmente será mais fácil especificar módulos por pacote do que listá-los individualmente.

## 6.2. Distribuição Python pura (por pacote)

Se você tiver mais do que alguns módulos para distribuir, especialmente se estiverem em vários pacotes, provavelmente será mais fácil especificar pacotes inteiros do que módulos individuais. Isso funciona mesmo que seus módulos não estejam em um pacote; você pode simplesmente dizer ao Distutils para processar os módulos do pacote raiz, e isso funciona da mesma forma que em qualquer outro pacote (exceto que você não precisa ter um arquivo `__init__.py`).

O script de instalação do último exemplo também pode ser escrito como

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

(A string vazia representa o pacote raiz.)

Se esses dois arquivos forem movidos para um subdiretório, mas permanecerem no pacote raiz, por exemplo:

    <root>/
            setup.py
            src/      foo.py
                      bar.py

você ainda especificaria o pacote raiz, mas precisará informar ao Distutils onde estão os arquivos fonte no pacote raiz:

    from distutils.core import setup
    setup(name='foobar',
          version='1.0',
          package_dir={'': 'src'},
          packages=[''],
          )

Mais tipicamente, porém, você deseja distribuir vários módulos no mesmo pacote (ou em subpacotes). Por exemplo, se os módulos `foo` e `bar` pertencem ao pacote `foobar`, uma maneira de fazer o layout da sua árvore de fontes é

    <root>/
            setup.py
            foobar/
                     __init__.py
                     foo.py
                     bar.py

Na verdade, esse é o layout padrão esperado pelo Distutils e o que exige menos trabalho para descrever no seu script de instalação:

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

Se você quiser colocar módulos em diretórios não nomeados para o pacote, precisará usar a opção `package_dir` novamente. Por exemplo, se o diretório `src` contiver módulos no pacote `foobar`:

    <root>/
            setup.py
            src/
                     __init__.py
                     foo.py
                     bar.py

um script de instalação apropriado seria

    from distutils.core import setup
    setup(name='foobar',
          version='1.0',
          package_dir={'foobar': 'src'},
          packages=['foobar'],
          )

Ou, você pode colocar módulos do seu pacote principal diretamente na raiz da distribuição:

    <root>/
            setup.py
            __init__.py
            foo.py
            bar.py

nesse caso, seu script de instalação seria

    from distutils.core import setup
    setup(name='foobar',
          version='1.0',
          package_dir={'foobar': ''},
          packages=['foobar'],
          )

(A string vazia também representa o diretório atual.)

Se você possui subpacotes, eles devem ser listados explicitamente em `packages`, mas qualquer entrada em `package_dir` se estende automaticamente aos subpacotes. (Em outras palavras, o Distutils não varre sua árvore de fontes, tentando descobrir quais diretórios correspondem aos pacotes Python procurando `__init__.py`.) Portanto, se o layout padrão aumentar um subpacote:

    <root>/
            setup.py
            foobar/
                     __init__.py
                     foo.py
                     bar.py
                     subfoo/
                               __init__.py
                               blah.py

então o script de instalação correspondente seria

    from distutils.core import setup
    setup(name='foobar',
          version='1.0',
          packages=['foobar', 'foobar.subfoo'],
          )

## 6.3. Módulo de extensão única

Os módulos de extensão são especificados usando a opção `ext_modules`. `package_dir` não afeta onde os arquivos de origem das extensões são encontrados; isso afeta apenas a fonte dos módulos Python puros. O caso mais simples, um único módulo de extensão em um único arquivo fonte C, é:

    <root>/
            setup.py
            foo.c

Se a extensão `foo` pertencer ao pacote raiz, o script de instalação para isso pode ser

    from distutils.core import setup
    from distutils.extension import Extension
    setup(name='foobar',
          version='1.0',
          ext_modules=[Extension('foo', ['foo.c'])],
          )

Se a extensão realmente pertence a um pacote, digamos `foopkg`, então

Com exatamente o mesmo layout da árvore de fontes, esta extensão pode ser colocada no pacote `foopkg` simplesmente alterando o nome da extensão:

    from distutils.core import setup
    from distutils.extension import Extension
    setup(name='foobar',
          version='1.0',
          ext_modules=[Extension('foopkg.foo', ['foo.c'])],
          )

## 6.4. Verificando um pacote

O comando `check` permite verificar se os metadados do seu pacote atendem aos requisitos mínimos para construir uma distribuição.

Para executá-lo, basta chamá-lo usando o script `setup.py`. Se algo estiver faltando, `check` exibirá um aviso.

Vamos dar um exemplo com um script simples:

    from distutils.core import setup

    setup(name='foobar')

A execução do comando `check` exibirá alguns avisos:

    $ python setup.py check
    running check
    warning: check: missing required meta-data: version, url
    warning: check: missing meta-data: either (author and author_email) or
             (maintainer and maintainer_email) should be supplied

Se você usar a sintaxe reStructuredText no campo `long_description` e o docutils estiver instalado, poderá verificar se a sintaxe está correta com o comando `check`, usando a opção `restructuredtext`.

Por exemplo, se o script `setup.py` for alterado assim:

    from distutils.core import setup

    desc = """\
    My description
    ==============

    This is the description of the ``foobar`` package.
    """

    setup(name='foobar', version='1', author='tarek',
        author_email='tarek@ziade.org',
        url='http://example.com', long_description=desc)

Onde a descrição longa está quebrada, `check` poderá detectá-la usando o analisador `docutils`:

    $ python setup.py check --restructuredtext
    running check
    warning: check: Title underline too short. (line 2)
    warning: check: Could not finish the parsing.

## 6.5. Lendo os metadados

A função `distutils.core.setup()` fornece uma interface de linha de comando que permite consultar os campos de metadados de um projeto através do script `setup.py` de um projeto fornecido:

    $ python setup.py --name
    distribute

Essa chamada lê os metadados `name` executando a função `distutils.core.setup()`. Embora, quando uma distribuição de origem ou binária é criada com o Distutils, os campos de metadados sejam gravados em um arquivo estático chamado `PKG-INFO`. Quando um projeto baseado no Distutils é instalado no Python, o arquivo `PKG-INFO` é copiado juntamente com os módulos e pacotes da distribuição em `NOME-VERSÃO-pyX.X.egg-info`, em que `NOME` é o nome do projeto, `VERSÃO` sua versão conforme definida nos metadados e `pyX.X` a versão principal e secundária do Python, como `2.7` ou `3.2`.

Você pode ler novamente esse arquivo estático usando a classe `distutils.dist.DistributionMetadata` e seu método `read_pkg_file()`:

    >>> from distutils.dist import DistributionMetadata
    >>> metadata = DistributionMetadata()
    >>> metadata.read_pkg_file(open('distribute-0.6.8-py2.7.egg-info'))
    >>> metadata.name
    'distribute'
    >>> metadata.version
    '0.6.8'
    >>> metadata.description
    'Easily download, build, install, upgrade, and uninstall Python packages'

Observe que a classe também pode ser instanciada com um caminho de arquivo de metadados para carregar seus valores:

    >>> pkg_info_path = 'distribute-0.6.8-py2.7.egg-info'
    >>> DistributionMetadata(pkg_info_path).name
    'distribute'