"os.path" --- Common pathname manipulations
*******************************************

**Source code:** Lib/genericpath.py, Lib/posixpath.py (for POSIX) and
Lib/ntpath.py (for Windows).

======================================================================

Este módulo implementa algunas funciones útiles sobre los nombres de
rutas. Para leer o escribir archivos consulte "open()", y para acceder
a archivos del sistema vea el "os". Los parámetros para las rutas
pueden ser pasados como caracteres, o bytes ,o cualquier objeto
implementado en el protocolo "os.PathLike".

A diferencia de un shell Unix, Python no realiza ninguna expansión de
ruta *automática*. Las funciones como "expanduser()" y "expandvars()"
puede ser invocadas de manera explicita cuando una aplicación desea
realizar una expansión de ruta *shell-like*. (Consulte el módulo
"glob".)

Ver también: El módulo "pathlib" ofrece objetos de ruta de alto nivel.

Nota:

  Todas estas funciones aceptan solo bytes o solo objetos de cadena
  como sus parámetros. El resultado es un objeto del mismo tipo, si se
  retorna una ruta o un nombre de archivo.

Nota:

  Dado que los diferentes sistemas operativos tienen diferentes
  convenciones de nombres de ruta, existen varias versiones de este
  módulo en la librería estándar. El módulo "os.path" siempre es el
  módulo adecuado para el sistema operativo en el cual Python está
  operando, y por lo tanto es utilizable para rutas locales. Sin
  embargo, también puedes importar y utilizar los módulos individuales
  si deseas manipular una ruta que *siempre* está en uno de los
  diferentes formatos. Todos tienen la misma interfaz:

  * "posixpath" para rutas con estilo UNIX

  * "ntpath" para rutas Windows

Distinto en la versión 3.8: "exists()", "lexists()", "isdir()",
"isfile()", "islink()", y "ismount()" ahora retornan "False" en lugar
de lanzar una excepción para rutas que contienen caracteres o bytes
que no se puedan representar a nivel de sistema operativo.

os.path.abspath(path)

   Retorna una versión normalizada y absoluta del nombre de ruta
   *path*. En la mayoría de las plataformas esto es el equivalente a
   invocar la función "normpath()" de la siguiente manera:
   "normpath(join(os.getcwd(), path))".

   Distinto en la versión 3.6: Acepta un *path-like object*.

os.path.basename(path)

   Retorna un nombre base de nombre de ruta *path*. Este es el segundo
   elemento del par retornado al pasar *path* a la función "split()".
   Toma en cuenta que el resultado de esta función es diferente a la
   del programa de Unix **basename**; donde **basename** para
   "'/foo/bar/'" retorna "'bar'", la función "basename()" retorna una
   cadena vacía ("''").

   Distinto en la versión 3.6: Acepta un *path-like object*.

os.path.commonpath(paths)

   Return the longest common sub-path of each pathname in the sequence
   *paths*.  Raise "ValueError" if *paths* contain both absolute and
   relative pathnames, if *paths* are on different drives, or if
   *paths* is empty.  Unlike "commonprefix()", this returns a valid
   path.

   Added in version 3.5.

   Distinto en la versión 3.6: Acepta una secuencia de *path-like
   objects*.

os.path.commonprefix(list)

   Retorna el prefijo de ruta más largo (tomado carácter por carácter)
   que es un prefijo de todas las rutas en *list*. Si *list* está
   vacía, retorna la cadena vacía ("''").

   Nota:

     Esta función puede que retorne rutas invalidas porque trabaja un
     carácter a la vez. Para obtener una ruta valida, consulta
     "commonpath()".

        >>> os.path.commonprefix(['/usr/lib', '/usr/local/lib'])
        '/usr/l'

        >>> os.path.commonpath(['/usr/lib', '/usr/local/lib'])
        '/usr'

   Distinto en la versión 3.6: Acepta un *path-like object*.

os.path.dirname(path)

   Retorna el nombre del directorio de la ruta *path*. Es el primer
   elemento del par retornado al pasar *path* a la función "split()".

   Distinto en la versión 3.6: Acepta un *path-like object*.

