Instalando módulos Python (versão legada)

Autor

Greg Ward

Ver também

Instalando módulos Python

A documentação de instalação do módulo atualizada. Para o uso regular do Python, você provavelmente deseja aquela documentação em vez desta.

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.

Nota

Este guia cobre apenas as ferramentas básicas para construir e distribuir extensões que são fornecidas como parte desta versão do Python. Ferramentas de terceiros oferecem alternativas mais fáceis de usar e mais seguras. Consulte a quick recommendations section no Guia do Usuário de Pacotes Python para maiores informações

Introdução

No Python 2.0, a API distutils foi adicionada pela primeira vez à biblioteca padrão. Isso forneceu aos mantenedores das distros Linux uma maneira padrão de converter projetos Python em pacotes de distro Linux, e aos administradores de sistema uma maneira padrão de instalá-los diretamente nos sistemas de destino.

Nos muitos anos desde que o Python 2.0 foi lançado, acoplar fortemente o sistema de compilação e o instalador do pacote ao ciclo de lançamento do tempo de execução da linguagem tornou-se problemático e agora é recomendado que os projetos usem o instalador de pacotes pip e o sistema de compilação setuptools, ao invés de usar distutils diretamente.

Veja Instalando módulos Python e Distribuindo módulos Python para mais detalhes.

Esta documentação legada está sendo mantida apenas até que tenhamos certeza de que a documentação do setuptools cobre tudo o que é necessário.

Distribuições de fonte baseadas em Distutils

Se você fizer o download de uma distribuição fonte do módulo, poderá saber rapidamente se ele foi empacotado e distribuído da maneira padrão, ou seja, usando o Distutils. Primeiro, o nome da distribuição e o número da versão aparecerão de forma proeminente no nome do arquivo baixado, por exemplo, foo-1.0.tar.gz ou widget-0.9.7.zip. Em seguida, o arquivo será descompactado em um diretório com nome semelhante: foo-1.0 ou widget-0.9.7. Além disso, a distribuição conterá um script de configuração setup.py, e um arquivo chamado README.txt ou possivelmente apenas README, que deve explicar a construção e instalação da distribuição de módulo é uma simples questão de executar um comando de um terminal:

python setup.py install

Para Windows, este comando deve ser executado de uma janela de prompt de comando (Iniciar ‣ Acessórios):

setup.py install

Se tudo isso for verdade, então você já sabe como construir e instalar os módulos que acabou de baixar: execute o comando acima. A menos que você precise instalar coisas de uma maneira não padronizada ou personalizar o processo de construção, você realmente não precisa deste manual. Ou melhor, o comando acima é tudo que você precisa para extrair deste manual.

Construção e instalação padrão

Conforme descrito na seção Distribuições de fonte baseadas em Distutils, construir e instalar uma distribuição de módulo usando o Distutils é geralmente um comando simples para executar a partir de um terminal:

python setup.py install

Variações de plataforma

Você deve sempre executar o comando de configuração a partir do diretório raiz da distribuição, ou seja, o subdiretório de nível superior no qual a distribuição fonte do módulo descompacta. Por exemplo, se você acabou de baixar uma distribuição fonte do módulo foo-1.0.tar.gz em um sistema Unix, a coisa normal a fazer é:

gunzip -c foo-1.0.tar.gz | tar xf -    # unpacks into directory foo-1.0
cd foo-1.0
python setup.py install

No Windows, você provavelmente baixaria foo-1.0.zip. Se você baixou o arquivo para C:\Temp, então ele seria descompactado em C:\Temp\foo-1.0; você pode usar um manipulador de arquivo com uma interface gráfica de usuário (como WinZip) ou uma ferramenta de linha de comando (como unzip ou pkunzip) para descompactar o arquivo. Em seguida, abra uma janela de prompt de comando e execute:

cd c:\Temp\foo-1.0
python setup.py install

Dividindo o trabalho

A execução de setup.py install constrói e instala todos os módulos de uma vez. Se você preferir trabalhar de forma incremental – especialmente útil se quiser personalizar o processo de construção ou se as coisas estiverem dando errado – você pode usar o script de configuração para fazer uma coisa por vez. Isto é particularmente útil quando a construção e instalação serão feitas por usuários diferentes – por exemplo, você pode querer construir uma distribuição de módulo e entregá-la a um administrador de sistema para instalação (ou faça você mesmo, com privilégios de superusuário).

Por exemplo, você pode construir tudo em uma etapa e, em seguida, instalar tudo em uma segunda etapa, invocando o script de configuração duas vezes:

python setup.py build
python setup.py install

Se você fizer isso, você notará que executar o comando install primeiro executa o comando build, que – neste caso – rapidamente nota que não tem nada a fazer, já que tudo no diretório build está atualizado.

