This document is for an old version of Python that is no longer supported. You should upgrade and read the documentação do Python para versão estável atual.

# 7. Examples

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.

## 7.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.

## 7.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'],
          )

## 7.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'])],
          )