os.path.exists(path)

   Retorna "True" si *path* se refiere a una ruta existente o un
   descriptor de archivo abierto. Retorna "False" para enlaces
   simbólicos rotos. En algunas plataformas, esta función puede
   retornar "False" si no se concede permiso para ejecutar "os.stat()"
   en el archivo solicitado, incluso la ruta *path* existe
   físicamente.

   Distinto en la versión 3.3: *path* ahora puede ser un valor entero:
   retorna "True" si es un descriptor de archivo abierto, de otro modo
   retorna "False".

   Distinto en la versión 3.6: Acepta un *path-like object*.

os.path.lexists(path)

   Return "True" if *path* refers to an existing path, including
   broken symbolic links.   Equivalent to "exists()" on platforms
   lacking "os.lstat()".

   Distinto en la versión 3.6: Acepta un *path-like object*.

os.path.expanduser(path)

   En Unix y Windows, retorna el argumento con un componente inicial
   de "~" o "~user" reemplazado por el directorio *home* de *user*.

   En Unix, el "~" inicial es reemplazado por la variable de entorno
   "HOME" si está activada; si no, el directorio principal del usuario
   actual se busca en el directorio de contraseñas a través del módulo
   incorporado "pwd". Un "~user" inicial es buscado directamente en el
   directorio de contraseñas.

   En Windows, se usará "USERPROFILE" si se establece, de lo contrario
   se usará una combinación de "HOMEPATH" y "HOMEDRIVE".  Un "~user"
   inicial se maneja comprobando que el último componente de
   directorio del directorio de inicio del usuario actual coincide con
   "USERNAME", y reemplazándolo si es así.

   Si la expansión falla o si la ruta no comienza con una tilde, la
   ruta se retorna sin cambios.

   Distinto en la versión 3.6: Acepta un *path-like object*.

   Distinto en la versión 3.8: Ya no utiliza "HOME" en Windows.

os.path.expandvars(path)

   Retorna el argumento con variables de entorno expandidas. Las sub-
   cadenas de la forma "$name" or "${name}" se reemplazan por el valor
   de la variable de entorno *name*. Los nombres de variables mal
   formadas y las referencias a variables no existentes se dejan sin
   cambios.

   En Windows, las expansiones "%name%" están soportadas además de
   "$name" y "${name}".

   Distinto en la versión 3.6: Acepta un *path-like object*.

os.path.getatime(path)

   Return the time of last access of *path*.  The return value is a
   floating-point number giving the number of seconds since the epoch
   (see the  "time" module).  Raise "OSError" if the file does not
   exist or is inaccessible.

os.path.getmtime(path)

   Return the time of last modification of *path*.  The return value
   is a floating-point number giving the number of seconds since the
   epoch (see the  "time" module). Raise "OSError" if the file does
   not exist or is inaccessible.

   Distinto en la versión 3.6: Acepta un *path-like object*.

os.path.getctime(path)

   Retorna el *ctime* del sistema que, en algunos sistemas (como Unix)
   es la hora del último cambio de metadatos y, en otros (como
   Windows), es el tiempo de creación de *path*. El valor retornado es
   un número que da el número de segundos desde la época (consulta el
   módulo "time"). Lanza una excepción "OSError" si el archivo no
   existe o es inaccesible.

   Distinto en la versión 3.6: Acepta un *path-like object*.

os.path.getsize(path)

   Retorna el tamaño en bytes de *path*, Lanza una excepción "OSError"
   si el archivo no existe o es inaccesible.

   Distinto en la versión 3.6: Acepta un *path-like object*.

os.path.isabs(path)

   Retorna "True" si *path* es un nombre de ruta de acceso absoluto.
   En Unix, eso significa que comienza con una barra diagonal, en
   Windows que comienza con una barra diagonal (invertida) después de
   cortar una letra de unidad potencial.

   Distinto en la versión 3.6: Acepta un *path-like object*.

os.path.isfile(path)

   Retorna "True" si *path* es un archivo "existing". Esto sigue los
   enlaces simbólicos, por lo que tanto "islink()" como "isfile()"
   pueden ser verdaderos para la misma ruta.

   Distinto en la versión 3.6: Acepta un *path-like object*.

