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

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

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

The "glob" module finds all the pathnames matching a specified pattern
according to the rules used by the Unix shell, although results are
returned in arbitrary order.  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 that 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.

   Si *root_dir* n'est pas "None", cela doit être un *objet simili-
   chemin* spécifiant le dossier racine de la recherche.  Cela a le
   même effet sur "glob()" que de changer le dossier courant avant
   l'appel de la fonction.  Si *pathname* est relatif, les chemins du
   résultat seront relatifs au *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, ""**"" pattern will match hidden
   directories.

   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.

   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.

   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)

   Échappe tous les caractères spéciaux ("'?'", "'*'" et "'['"). Cela
   est utile pour reconnaître une chaîne de caractère littérale
   arbitraire qui contiendrait ce type de caractères. Les caractères
   spéciaux dans les disques et répertoires partagés (chemins UNC) ne
   sont pas échappés, e.g. sous Windows "escape('//?/c:/Quo
   vadis?.txt')" renvoie "'//?/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.match()". 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.match('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.
