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

**Code source :** Lib/glob.py

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

The "glob" module finds pathnames using pattern matching rules similar
to the Unix shell. No tilde expansion is done, but "*", "?", and
character ranges expressed with "[]" will be correctly matched.  This
is done by using the "os.scandir()" and "fnmatch.fnmatch()" functions
in concert, and not by actually invoking a subshell.

Note:

  The pathnames are returned in no particular order.  If you need a
  specific order, sort the results.

By default, files beginning with a dot (".") can only be matched by
patterns that also start with a dot, unlike "fnmatch.fnmatch()" or
"pathlib.Path.glob()". For tilde and shell variable expansion, use
"os.path.expanduser()" and "os.path.expandvars()".

Pour une correspondance littérale, il faut entourer le métacaractère
par des crochets. Par exemple, "'[?]'" reconnaît le caractère "'?'".

The "glob" module defines the following functions:

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.

   If *root_dir* is not "None", it should be a *path-like object*
   specifying the root directory for searching.  It has the same
   effect on "glob()" as changing the current directory before calling
   it.  If *pathname* is relative, the result will contain paths
   relative to *root_dir*.

   Cette fonction prend en charge les chemins relatifs aux
   descripteurs de dossier avec le paramètre *dir_fd*.

   Si *recursive* est vrai, le motif ""**"" reconnaît tous les
   fichiers, aucun ou plusieurs répertoires, sous-répertoires et liens
   symboliques aux répertoires. Si le motif est suivi par "os.sep" ou
   "os.altsep" alors les fichiers ne sont pas inclus dans le résultat.

   If *include_hidden* is true, wildcards can match path segments that
   begin with a dot (".").

   Lève un évènement d'audit "glob.glob" avec les arguments
   "pathname", "recursive".

   Lève un évènement d'audit "glob.glob/2" avec les arguments
   "pathname", "recursive", "root_dir", "dir_fd".

   Note:

     Utiliser le motif ""**"" dans de grandes arborescences de dossier
     peut consommer une quantité de temps démesurée.

   Note:

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

   Note:

     Any "OSError" exceptions raised from scanning the filesystem are
     suppressed. This includes "PermissionError" when accessing
     directories without read permission.

   Modifié dans la version 3.5: Prise en charge des chemins récursifs
   utilisant le motif  ""**"".

   Modifié dans la version 3.10: Paramètres *root_dir* et *dir_fd*
   ajoutés.

   Modifié dans la version 3.11: Added the *include_hidden* parameter.

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

   Renvoie un *itérateur* qui produit les mêmes valeurs que "glob()",
   sans toutes les charger en mémoire simultanément.

   Lève un évènement d'audit "glob.glob" avec les arguments
   "pathname", "recursive".

   Lève un évènement d'audit "glob.glob/2" avec les arguments
   "pathname", "recursive", "root_dir", "dir_fd".

   Note:

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

   Note:

     Any "OSError" exceptions raised from scanning the filesystem are
     suppressed. This includes "PermissionError" when accessing
     directories without read permission.

   Modifié dans la version 3.5: Prise en charge des chemins récursifs
   utilisant le motif  ""**"".

   Modifié dans la version 3.10: Paramètres *root_dir* et *dir_fd*
   ajoutés.

   Modifié dans la version 3.11: Added the *include_hidden* parameter.

glob.escape(pathname)

   Escape all special characters ("'?'", "'*'" and "'['"). This is
   useful if you want to match an arbitrary literal string that may
   have special characters in it.  Special characters in drive/UNC
   sharepoints are not escaped, for example on Windows
   "escape('//?/c:/Quo vadis?.txt')" returns "'//?/c:/Quo
   vadis[?].txt'".

   Ajouté dans la version 3.4.

glob.translate(pathname, *, recursive=False, include_hidden=False, seps=None)

   Convert the given path specification to a regular expression for
   use with "re.prefixmatch()". The path specification can contain
   shell-style wildcards.

   Par exemple :

   >>> import glob, re
   >>>
   >>> regex = glob.translate('**/*.txt', recursive=True, include_hidden=True)
   >>> regex
   '(?s:(?:.+/)?[^/]*\\.txt)\\z'
   >>> reobj = re.compile(regex)
   >>> reobj.prefixmatch('foo/bar/baz.txt')
   <re.Match object; span=(0, 15), match='foo/bar/baz.txt'>

   Path separators and segments are meaningful to this function,
   unlike "fnmatch.translate()". By default wildcards do not match
   path separators, and "*" pattern segments match precisely one path
   segment.

   If *recursive* is true, the pattern segment ""**"" will match any
   number of path segments.

   If *include_hidden* is true, wildcards can match path segments that
   start with a dot (".").

   A sequence of path separators may be supplied to the *seps*
   argument. If not given, "os.sep" and "altsep" (if available) are
   used.

   Voir aussi:

     "pathlib.PurePath.full_match()" and "pathlib.Path.glob()"
     methods, which call this function to implement pattern matching
     and globbing.

   Ajouté dans la version 3.13.


Exemples
========

Consider a directory containing the following files: "1.gif", "2.txt",
"card.gif" and a subdirectory "sub" which contains only the file
"3.txt".  "glob()" will produce the following results.  Notice how any
leading components of the path are preserved.

   >>> 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 le répertoire contient des fichiers commençant par ".", ils ne sont
pas reconnus par défaut. Par exemple, considérons un répertoire
contenant "card.gif" et ".card.gif" :

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

Voir aussi:

  The "fnmatch" module offers shell-style filename (not path)
  expansion.

Voir aussi:

  Le module "pathlib" offre une représentation objet de haut niveau
  des chemins.