os.path.isdir(path)

   Retorna "True" si *path* es un directorio "existing". Esto sigue
   los enlaces simbólicos, por lo que tanto "islink()" como "isdir()"
   pueden ser verdaderos para la misma ruta.

   Distinto en la versión 3.6: Acepta un *path-like object*.

os.path.isjunction(path)

   Return "True" if *path* refers to an "existing" directory entry
   that is a junction.  Always return "False" if junctions are not
   supported on the current platform.

   Added in version 3.12.

os.path.islink(path)

   Retorna  "True" si *path* hace referencia a una entrada de
   directorio "existing" que es un enlace simbólico. Siempre "False"
   si el entorno de ejecución de Python no admite vínculos
   simbólicos..

   Distinto en la versión 3.6: Acepta un *path-like object*.

os.path.ismount(path)

   Retorna "True" si el nombre de ruta *path* es un *mount point*: un
   punto en un sistema de archivos donde se ha montado un sistema de
   archivos diferente. En POSIX, la función comprueba si el elemento
   primario de *path*, "*path*/..", se encuentra en un dispositivo
   diferente de *path*, o si "*path*/.." y *path* apuntan al mismo
   *i-node* en el mismo dispositivo --- esto debería detectar puntos
   de montaje para todas las variantes Unix y POSIX. No es capaz de
   detectar de forma fiable los montajes de enlace en el mismo sistema
   de archivos. En Windows, una raíz de letra de unidad y un recurso
   compartido UNC siempre son puntos de montaje, y para cualquier otra
   ruta de acceso "GetVolumePathName" se llama para ver si es
   diferente de la ruta de acceso de entrada.

   Distinto en la versión 3.4: Added support for detecting non-root
   mount points on Windows.

   Distinto en la versión 3.6: Acepta un *path-like object*.

os.path.isdevdrive(path)

   Return "True" if pathname *path* is located on a Windows Dev Drive.
   A Dev Drive is optimized for developer scenarios, and offers faster
   performance for reading and writing files. It is recommended for
   use for source code, temporary build directories, package caches,
   and other IO-intensive operations.

   May raise an error for an invalid path, for example, one without a
   recognizable drive, but returns "False" on platforms that do not
   support Dev Drives. See the Windows documentation for information
   on enabling and creating Dev Drives.

   Availability: Windows.

   Added in version 3.12.

os.path.join(path, *paths)

   Join one or more path segments intelligently.  The return value is
   the concatenation of *path* and all members of **paths*, with
   exactly one directory separator following each non-empty part,
   except the last. That is, the result will only end in a separator
   if the last part is either empty or ends in a separator. If a
   segment is an absolute path (which on Windows requires both a drive
   and a root), then all previous segments are ignored and joining
   continues from the absolute path segment.

   On Windows, the drive is not reset when a rooted path segment
   (e.g., "r'\foo'") is encountered. If a segment is on a different
   drive or is an absolute path, all previous segments are ignored and
   the drive is reset. Note that since there is a current directory
   for each drive, "os.path.join("c:", "foo")" represents a path
   relative to the current directory on drive "C:" ("c:foo"), not
   "c:\foo".

   Distinto en la versión 3.6: Acepta un objeto *path-like object*
   para *path* y *paths*.

os.path.normcase(path)

   Normaliza las mayúsculas y minúsculas de un nombre de ruta. En
   Windows convierte todos los caracteres en el nombre de ruta a
   minúsculas y también convierte las barras inclinadas hacia atrás en
   barras inclinadas hacia atrás. En otros sistemas operativos,
   retorna la ruta sin cambios.

   Distinto en la versión 3.6: Acepta un *path-like object*.

os.path.normpath(path)

   Normaliza un nombre de ruta colapsando separadores redundantes y
   referencias de nivel superior para que "A//B", "A/B/", "A/./B" y
   "A/foo/../B" se transformen en "A/B". Esta modificación de cadena
   puede que modifique el significado de la ruta que contenga enlaces
   simbólicos. En Windows, convierte las barras inclinadas hacia
   adelante en barras hacia atrás. Para normalizar mayúsculas y
   minúsculas, utiliza "normcase()".

   Nota:

     En sistemas POSIX, de acuerdo con IEEE Std 1003.1 Edición 2013;
     4.13 Resolución de Nombres de Rutas, si el nombre de ruta
     comienza con exactamente dos barras diagonales, el primer
     componente que sigue a los caracteres principales puede
     interpretarse de una manera definida por la implementación,
     aunque más de dos caracteres principales se tratarán como un solo
     carácter.

   Distinto en la versión 3.6: Acepta un *path-like object*.

