"glob" --- Unix style pathname pattern expansion
************************************************

**Código fuente:** Lib/glob.py

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

El módulo "glob" encuentra todos los nombres de rutas que se asemejan
a un patrón especificado de acuerdo a las reglas que se siguen en una
terminal Unix, aunque los resultados se retornan con un orden
arbitrario.  No se realiza expansión de virgulilla (*tilde ("~")
expansion* en inglés) pero "*", "?" y caracteres de rango expresados
mediante "[]" serán emparejados correctamente.  Esto se realiza usando
las funciones "os.scandir()" y "fnmatch.fnmatch()" de forma concertada
sin invocar, realmente, a una *subshell*.

Nótese que, los archivos que comienzan con un punto (".") solo se
puede combinar con patrones que también comiencen con un punto, a
diferencia de "fnmatch.fnmatch()", o "pathlib.Path.glob()". (Para la
expansión de virgulilla o variable de terminal, use
"os.path.expanduser()"  y "os.path.expandvars()".)

Para una coincidencia literal, envuelve los meta-caracteres en
corchetes. Por ejemplo, "'[?]'" empareja el caracter "'?'".

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

glob.glob(pathname, *, root_dir=None, dir_fd=None, recursive=False, include_hidden=False)

   Return a possibly empty list of path names that match *pathname*,
   which must be a string containing a path specification. *pathname*
   can be either absolute (like "/usr/src/Python-1.5/Makefile") or
   relative (like "../../Tools/*/*.gif"), and can contain shell-style
   wildcards. Broken symlinks are included in the results (as in the
   shell). Whether or not the results are sorted depends on the file
   system.  If a file that satisfies conditions is removed or added
   during the call of this function, whether a path name for that file
   will be included is unspecified.

   Si *root_dir* no es "None", debería ser un *path-like object* que
   especifique el directorio raíz para la búsqueda. Tiene el mismo
   efecto en "glob()" que cambiar el directorio actual antes de
   llamarlo. Si *pathname* es relativo, el resultado contendrá rutas
   relativas a *root_dir*.

   Esta función puede admitir rutas relativas a descriptores de
   directorio con el parámetro *dir_fd*.

   Si *recursive* es verdadero, el patrón ""**"" coincidirá con
   cualquier fichero y cero o más directorios, subdirectorios y
   enlaces simbólicos a directorios.  Si el patrón va seguido de un
   "os.sep" o "os.altsep" los ficheros no coincidirán.

   Si *include_hidden* es verdadero, el patrón ""**"" coincidirá con
   los directorios ocultos.

   Raises an auditing event "glob.glob" with arguments "pathname",
   "recursive".

   Raises an auditing event "glob.glob/2" with arguments "pathname",
   "recursive", "root_dir", "dir_fd".

   Nota:

     El uso del patrón ""**"" en árboles de directorios grandes podría
     consumir una cantidad de tiempo excesiva.

   Nota:

     This function may return duplicate path names if *pathname*
     contains multiple ""**"" patterns and *recursive* is true.

   Distinto en la versión 3.5: Soporte para globs recursivos usando
   ""**"".

   Distinto en la versión 3.10: Se agregaron los parámetros *root_dir*
   y *dir_fd*.

   Distinto en la versión 3.11: Agregado el parámetro
   *include_hidden*.

glob.iglob(pathname, *, root_dir=None, dir_fd=None, recursive=False, include_hidden=False)

   Retorna un *iterador* el cual produce los mismos valores que
   "glob()" sin necesidad de almacenarlos todos de forma simultánea.

   Raises an auditing event "glob.glob" with arguments "pathname",
   "recursive".

   Raises an auditing event "glob.glob/2" with arguments "pathname",
   "recursive", "root_dir", "dir_fd".

   Nota:

     This function may return duplicate path names if *pathname*
     contains multiple ""**"" patterns and *recursive* is true.

   Distinto en la versión 3.5: Soporte para globs recursivos usando
   ""**"".

   Distinto en la versión 3.10: Se agregaron los parámetros *root_dir*
   y *dir_fd*.

   Distinto en la versión 3.11: Agregado el parámetro
   *include_hidden*.

glob.escape(pathname)

   Escapa todos los caracteres especiales ("'?'", "'*'" y "'['"). Esto
   es útil si deseas coincidir una cadena de caracteres literal
   arbitraria que podría contener caracteres especiales.  Los
   caracteres especiales en unidades compartidas/UNC no se eluden,
   e.g. en Windows "escape('//?/c:/Quo vadis?.txt')" retorna
   "'//?/c:/Quo vadis[?].txt'".

   Added in version 3.4.

Por ejemplo, considera un directorio que contenga los siguientes
ficheros: "1.gif", "2.txt", "card.gif" y un subdirectorio "sub" el
cual contenga solo el fichero "3.txt".  "glob()" producirá los
siguientes resultados.  Nótese como se preservará cualquier componente
inicial de la ruta.

   >>> import glob
   >>> glob.glob('./[0-9].*')
   ['./1.gif', './2.txt']
   >>> glob.glob('*.gif')
   ['1.gif', 'card.gif']
   >>> glob.glob('?.gif')
   ['1.gif']
   >>> glob.glob('**/*.txt', recursive=True)
   ['2.txt', 'sub/3.txt']
   >>> glob.glob('./**/', recursive=True)
   ['./', './sub/']

Si un directorio contiene ficheros que comienzan con "." no coincidirá
por defecto. Por ejemplo, considera un directorio que contiene
"card.gif" y ".card.gif":

   >>> import glob
   >>> glob.glob('*.gif')
   ['card.gif']
   >>> glob.glob('.c*')
   ['.card.gif']

Ver también:

  Módulo "fnmatch"
     Expansión de nombre de fichero (no de ruta) al estilo de la
     terminal