Você pode não precisar dessa habilidade para quebrar as coisas com frequência se tudo o que fizer for instalar módulos baixados da rede, mas é muito útil para tarefas mais avançadas. Se você começar a distribuir seus próprios módulos e extensões Python, executará muitos comandos distutils individuais por conta própria.

Como a construção funciona

Como implícito acima, o comando build é responsável por colocar os arquivos a serem instalados em um diretório de construção. Por padrão, é build na raiz da distribuição; se você está excessivamente preocupado com a velocidade, ou deseja manter a árvore de fontes intocada, você pode alterar o diretório de construção com a opção --build-base. Por exemplo:

python setup.py build --build-base=/path/to/pybuild/foo-1.0

(Ou você poderia fazer isso permanentemente com uma diretiva em seu sistema ou arquivo de configuração pessoal do Distutils; consulte a seção Arquivos de configuração do Distutils.) Normalmente, isso não é necessário.

O layout padrão para a árvore de construção é o seguinte:

--- build/ --- lib/
or
--- build/ --- lib.<plat>/
               temp.<plat>/

onde <plat> expande-se para uma breve descrição do sistema operacional/plataforma de hardware atual e versão Python. A primeira forma, com apenas um diretório lib, é usada para “distribuições de módulos puros” – isto é, distribuições de módulos que incluem apenas módulos Python puros. Se uma distribuição de módulo contém quaisquer extensões (módulos escritos em C/C++), então a segunda forma, com dois diretórios <plat>, é usada. Nesse caso, o diretório temp.plat contém arquivos temporários gerados pelo processo de compilação/vinculação que não são realmente instalados. Em ambos os casos, o diretório lib (ou lib.plat) contém todos os módulos Python (Python puro e extensões) que serão instalados.

No futuro, mais diretórios serão adicionados para lidar com scripts Python, documentação, executáveis binários e tudo o mais que for necessário para lidar com o trabalho de instalação de módulos e aplicações Python.

Como a instalação funciona

Depois que o comando build é executado (se você o executa explicitamente ou o comando install faz isso por você), o trabalho do comando install é relativamente simples: tudo o que ele tem a fazer é copiar tudo em build/lib (ou build/lib.plat) para o diretório de instalação escolhido.

If you don’t choose an installation directory—i.e., if you just run setup.py install—then the install command installs to the standard location for third-party Python modules. This location varies by platform and by how you built/installed Python itself. On Unix (and macOS, which is also Unix-based), it also depends on whether the module distribution being installed is pure Python or contains extensions (“non-pure”):

Plataforma	Local de instalação padrão	Valor padrão	Notas
Unix (puro)	prefix/lib/pythonX.Y/site-packages	/usr/local/lib/pythonX.Y/site-packages	(1)
Unix (não puro)	exec-prefix/lib/pythonX.Y/site-packages	/usr/local/lib/pythonX.Y/site-packages	(1)
Windows	prefix\Lib\site-packages	C:\PythonXY\Lib\site-packages	(2)

Notas:

1. A maioria das distribuições Linux inclui Python como uma parte padrão do sistema, então prefix e exec-prefix são geralmente /usr no Linux. Se você construir Python no Linux (ou qualquer sistema semelhante ao Unix), o padrão de prefix e exec-prefix é /usr/local.

2. O diretório de instalação padrão no Windows era C:\Program Files\Python no Python 1.6a1, 1.5.2 e anterior.

prefix and exec-prefix stand for the directories that Python is installed to, and where it finds its libraries at run-time. They are always the same under Windows, and very often the same under Unix and macOS. You can find out what your Python installation uses for prefix and exec-prefix by running Python in interactive mode and typing a few simple commands. Under Unix, just type python at the shell prompt. Under Windows, choose Start ‣ Programs ‣ Python X.Y ‣ Python (command line). Once the interpreter is started, you type Python code at the prompt. For example, on my Linux system, I type the three Python statements shown below, and get the output as shown, to find out my prefix and exec-prefix:

