Instalando módulos Python (versão legada)¶
- Autor:
Greg Ward
Nota
Todo o pacote distutils foi descontinuado e será removido no Python 3.12. Esta documentação é mantida apenas como referência e será removida com o pacote. Veja a entrada no O que há de novo para mais informações.
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 ():
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.
Se você não escolher um diretório de instalação – ou seja, se você apenas executar setup.py install– então o comando install instala no local padrão para módulos Python de terceiros . Esse local varia de acordo com a plataforma e como você construiu/instalou o próprio Python. No Unix (e no macOS, que também é baseado no Unix), também depende se a distribuição de módulo que está sendo instalada é Python puro ou contém extensões (“não puras”):
Plataforma |
Local de instalação padrão |
Valor padrão |
Notas |
|---|---|---|---|
Unix (puro) |
|
|
(1) |
Unix (não puro) |
|
|
(1) |
Windows |
|
|
(2) |
Notas:
A maioria das distribuições Linux inclui Python como uma parte padrão do sistema, então
prefixeexec-prefixsão geralmente/usrno Linux. Se você construir Python no Linux (ou qualquer sistema semelhante ao Unix), o padrão deprefixeexec-prefixé/usr/local.O diretório de instalação padrão no Windows era
C:\Program Files\Pythonno Python 1.6a1, 1.5.2 e anterior.
prefix e exec-prefix representam os diretórios nos quais o Python é instalado e onde ele encontra suas bibliotecas em tempo de execução. Eles são sempre os mesmos no Windows, e muitas vezes os mesmos no Unix e macOS. Você pode descobrir o que sua instalação Python usa para prefix e exec-prefix executando Python no modo interativo e digitando alguns comandos simples. No Unix, apenas digite python no prompt do shell. No Windows, escolha . Depois que o interpretador é iniciado, você digita o código Python no prompt. Por exemplo, em meu sistema Linux, eu digito as três instruções Python mostradas abaixo e obtenho a saída conforme mostrado, para descobrir meu prefix e 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
Os arquivos serão instalados em subdiretórios de site.USER_BASE (escrito como userbase daqui em diante). Este esquema instala módulos Python puros e módulos de extensão no mesmo local (também conhecido como site.USER_SITE). Aqui estão os valores para UNIX, incluindo macOS:
Tipo de arquivo |
Diretório de instalação |
|---|---|
módulos |
|
scripts |
|
dados |
|
cabeçalhos do C |
|
E aqui estão os valores usados no Windows:
Tipo de arquivo |
Diretório de instalação |
|---|---|
módulos |
|
scripts |
|
dados |
|
cabeçalhos do C |
|
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=~
To make Python find the distributions installed with this scheme, you may have
to modify Python’s search path or edit
sitecustomize (see site) to call site.addsitedir() or edit
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 |
|
scripts |
|
dados |
|
cabeçalhos do C |
|
(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 |
|
módulos de extensão |
|
scripts |
|
dados |
|
cabeçalhos do C |
|
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 |
|
scripts |
|
dados |
|
cabeçalhos do C |
|
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 |
|
módulos de extensão |
|
todos os módulos |
|
scripts |
|
dados |
|
cabeçalhos do C |
|
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/')
However, if you reinstall the same minor version of Python (perhaps when
upgrading from 2.2 to 2.2.2, for example) site.py will be overwritten by
the stock version. You’d have to remember that it was modified and save a copy
before doing the installation.
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 |
|
(1) |
pessoal |
|
(2) |
local |
|
(3) |
E no Windows, os arquivos de configuração são:
Tipo de arquivo |
Localização e nome de arquivo |
Notas |
|---|---|---|
sistema |
|
(4) |
pessoal |
|
(5) |
local |
|
(3) |
On all platforms, the “personal” file can be temporarily disabled by
passing the --no-user-cfg option.
Notas:
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.On Unix, if the
HOMEenvironment variable is not defined, the user’s home directory will be determined with thegetpwuid()function from the standardpwdmodule. This is done by theos.path.expanduser()function used by Distutils.Ou seja, no diretório atual (geralmente a localização do script de configuração).
(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 é normalmenteC:\Python\Lib\distutils\distutils.cfg. No Python 1.5.2, o prefixo padrão eraC:\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 seriaC:\Arquivos de programas\Python\distutils\distutils.cfgem uma instalação padrão do Python 1.5.2 no Windows.No Windows, Se a variável de ambiente
HOMEnão estiver definida,USERPROFILE, entãoHOMEDRIVEe, por fim,HOMEPATHserão tentados. Isso é feito pela funçãoos.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
.care assumed to be written in C, filenames ending in.C,.cc, and.c++are assumed to be C++, and filenames ending in.mor.mmare assumed to be in Objective C.cpparg is an argument for the C preprocessor, and is anything starting with
-I,-D,-Uor-C.library is anything ending in
.aor beginning with-lor-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é