La inicialización de la ruta de búsqueda de módulo de "sys.path"
****************************************************************

Una ruta de búsqueda de módulo se inicializa cuando se inicia Python.
Se puede acceder a esta ruta de búsqueda de módulo en "sys.path".

La primera entrada en la ruta de búsqueda de módulo es el directorio
que contiene el script de entrada, si lo hay. De lo contrario, la
primera entrada es el directorio actual, que es el caso cuando se
ejecuta el shell interactivo, un comando "-c" o un módulo "-m".

La variable de entorno "PYTHONPATH" se utiliza a menudo para añadir
directorios a la ruta de búsqueda. Si se encuentra esta variable de
entorno, su contenido se añade a la ruta de búsqueda del módulo.

Nota:

  "PYTHONPATH" afectará a todas las versiones/entornos de Python
  instalados. Tenga cuidado al establecer esto en su perfil de shell o
  en las variables de entorno globales. El módulo "site" ofrece
  técnicas más suavizadas como se menciona a continuación.

Los siguientes elementos que se añaden son los directorios que
contienen los módulos estándar de Python, así como los *extension
module* de los que dependen estos módulos. Los módulos de extensión
son archivos ".pyd" en Windows y archivos ".so" en otras plataformas.
El directorio con los módulos Python independientes de la plataforma
se llama "prefix". El directorio con los módulos de extensión se llama
"exec_prefix".

La variable de entorno "PYTHONHOME" puede utilizarse para establecer
las ubicaciones "prefix" y "exec_prefix". De lo contrario, estos
directorios se encuentran utilizando el ejecutable de Python como
punto de partida y luego buscando varios archivos y directorios "de
referencia". Tenga en cuenta que cualquier enlace simbólico se sigue,
por lo que la ubicación real del ejecutable de Python se utiliza como
punto de partida de la búsqueda. La ubicación del ejecutable de Python
se llama "home".

Una vez determinado "home", el directorio "prefix" se encuentra
buscando primero "python*majorversion**minorversion*.zip"
("python311.zip"). En Windows el archivo zip se busca en "home" y en
Unix se espera que el archivo esté en "lib". Tenga en cuenta que la
ubicación esperada del archivo zip se añade a la ruta de búsqueda del
módulo incluso si el archivo no existe. Si no se encuentra ningún
archivo, Python en Windows continuará la búsqueda de "prefix" buscando
en "Lib\os.py". Python en Unix buscará
"lib/python*majorversion*.*minorversion*/os.py"
("lib/python3.11/os.py"). En Windows "prefix" y "prefix_exec" son los
mismos, sin embargo en otras plataformas se busca
"lib/python*majorversion*.*minorversion*/lib-dynload" ("lib/python3.11
/lib-dynload") y se utiliza como ancla para "prefix_exec". En algunas
plataformas "lib" puede ser "lib64" u otro valor, ver "sys.platlibdir"
y "PYTHONPLATLIBDIR".

Una vez encontrados, "prefix" y "exec_prefix" están disponibles en
"sys.prefix" y "sys.exec_prefix" respectivamente.

Finalmente, el módulo "site" se procesa y los directorios "site-
packages" se añaden a la ruta de búsqueda de módulo. Una forma común
de personalizar la ruta de búsqueda es crear módulos "sitecustomize" o
"usercustomize" como se describe en la documentación del módulo
"site".

Nota:

  Ciertas opciones de la línea de comandos pueden afectar aún más los
  cálculos de ruta. Vea "-E", "-I", "-s" y "-S" para más detalles.


Entornos virtuales
==================

Si Python se ejecuta en un entorno virtual (como se describe en
Entornos virtuales y paquetes) entonces "prefix" y "exec_prefix" son
específicos del entorno virtual.

Si se encuentra un archivo "pyvenv.cfg" junto al ejecutable principal,
o en el directorio un nivel por encima del ejecutable, se aplican las
siguientes variaciones:

* Si "home" es una ruta absoluta y "PYTHONHOME" no está establecido,
  esta ruta se utiliza en lugar de la ruta al ejecutable principal
  cuando se deduce "prefix" y "exec_prefix".


Archivos _pth
=============

Para anular completamente "sys.path" cree un archivo "._pth" con el
mismo nombre que la biblioteca compartida o el ejecutable
("python._pth" o "python311._pth"). La ruta de la biblioteca
compartida se conoce siempre en Windows, pero puede no estar
disponible en otras plataformas. En el archivo "._pth" especifique una
línea por cada ruta a añadir a "sys.path`". El archivo basado en el
nombre de la biblioteca compartida anula el basado en el ejecutable,
lo que permite restringir las rutas para cualquier programa en tiempo
de ejecución si se desea.

Cuando el archivo existe, se ignoran todas las variables de registro y
de entorno, se habilita el modo aislado y no se importa "site" a menos
que una línea del archivo especifique "import site". Las rutas en
blanco y las líneas que comienzan con "#" son ignoradas. Cada ruta
puede ser absoluta o relativa a la ubicación del fichero. No se
permiten declaraciones de importación distintas de "site", y no se
puede especificar código arbitrario.

Tenga en cuenta que los archivos ".pth" (sin guión bajo inicial) serán
procesados normalmente por el módulo "site" cuando se haya
especificado "import site".


Python embebido
===============

Si Python está embebido dentro de otra aplicación
"Py_InitializeFromConfig()" y la estructura "PyConfig" pueden
utilizarse para inicializar Python. Los detalles específicos de la
ruta se describen en Configuración de la ruta de Python.
Alternativamente se puede utilizar la antigua "Py_SetPath()" para
saltarse la inicialización de la ruta de búsqueda de módulo.

Ver también:

  * Encontrar módulos para las notas detalladas de Windows.

  * Uso de Python en plataformas Unix para los detalles de Unix.