os.path.realpath(path, *, strict=False)

   Retorna la ruta canónica del nombre de archivo especificado,
   eliminando cualquier enlace simbólico encontrado en la ruta (si es
   que tienen soporte por el sistema operativo).

   By default, the path is evaluated up to the first component that
   does not exist, is a symlink loop, or whose evaluation raises
   "OSError". All such components are appended unchanged to the
   existing part of the path.

   Some errors that are handled this way include "access denied", "not
   a directory", or "bad argument to internal function". Thus, the
   resulting path may be missing or inaccessible, may still contain
   links or loops, and may traverse non-directories.

   This behavior can be modified by keyword arguments:

   If *strict* is "True", the first error encountered when evaluating
   the path is re-raised. In particular, "FileNotFoundError" is raised
   if *path* does not exist, or another "OSError" if it is otherwise
   inaccessible.

   If *strict* is "os.path.ALLOW_MISSING", errors other than
   "FileNotFoundError" are re-raised (as with "strict=True"). Thus,
   the returned path will not contain any symbolic links, but the
   named file and some of its parent directories may be missing.

   Nota:

     Esta función emula el procedimiento del sistema operativo para
     hacer que una ruta sea canónica, que difiere ligeramente entre
     Windows y UNIX con respecto a cómo interactúan los enlaces y los
     componentes de la ruta posterior.Las API del sistema operativo
     hacen que las rutas sean canónicas según sea necesario, por lo
     que normalmente no es necesario llamar a esta función.

   Distinto en la versión 3.6: Acepta un *path-like object*.

   Distinto en la versión 3.8: Los enlaces y uniones simbólicos ahora
   se resuelven en Windows.

   Distinto en la versión 3.10: Se agregó el parámetro *strict*.

   Distinto en la versión 3.12.11: The "ALLOW_MISSING" value for the
   *strict* parameter was added.

os.path.ALLOW_MISSING

   Special value used for the *strict* argument in "realpath()".

   Added in version 3.12.11.

os.path.relpath(path, start=os.curdir)

   Retorna un nombre de ruta relativo a *path* desde el directorio
   actual o de un directorio *start* opcional. Este es un cálculo de
   ruta: No se accede al sistema de archivos para confirmar la
   existencia o la naturaleza de *path* o *start*. En Windows, se
   lanza "ValueError"  cuando *path* y *start* están en discos
   diferentes.

   *start* defaults to "os.curdir".

   Distinto en la versión 3.6: Acepta un *path-like object*.

os.path.samefile(path1, path2)

   Retorna "True" si ambos argumentos de nombre de ruta refieren al
   mismo archivo o directorio. Esto se determina por el número de
   dispositivo y el número de *i-node* y lanza una excepción si una
   llamada de "os.stat()" en alguno de los nombres de ruta falla.

   Distinto en la versión 3.2: Añadido soporte para Windows.

   Distinto en la versión 3.4: Windows ahora utiliza la misma
   implementación que en el resto de las plataformas.

   Distinto en la versión 3.6: Acepta un *path-like object*.

os.path.sameopenfile(fp1, fp2)

   Retorna "True" si los descriptores de archivo *fp1* y *fp2* se
   refieren al mismo archivo.

   Distinto en la versión 3.2: Añadido soporte para Windows.

   Distinto en la versión 3.6: Acepta un *path-like object*.

os.path.samestat(stat1, stat2)

   Retorna "True" si las tuplas de *stat* (*stat1* y *stat2*) refieren
   al mismo archivo. Estas estructuras pueden haber sido retornadas
   por "os.fstat()", "os.lstat()", o "os.stat()". Esta función
   implementa la comparación subyacente utilizada por: "samefile()" y
   "sameopenfile()".

   Distinto en la versión 3.4: Añadido soporte para Windows.

   Distinto en la versión 3.6: Acepta un *path-like object*.