Python 2.4 (#26, Aug  7 2004, 17:19:02)
Type "help", "copyright", "credits" or "license" for more information.
>>> import sys
>>> sys.prefix
'/usr'
>>> sys.exec_prefix
'/usr'

Alguns outros espaços reservados são usados neste documento: X.Y representa a versão do Python, por exemplo 3.2; abiflags será substituído pelo valor de sys.abiflags ou pela string vazia para plataformas que não definem sinalizadores ABI; distname será substituído pelo nome da distribuição de módulo sendo instalado. Pontos e letras maiúsculas são importantes nos caminhos; por exemplo, um valor que usa python3.2 no UNIX normalmente usará Python32 no Windows.

Se você não deseja instalar módulos no local padrão, ou se não tem permissão para escrever lá, então você precisa ler sobre instalações alternativas na seção Instalação alternativa. Se você deseja personalizar seus diretórios de instalação mais intensamente, consulte a seção Instalação personalizada sobre instalações personalizadas.

Instalação alternativa

Frequentemente, é necessário ou desejável instalar módulos em um local diferente do local padrão para módulos Python de terceiros. Por exemplo, em um sistema Unix, você pode não ter permissão para escrever no diretório de módulo de terceiros padrão. Ou você pode querer experimentar um módulo antes de torná-lo uma parte padrão da instalação local do Python. Isso é especialmente verdadeiro ao atualizar uma distribuição já presente: você deseja ter certeza de que sua base de scripts existente ainda funciona com a nova versão antes de realmente atualizar.

O comando install do Distutils é projetado para tornar a instalação de distribuições de módulos em um local alternativo simples e indolor. A ideia básica é que você forneça um diretório base para a instalação, e o comando install escolhe um conjunto de diretórios (chamado de esquema de instalação) neste diretório base no qual deseja instalar os arquivos. Os detalhes variam entre as plataformas, portanto, leia qualquer uma das seções a seguir que se aplique a você.

Observe que os vários esquemas de instalação alternativos são mutuamente exclusivos: você pode passar --user, ou --home, ou --prefix e --exec-prefix, ou --install-base e --install-platbase, mas você não pode misturar a partir destes grupos.

Instalação alternativa: o esquema usuário

Este esquema foi projetado para ser a solução mais conveniente para usuários que não têm permissão de escrita no diretório global de pacotes de sites ou não desejam instalar nele. É habilitado com uma opção simples:

python setup.py install --user

Files will be installed into subdirectories of site.USER_BASE (written as userbase hereafter). This scheme installs pure Python modules and extension modules in the same location (also known as site.USER_SITE). Here are the values for UNIX, including macOS:

Tipo de arquivo	Diretório de instalação
módulos	userbase/lib/pythonX.Y/site-packages
scripts	userbase/bin
dados	userbase
cabeçalhos do C	userbase/include/pythonX.Yabiflags/distname

E aqui estão os valores usados no Windows:

Tipo de arquivo	Diretório de instalação
módulos	userbase\PythonXY\site-packages
scripts	userbase\PythonXY\Scripts
dados	userbase
cabeçalhos do C	userbase\PythonXY\Include{distname}

A vantagem de usar este esquema em comparação com os outros descritos abaixo é que o diretório de pacotes do site do usuário está, em condições normais, sempre incluído em sys.path (veja site para mais informações), o que significa que não há etapa adicional a ser executada após a execução do script setup.py para finalizar a instalação.

O comando build_ext também tem uma opção --user para adicionar userbase/include ao caminho de pesquisa do compilador para arquivos de cabeçalho e userbase/lib para o caminho de pesquisa do compilador para bibliotecas, bem como para o caminho de pesquisa em tempo de execução para bibliotecas C compartilhadas (rpath).

Instalação alternativa: o esquema home

A ideia por trás do “esquema home” é que você construa e mantenha um estoque pessoal de módulos Python. O nome deste esquema é derivado da ideia de um diretório “home” no Unix, uma vez que não é incomum para um usuário Unix fazer seu diretório home ter um layout semelhante a /usr/ ou /usr/local/. Este esquema pode ser usado por qualquer pessoa, independentemente do sistema operacional para o qual está instalando.

Instalando uma nova distribuição de módulo é tão simples quanto

python setup.py install --home=<dir>

onde você pode fornecer qualquer diretório que desejar para a opção --home. No Unix, digitadores preguiçosos podem simplesmente digitar um til (~); o comando install vai expandir isso para o seu diretório home:

python setup.py install --home=~

Para fazer o Python encontrar as distribuições instaladas com este esquema, você deve modificar o caminho de pesquisa do Python ou editar sitecustomize (veja site) para chamar site.additedir() ou editar sys.path.

A opção --home define o diretório base de instalação. Os arquivos são instalados nos seguintes diretórios na base de instalação da seguinte maneira:

Tipo de arquivo	Diretório de instalação
módulos	home/lib/python
scripts	home/bin
dados	home
cabeçalhos do C	home/include/python/distname

(Substitua mentalmente as barras por contrabarras se estiver no Windows.)

Instalação alternativa: Unix (o esquema prefixo)

O “esquema prefixo” é útil quando você deseja usar uma instalação Python para realizar a compilação/instalação (ou seja, para executar o script de configuração), mas instalar módulos no diretório de módulo de terceiros de uma instalação Python diferente (ou algo que parece uma instalação diferente do Python). Se isso parece um pouco incomum, então é – é por isso que os esquemas usuário e home vêm antes. No entanto, existem pelo menos dois casos conhecidos em que o esquema prefixo será útil.

Primeiro, considere que muitas distribuições Linux colocam Python em /usr, ao invés do mais tradicional /usr/local. Isso é totalmente apropriado, já que, nesses casos, o Python é parte do “sistema” em vez de um complemento local. No entanto, se você estiver instalando módulos Python a partir do código-fonte, provavelmente deseja que eles entrem em /usr/local/lib/python2.X em vez de /usr/lib/python2.X. Isso pode ser feito com

/usr/bin/python setup.py install --prefix=/usr/local

Outra possibilidade é um sistema de arquivos de rede onde o nome usado para escrever em um diretório remoto é diferente do nome usado para lê-lo: por exemplo, o interpretador Python acessado como /usr/local/bin/python pode pesquisar por módulos em /usr/local/lib/python2.X, mas esses módulos teriam que ser instalados em, digamos, /mnt/@server/export/lib/python2.X. Isso pode ser feito com

/usr/local/bin/python setup.py install --prefix=/mnt/@server/export

Em ambos os casos, a opção --prefix define a base de instalação, e a opção --exec-prefix define a base de instalação específica da plataforma, que é usada para arquivos específicos da plataforma. (Atualmente, isso significa apenas distribuições de módulos não puros, mas pode ser expandido para bibliotecas C, executáveis binários, etc.) Se --exec-prefix não for fornecido, o padrão é --prefix. Os arquivos são instalados da seguinte forma:

Tipo de arquivo	Diretório de instalação
módulos Python	prefix/lib/pythonX.Y/site-packages
módulos de extensão	exec-prefix/lib/pythonX.Y/site-packages
scripts	prefix/bin
dados	prefix
cabeçalhos do C	prefix/include/pythonX.Yabiflags/distname

Não há nenhum requisito de que --prefix ou --exec-prefix realmente apontem para uma instalação alternativa do Python; se os diretórios listados acima ainda não existirem, eles serão criados no momento da instalação.

A propósito, a verdadeira razão pela qual o esquema prefixo é importante é simplesmente que uma instalação Unix padrão usa o esquema prefixo, mas com --prefix e --exec-prefix fornecidos pelo próprio Python como sys.prefix e sys.exec_prefix. Portanto, você pode pensar que nunca usará o esquema prefixo, mas toda vez que executa python setup.py install sem qualquer outra opção, você o está usando.

Observe que instalar extensões para uma instalação alternativa do Python não tem efeito sobre como essas extensões são construídas: em particular, os arquivos de cabeçalho Python (Python.h e amigos) instalados com o interpretador Python usado para executar o script de configuração vão ser usador na compilação de extensões. É sua responsabilidade garantir que o interpretador usado para executar as extensões instaladas dessa maneira seja compatível com o interpretador usado para criá-las. A melhor maneira de fazer isso é garantir que os dois interpretadores sejam da mesma versão do Python (possivelmente compilações diferentes ou possivelmente cópias da mesma compilação). (Claro, se seu --prefix e seu --exec-prefix nem mesmo apontam para uma instalação alternativa do Python, isso é imaterial.)

Instalação alternativa: Windows (o esquema prefixo)

O Windows não tem o conceito de diretório pessoal do usuário e, como a instalação padrão do Python no Windows é mais simples do que no Unix, a opção --prefix tem sido tradicionalmente usada para instalar pacotes adicionais em locais separados no Windows.

python setup.py install --prefix="\Temp\Python"

para instalar módulos para o diretório \Temp\Python na unidade atual.

A base de instalação é definida pela opção --prefix; a opção --exec-prefix não é suportada no Windows, o que significa que módulos Python puros e módulos de extensão são instalados no mesmo local. Os arquivos são instalados da seguinte forma:

Tipo de arquivo	Diretório de instalação
módulos	prefix\Lib\site-packages
scripts	prefix\Scripts
dados	prefix
cabeçalhos do C	prefix\Include{distname}

Instalação personalizada

Às vezes, os esquemas de instalação alternativos descritos na seção Instalação alternativa simplesmente não fazem o que você quer. Você pode querer ajustar apenas um ou dois diretórios enquanto mantém tudo sob o mesmo diretório base, ou você pode querer redefinir completamente o esquema de instalação. Em ambos os casos, você está criando um esquema de instalação personalizada.

Para criar um esquema de instalação personalizada, você começa com um dos esquemas alternativos e substitui alguns dos diretórios de instalação usados para os vários tipos de arquivos, usando estas opções:

Tipo de arquivo	Opção de substituição
módulos Python	--install-purelib
módulos de extensão	--install-platlib
todos os módulos	--install-lib
scripts	--install-scripts
dados	--install-data
cabeçalhos do C	--install-headers

Essas opções de substituição podem ser relativas, absolutas ou explicitamente definidas em termos de um dos diretórios base da instalação. (Existem dois diretórios básicos de instalação, e eles são normalmente os mesmos – eles só diferem quando você usa o “esquema prefixo” do Unix e fornece opções diferentes de --prefix e --exec-prefix; usar --install-lib irá substituir os valores calculados ou fornecidos para --install-purelib e --install-platlib, e é recomendado para esquemas que não fazem diferença entre Python e módulos de extensão.)

Por exemplo, digamos que você esteja instalando uma distribuição de módulo em seu diretório pessoal no Unix – mas deseja que os scripts estejam em ~/scripts em vez de ~/bin. Como você pode esperar, você pode substituir este diretório com a opção --install-scripts; neste caso, faz mais sentido fornecer um caminho relativo, que será interpretado em relação ao diretório base da instalação (seu diretório home, neste caso):

python setup.py install --home=~ --install-scripts=scripts

Outro exemplo Unix: suponha que sua instalação Python foi construída e instalada com um prefixo de /usr/local/python, então sob uma instalação padrão os scripts irão acabar em /usr/local/python/bin. Se você os quiser em /usr/local/bin em vez disso, você deve fornecer este diretório absoluto para a opção --install-scripts

python setup.py install --install-scripts=/usr/local/bin

(Isso executa uma instalação usando o “esquema prefixo”, onde o prefixo é com o que seu interpretador Python foi instalado – /usr/local/python neste caso.)

Se você mantém o Python no Windows, pode querer que os módulos de terceiros fiquem em um subdiretório de prefix, ao invés do próprio prefix. Isso é quase tão fácil quanto personalizar o diretório de instalação do script – você apenas tem que lembrar que há dois tipos de módulos com os quais se preocupar, Python e módulos de extensão, que podem ser convenientemente controlados por uma opção:

python setup.py install --install-lib=Site

O diretório de instalação especificado é relativo a prefix. Obviamente, você também deve garantir que esse diretório esteja no caminho de pesquisa do módulo do Python, por exemplo, colocando um arquivo .pth em um diretório de site (consulte site). Veja a seção Modificando o caminho de pesquisa do Python para descobrir como modificar o caminho de pesquisa do Python.

Se você deseja definir todo um esquema de instalação, basta fornecer todas as opções do diretório de instalação. A maneira recomendada de fazer isso é fornecer caminhos relativos; por exemplo, se você deseja manter todos os arquivos relacionados ao módulo Python em python em seu diretório home, e deseja um diretório separado para cada plataforma de onde você usa seu diretório inicial, você pode definir o seguinte esquema de instalação:

python setup.py install --home=~ \
                        --install-purelib=python/lib \
                        --install-platlib=python/lib.$PLAT \
                        --install-scripts=python/scripts
                        --install-data=python/data

ou, equivalentemente,

python setup.py install --home=~/python \
                        --install-purelib=lib \
                        --install-platlib='lib.$PLAT' \
                        --install-scripts=scripts
                        --install-data=data

$PLAT não é (necessariamente) uma variável de ambiente – ela será expandida pelo Distutils conforme ele analisa suas opções de linha de comando, assim como faz ao analisar seu(s) arquivo(s) de configuração.

Obviamente, especificar todo o esquema de instalação toda vez que você instalar uma nova distribuição de módulo seria muito tedioso. Assim, você pode colocar essas opções em seu arquivo de configuração Distutils (consulte a seção Arquivos de configuração do Distutils):

[install]
install-base=$HOME
install-purelib=python/lib
install-platlib=python/lib.$PLAT
install-scripts=python/scripts
install-data=python/data

ou, equivalentemente,

[install]
install-base=$HOME/python
install-purelib=lib
install-platlib=lib.$PLAT
install-scripts=scripts
install-data=data

Observe que esses dois não são equivalentes se você fornecer um diretório base de instalação diferente ao executar o script de configuração. Por exemplo,

python setup.py install --install-base=/tmp

instalaria módulos puros em /tmp/python/lib no primeiro caso e em /tmp/lib no segundo caso. (Para o segundo caso, você provavelmente deseja fornecer uma base de instalação de /tmp/python.)

Você provavelmente notou o uso de $HOME e $PLAT na entrada do arquivo de configuração de amostra. Estas são variáveis de configuração Distutils, que apresentam uma forte semelhança com variáveis de ambiente. Na verdade, você pode usar variáveis de ambiente em arquivos de configuração em plataformas que têm essa noção, mas os Distutils definem adicionalmente algumas variáveis extras que podem não estar em seu ambiente, como $PLAT. (E, claro, em sistemas que não têm variáveis de ambiente, como Mac OS 9, as variáveis de configuração fornecidas pelo Distutils são as únicas que você pode usar.) Consulte a seção Arquivos de configuração do Distutils para detalhes.

Nota

Quando um ambiente virtual é ativado, quaisquer opções que alterem o caminho de instalação serão ignoradas de todos os arquivos de configuração distutils para evitar a instalação inadvertida de projetos fora do ambiente virtual.

Modificando o caminho de pesquisa do Python

Quando o interpretador Python executa uma instrução import, ele procura tanto o código Python quanto os módulos de extensão ao longo de um caminho de busca. Um valor padrão para o caminho é configurado no binário Python quando o interpretador é construído. Você pode determinar o caminho importando o módulo sys e imprimindo o valor de sys.path.

$ python
Python 2.2 (#11, Oct  3 2002, 13:31:27)
[GCC 2.96 20000731 (Red Hat Linux 7.3 2.96-112)] on linux2
Type "help", "copyright", "credits" or "license" for more information.
>>> import sys
>>> sys.path
['', '/usr/local/lib/python2.3', '/usr/local/lib/python2.3/plat-linux2',
 '/usr/local/lib/python2.3/lib-tk', '/usr/local/lib/python2.3/lib-dynload',
 '/usr/local/lib/python2.3/site-packages']
>>>

A string nula em sys.path representa o diretório de trabalho atual.

A convenção esperada para pacotes instalados localmente é colocá-los no diretório …/site-packages/, mas você pode querer instalar módulos Python em algum diretório arbitrário. Por exemplo, seu site pode ter uma convenção de manter todos os softwares relacionados ao servidor da web em /www. Módulos add-on Python podem então pertencer a /www/python, e para importá-los, este diretório deve ser adicionado a sys.path. Existem várias maneiras de adicionar o diretório.

A maneira mais conveniente é adicionar um arquivo de configuração de caminho a um diretório que já está no caminho do Python, geralmente para o diretório .../site-packages/. Os arquivos de configuração de caminho têm uma extensão de .pth, e cada linha deve conter um único caminho que será anexado a sys.path. (Como os novos caminhos são anexados a sys.path, os módulos nos diretórios adicionados não substituirão os módulos padrão. Isso significa que você não pode usar este mecanismo para instalar versões fixas de módulos padrão.)

Os caminhos podem ser absolutos ou relativos, nesse caso eles são relativos ao diretório que contém o arquivo .pth. Veja a documentação do módulo site para mais informações.

Uma maneira um pouco menos conveniente é editar o arquivo site.py na biblioteca padrão do Python e modificar sys.path. site.py é importado automaticamente quando o interpretador Python é executado, a menos que a opção -S seja fornecida para suprimir este comportamento. Portanto, você pode simplesmente editar site.py e adicionar duas linhas a ele:

import sys
sys.path.append('/www/python/')

No entanto, se você reinstalar a mesma versão principal do Python (talvez ao atualizar de 2.2 para 2.2.2, por exemplo) site.py será substituído pela versão padrão. Você teria que lembrar que ele foi modificado e salvar uma cópia antes de fazer a instalação.

Existem duas variáveis de ambiente que podem modificar sys.path. PYTHONHOME define um valor alternativo para o prefixo da instalação do Python. Por exemplo, se PYTHONHOME estiver definida como /www/python, o caminho de pesquisa será definido como ['', '/www/python/lib/pythonX.Y/', '/www/python/lib/pythonX.Y/plat-linux2', ...].

A variável PYTHONPATH pode ser definida como uma lista de caminhos que serão adicionados ao início de sys.path. Por exemplo, se PYTHONPATH estiver definida como /www/python:/opt/py, o caminho de pesquisa começará com ['/www/python', '/opt/py']. (Observe que os diretórios devem existir para serem adicionados ao sys.path; o módulo site remove caminhos que não existem.)

Finalmente, sys.path é apenas uma lista Python regular, então qualquer aplicação Python pode modificá-la adicionando ou removendo entradas.

Arquivos de configuração do Distutils

Conforme mencionado acima, você pode usar os arquivos de configuração do Distutils para registrar preferências pessoais ou do site para qualquer opção do Distutils. Ou seja, qualquer opção para qualquer comando pode ser armazenada em um de dois ou três (dependendo da sua plataforma) arquivos de configuração, que serão consultados antes que a linha de comando seja analisada. Isso significa que os arquivos de configuração sobrescreverão os valores padrão e a linha de comando, por sua vez, sobrescreverá os arquivos de configuração. Além disso, se vários arquivos de configuração se aplicarem, os valores dos arquivos “anteriores” serão substituídos pelos arquivos “posteriores”.

Localização e nomes dos arquivos de configuração

The names and locations of the configuration files vary slightly across platforms. On Unix and macOS, the three configuration files (in the order they are processed) are:

Tipo de arquivo	Localização e nome de arquivo	Notas
sistema	prefix/lib/pythonver/distutils/distutils.cfg	(1)
pessoal	$HOME/.pydistutils.cfg	(2)
local	setup.cfg	(3)

E no Windows, os arquivos de configuração são:

Tipo de arquivo	Localização e nome de arquivo	Notas
sistema	prefix\Lib\distutils\distutils.cfg	(4)
pessoal	%HOME%\pydistutils.cfg	(5)
local	setup.cfg	(3)

Em todas as plataformas, o arquivo “pessoal” pode ser desativado temporariamente passando a opção –no-user-cfg.

Notas:

1. Estritamente falando, o arquivo de configuração de todo o sistema reside no diretório onde os Distutils estão instalados; no Python 1.6 e posterior no Unix, isso é mostrado. Para Python 1.5.2, o Distutils normalmente será instalado em prefix/lib/python1.5/site-packages/distutils, então o arquivo de configuração do sistema deve ser colocado lá em Python 1.5.2.

2. No Unix, se a variável de ambiente HOME não estiver definida, o diretório home do usuário será determinado com a função getpwuid() do módulo padrão pwd. Isso é feito pela função os.path.expanduser() usada pelo Distutils.

3. Ou seja, no diretório atual (geralmente a localização do script de configuração).

4. (Consulte também a nota (1).) No Python 1.6 e posterior, o “prefixo de instalação” padrão do Python é C:\Python, então o arquivo de configuração do sistema é normalmente C:\Python\Lib\distutils\distutils.cfg. No Python 1.5.2, o prefixo padrão era C:\Arquivos de programas\Python, e os Distutils não faziam parte da biblioteca padrão – de forma que o arquivo de configuração do sistema seria C:\Arquivos de programas\Python\distutils\distutils.cfg em uma instalação padrão do Python 1.5.2 no Windows.

5. No Windows, Se a variável de ambiente HOME não estiver definida, USERPROFILE, então HOMEDRIVE e, por fim, HOMEPATH serão tentados. Isso é feito pela função os.path.expanduser() usada pelo Distutils.

Sintaxe dos arquivos de configuração

The Distutils configuration files all have the same syntax. The config files are grouped into sections. There is one section for each Distutils command, plus a global section for global options that affect every command. Each section consists of one option per line, specified as option=value.

For example, the following is a complete config file that just forces all commands to run quietly by default:

[global]
verbose=0

If this is installed as the system config file, it will affect all processing of any Python module distribution by any user on the current system. If it is installed as your personal config file (on systems that support them), it will affect only module distributions processed by you. And if it is used as the setup.cfg for a particular module distribution, it affects only that distribution.

You could override the default “build base” directory and make the build* commands always forcibly rebuild all files with the following:

[build]
build-base=blib
force=1

which corresponds to the command-line arguments

python setup.py build --build-base=blib --force

except that including the build command on the command-line means that command will be run. Including a particular command in config files has no such implication; it only means that if the command is run, the options in the config file will apply. (Or if other commands that derive values from it are run, they will use the values in the config file.)

You can find out the complete list of options for any command using the --help option, e.g.:

python setup.py build --help

and you can find out the complete list of global options by using --help without a command:

python setup.py --help

See also the “Reference” section of the “Distributing Python Modules” manual.

Building Extensions: Tips and Tricks

Whenever possible, the Distutils try to use the configuration information made available by the Python interpreter used to run the setup.py script. For example, the same compiler and linker flags used to compile Python will also be used for compiling extensions. Usually this will work well, but in complicated situations this might be inappropriate. This section discusses how to override the usual Distutils behaviour.

Tweaking compiler/linker flags

Compiling a Python extension written in C or C++ will sometimes require specifying custom flags for the compiler and linker in order to use a particular library or produce a special kind of object code. This is especially true if the extension hasn’t been tested on your platform, or if you’re trying to cross-compile Python.

In the most general case, the extension author might have foreseen that compiling the extensions would be complicated, and provided a Setup file for you to edit. This will likely only be done if the module distribution contains many separate extension modules, or if they often require elaborate sets of compiler flags in order to work.

A Setup file, if present, is parsed in order to get a list of extensions to build. Each line in a Setup describes a single module. Lines have the following structure:

module ... [sourcefile ...] [cpparg ...] [library ...]

Let’s examine each of the fields in turn.

• module is the name of the extension module to be built, and should be a valid Python identifier. You can’t just change this in order to rename a module (edits to the source code would also be needed), so this should be left alone.

• sourcefile is anything that’s likely to be a source code file, at least judging by the filename. Filenames ending in .c are assumed to be written in C, filenames ending in .C, .cc, and .c++ are assumed to be C++, and filenames ending in .m or .mm are assumed to be in Objective C.

• cpparg is an argument for the C preprocessor, and is anything starting with -I, -D, -U or -C.

• library is anything ending in .a or beginning with -l or -L.

If a particular platform requires a special library on your platform, you can add it by editing the Setup file and running python setup.py build. For example, if the module defined by the line

foo foomodule.c

must be linked with the math library libm.a on your platform, simply add -lm to the line:

foo foomodule.c -lm

Arbitrary switches intended for the compiler or the linker can be supplied with the -Xcompiler arg and -Xlinker arg options:

foo foomodule.c -Xcompiler -o32 -Xlinker -shared -lm

The next option after -Xcompiler and -Xlinker will be appended to the proper command line, so in the above example the compiler will be passed the -o32 option, and the linker will be passed -shared. If a compiler option requires an argument, you’ll have to supply multiple -Xcompiler options; for example, to pass -x c++ the Setup file would have to contain -Xcompiler -x -Xcompiler c++.

Compiler flags can also be supplied through setting the CFLAGS environment variable. If set, the contents of CFLAGS will be added to the compiler flags specified in the Setup file.

Using non-Microsoft compilers on Windows

Borland/CodeGear C++

This subsection describes the necessary steps to use Distutils with the Borland C++ compiler version 5.5. First you have to know that Borland’s object file format (OMF) is different from the format used by the Python version you can download from the Python or ActiveState Web site. (Python is built with Microsoft Visual C++, which uses COFF as the object file format.) For this reason you have to convert Python’s library python25.lib into the Borland format. You can do this as follows:

coff2omf python25.lib python25_bcpp.lib

The coff2omf program comes with the Borland compiler. The file python25.lib is in the Libs directory of your Python installation. If your extension uses other libraries (zlib, …) you have to convert them too.

The converted files have to reside in the same directories as the normal libraries.

How does Distutils manage to use these libraries with their changed names? If the extension needs a library (eg. foo) Distutils checks first if it finds a library with suffix _bcpp (eg. foo_bcpp.lib) and then uses this library. In the case it doesn’t find such a special library it uses the default name (foo.lib.) 1

To let Distutils compile your extension with Borland C++ you now have to type:

python setup.py build --compiler=bcpp

If you want to use the Borland C++ compiler as the default, you could specify this in your personal or system-wide configuration file for Distutils (see section Arquivos de configuração do Distutils.)

Ver também

C++Builder Compiler

Information about the free C++ compiler from Borland, including links to the download pages.

Creating Python Extensions Using Borland’s Free Compiler

Document describing how to use Borland’s free command-line C++ compiler to build Python.

GNU C / Cygwin / MinGW

This section describes the necessary steps to use Distutils with the GNU C/C++ compilers in their Cygwin and MinGW distributions. 2 For a Python interpreter that was built with Cygwin, everything should work without any of these following steps.

Not all extensions can be built with MinGW or Cygwin, but many can. Extensions most likely to not work are those that use C++ or depend on Microsoft Visual C extensions.

To let Distutils compile your extension with Cygwin you have to type:

python setup.py build --compiler=cygwin

and for Cygwin in no-cygwin mode 3 or for MinGW type:

python setup.py build --compiler=mingw32

If you want to use any of these options/compilers as default, you should consider writing it in your personal or system-wide configuration file for Distutils (see section Arquivos de configuração do Distutils.)

Older Versions of Python and MinGW

The following instructions only apply if you’re using a version of Python inferior to 2.4.1 with a MinGW inferior to 3.0.0 (with binutils-2.13.90-20030111-1).

These compilers require some special libraries. This task is more complex than for Borland’s C++, because there is no program to convert the library. First you have to create a list of symbols which the Python DLL exports. (You can find a good program for this task at https://sourceforge.net/projects/mingw/files/MinGW/Extension/pexports/).

pexports python25.dll >python25.def

The location of an installed python25.dll will depend on the installation options and the version and language of Windows. In a “just for me” installation, it will appear in the root of the installation directory. In a shared installation, it will be located in the system directory.

Then you can create from these information an import library for gcc.

/cygwin/bin/dlltool --dllname python25.dll --def python25.def --output-lib libpython25.a

The resulting library has to be placed in the same directory as python25.lib. (Should be the libs directory under your Python installation directory.)

If your extension uses other libraries (zlib,…) you might have to convert them too. The converted files have to reside in the same directories as the normal libraries do.

Ver também

Building Python modules on MS Windows platform with MinGW

Information about building the required libraries for the MinGW environment.

Notas de rodapé

1

This also means you could replace all existing COFF-libraries with OMF-libraries of the same name.

2

Check https://www.sourceware.org/cygwin/ for more information

3

Then you have no POSIX emulation available, but you also don’t need cygwin1.dll.