A inicialização do caminho de pesquisa de módulos "sys.path"
************************************************************

Um caminho de pesquisa de módulos é inicializado quando o Python é
iniciado. Este caminho de pesquisa de módulos pode ser acessado em
"sys.path".

A primeira entrada no caminho de pesquisa de módulos é o diretório que
contém o script de entrada, se houver. Caso contrário, a primeira
entrada é o diretório atual, que é o caso ao executar o console
interativo, um comando com "-c" ou um módulo com "-m".

A variável de ambiente "PYTHONPATH" é frequentemente usada para
adicionar diretórios ao caminho de pesquisa. Se esta variável de
ambiente for encontrada, o conteúdo será adicionado ao caminho de
pesquisa de módulos.

Nota:

  "PYTHONPATH" afetará todas as versões/ambientes Python instalados.
  Tenha cuidado ao definir isso em seu perfil do shell ou em variáveis
  de ambiente globais. O módulo "site" oferece técnicas mais
  diferenciadas, conforme mencionado abaixo.

Os próximos itens adicionados são os diretórios contendo módulos
padrão do Python, bem como quaisquer *módulos de extensão* dos quais
esses módulos dependem. Módulos de extensão são arquivos ".pyd" no
Windows e arquivos ".so" em outras plataformas. O diretório com os
módulos Python independentes de plataforma é chamado "prefix". O
diretório com os módulos de extensão é chamado "exec_prefix".

A variável de ambiente "PYTHONHOME" pode ser usada para definir os
locais "prefix" e "exec_prefix". Caso contrário, esses diretórios
serão encontrados usando o executável Python como ponto de partida e,
em seguida, procurando por vários arquivos e diretórios "de
referência". Observe que todos os links simbólicos são seguidos para
que o local real do executável do Python seja usado como ponto de
partida da pesquisa. O local do executável do Python é chamado "home".

Uma vez que "home" é determinado, o diretório "prefix" é encontrado
procurando primeiro por "python*majorversion**minorversion*.zip"
("python311.zip"). No Windows, o arquivo zip é procurado em "home" e
no Unix espera-se que o arquivo esteja em "lib". Observe que o local
esperado do arquivo zip é adicionado ao caminho de pesquisa de
módulos, mesmo que o arquivo não exista. Se nenhum arquivo for
encontrado, o Python no Windows continuará a pesquisa por "prefix"
procurando por "Lib\os.py". Python no Unix procurará por
"lib/python*majorversion*.*minorversion*/os.py"
("lib/python3.11/os.py"). No Windows, "prefix" e "exec_prefix" são
iguais, porém em outras plataformas
"lib/python*majorversion*.*minorversion*/lib-dynload" ("lib/python3.11
/lib-dynload") é pesquisado e usado como âncora para "exec_prefix". Em
algumas plataformas, "lib" pode ser "lib64" ou outro valor, veja
"sys.platlibdir" e "PYTHONPLATLIBDIR".

Uma vez encontrados, "prefix" e "exec_prefix" estão disponíveis em
"sys.prefix" e "sys.exec_prefix", respectivamente.

Finalmente, o módulo "site" é processado e os diretórios "site-
packages" são adicionados ao caminho de pesquisa de módulos. Uma
maneira comum de personalizar o caminho de pesquisa é criar módulos
"sitecustomize" ou "usercustomize" conforme descrito na documentação
do módulo "site".

Nota:

  Certas opções de linha de comando podem afetar ainda mais os
  cálculos de caminho. Veja "-E", "-I", "-s" e "-S" para mais
  detalhes.


Ambientes virtuais
==================

Se Python for executado em um ambiente virtual (conforme descrito em
Ambientes virtuais e pacotes), então "prefix" e "exec_prefix" são
específicos para o ambiente virtual.

Se um arquivo "pyvenv.cfg" for encontrado juntamente com o principal
executável, ou no diretório um nível acima do executável, as seguintes
variações se aplicam:

* Se "home" é um caminho absoluto e "PYTHONHOME" não está definido, o
  caminho é usado ao invés do caminho ao principal executável quando
  deduzindo "prefix" e "exec_prefix".


Arquivos _pth
=============

Para substituir completamente "sys.path", crie um arquivo "._pth" com
o mesmo nome da biblioteca compartilhada ou executável ("python._pth"
ou "python311._pth"). O caminho da biblioteca compartilhada é sempre
conhecido no Windows, mas pode não estar disponível em outras
plataformas. No arquivo "._pth", especifique uma linha para cada
caminho a ser adicionado a "sys.path". O arquivo baseado no nome da
biblioteca compartilhada substitui aquele baseado no executável, o que
permite que os caminhos sejam restritos para qualquer programa que
carregue o tempo de execução, se desejado.

Quando o arquivo existe, todos os registros e variáveis de ambiente
são ignorados, o modo isolado é ativado, e "site" não é importado a
menos que uma linha do arquivo especifique "import site". Caminhos em
branco e linhas começando com "#" são ignorados. Cada caminho pode ser
absoluto ou relativo ao local do arquivo. Instruções de importação
diferente de "site" não são permitidas, e código arbitrário não pode
ser especificado.

Note que arquivos ".pth" (sem o sublinhado no início) serão
processados normalmente pelo módulo "site" quando "import site" tiver
sido especificado.


Python embarcado
================

Se o Python estiver incorporado em outra aplicação,
"Py_InitializeFromConfig()" e a estrutura "PyConfig" podem ser usados
para inicializar o Python. Os detalhes específicos do caminho estão
descritos em Python Path Configuration. Alternativamente, o
"Py_SetPath()" mais antigo pode ser usado para ignorar a inicialização
do caminho de pesquisa de módulos.

Ver também:

  * Encontrando módulos para observações detalhadas do Windows.

  * Utilizando Python em plataformas Unix para detalhes do Unix.