os.path.split(path)

   Divide el nombre de la ruta *path * en un par, ``(head, tail)``
   donde *tail* es el último componente del nombre de la ruta y *head*
   es todo lo que conduce a eso. La parte *head* nunca contendrá una
   barra; si *head* termina en una barra, *tail* estará vacía. Si no
   hay barra inclinada en *path*, *head* estará vacío. Si *path* está
   vacía, tanto *head* como *tail* estarán vacíos. Las barras
   diagonales finales se eliminan de *head* a menos que sea la raíz
   (solo una o más barras). En todos los casos, "join(head, tail)"
   retorna una ruta a la misma ubicación que *path* (pero las cadenas
   pueden diferir). Consulta las funciones "dirname()" y "basename()".

   Distinto en la versión 3.6: Acepta un *path-like object*.

os.path.splitdrive(path)

   Divide el nombre de ruta *path* en un par "(drive, tail)" donde
   *drive* es un punto de montaje o una cadena vacía. En sistemas que
   no utilizan especificaciones de unidad, *drive* siempre será una
   cadena vacía. En todos los casos, "drive + tail" será lo mismo que
   *path*.

   En Windows, divide un nombre de ruta en unidad / punto compartido
   UNC y ruta relativa.

   Si la ruta contiene una letra de unidad, la unidad contendrá todo
   hasta los dos puntos inclusive:

      >>> splitdrive("c:/dir")
      ("c:", "/dir")

   If the path contains a UNC path, drive will contain the host name
   and share:

      >>> splitdrive("//host/computer/dir")
      ("//host/computer", "/dir")

   Distinto en la versión 3.6: Acepta un *path-like object*.

os.path.splitroot(path)

   Split the pathname *path* into a 3-item tuple "(drive, root, tail)"
   where *drive* is a device name or mount point, *root* is a string
   of separators after the drive, and *tail* is everything after the
   root. Any of these items may be the empty string. In all cases,
   "drive + root + tail" will be the same as *path*.

   On POSIX systems, *drive* is always empty. The *root* may be empty
   (if *path* is relative), a single forward slash (if *path* is
   absolute), or two forward slashes (implementation-defined per IEEE
   Std 1003.1-2017; 4.13 Pathname Resolution.) For example:

      >>> splitroot('/home/sam')
      ('', '/', 'home/sam')
      >>> splitroot('//home/sam')
      ('', '//', 'home/sam')
      >>> splitroot('///home/sam')
      ('', '/', '//home/sam')

   On Windows, *drive* may be empty, a drive-letter name, a UNC share,
   or a device name. The *root* may be empty, a forward slash, or a
   backward slash. For example:

      >>> splitroot('C:/Users/Sam')
      ('C:', '/', 'Users/Sam')
      >>> splitroot('//Server/Share/Users/Sam')
      ('//Server/Share', '/', 'Users/Sam')

   Added in version 3.12.

os.path.splitext(path)

   Divide el nombre de la ruta *path* en un par "(root, ext)" de tal
   forma que "root + ext == path", y *ext* queda vacío o inicia con un
   punto y contiene a lo mucho un punto.

   Si la ruta no contiene ninguna extensión, *ext* será  "’’":

      >>> splitext('bar')
      ('bar', '')

   Si la ruta contiene una extensión, *ext* se establecerá como esta
   extensión, incluido el punto por delante. Tenga en cuenta que los
   puntos anteriores se ignorarán:

      >>> splitext('foo.bar.exe')
      ('foo.bar', '.exe')
      >>> splitext('/foo/bar.exe')
      ('/foo/bar', '.exe')

   Los puntos que están por delante del último componente de la ruta
   son considerados parte de la raíz:

      >>> splitext('.cshrc')
      ('.cshrc', '')
      >>> splitext('/foo/....jpg')
      ('/foo/....jpg', '')

   Distinto en la versión 3.6: Acepta un *path-like object*.

os.path.supports_unicode_filenames

   "True" si se pueden utilizar cadenas Unicode arbitrarias como
   nombres de archivo (dentro de las limitaciones impuestas por el
   sistema de archivos).
