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

**Código-fonte:** Lib/glob.py

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

O módulo "glob" encontra todos os nomes de caminho que correspondem a
um padrão especificado de acordo com as regras usadas pelo shell Unix,
embora os resultados sejam retornados em ordem arbitrária. Nenhuma
expansão de til é feita, mas "*", "?" e os intervalos de caracteres
expressos com "[]" serão correspondidos corretamente. Isso é feito
usando as funções "os.scandir()" e "fnmatch.fnmatch()" em conjunto, e
não invocando realmente um subshell.

Observe que arquivos iniciados com um ponto (".") só podem ser
correspondidos com padrões que também iniciam com um ponto, ao
contrário de "fnmatch.fnmatch()" ou "pathlib.Path.glob()". (Para
expansão de til e variável de shell, use "os.path.expanduser()" e
"os.path.expandvars()".)

Para uma correspondência literal, coloque os metacaracteres entre
colchetes. Por exemplo, "'[?]'" corresponde ao caractere "'?'".

The "glob" module defines the following functions:

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

   Retorna uma lista possivelmente vazia de nomes de caminho que
   correspondem a *pathname*, que deve ser uma string contendo uma
   especificação de caminho. *pathname* pode ser absoluto (como
   "/usr/src/Python-1.5/Makefile") ou relativo (como
   "../../Tools/*/*.gif") e pode conter curingas no estilo shell.
   Links simbólicos quebrados são incluídos nos resultados (como no
   shell). Se os resultados são classificados ou não depende do
   sistema de arquivos. Se um arquivo que satisfaz as condições for
   removido ou adicionado durante a chamada desta função, não é
   especificado se um nome de caminho para esse arquivo será incluído.

   Se *root_dir* não for "None", deve ser um *objeto caminho ou
   similar* especificando o diretório raiz para pesquisa. Tem o mesmo
   efeito em "glob()" que alterar o diretório atual antes de chamá-lo.
   Se *pathname* for relativo, o resultado conterá caminhos relativos
   a *root_dir*.

   Esta função pode suportar paths relative to directory descriptors
   com o parâmetro *dir_fd*.

   Se *recursive* for verdadeiro, o padrão ""**"" corresponderá a
   qualquer arquivo e zero ou mais diretórios, subdiretórios e links
   simbólicos para diretórios. Se o padrão for seguido por um "os.sep"
   ou "os.altsep", então os arquivos não irão corresponder.

   Se *include_hidden* for verdadeiro, o padrão ""**"" corresponderá
   aos diretórios ocultos.

   Levanta um evento de auditoria "glob.glob" com argumentos
   "pathname", "recursive".

   Levanta um evento de auditoria "glob.glob/2" com argumentos
   "pathname", "recursive", "root_dir", "dir_fd".

   Nota:

     Usar o padrão ""**"" em grandes árvores de diretório pode
     consumir uma quantidade excessiva de tempo.

   Nota:

     Esta função pode retornar nomes de caminhos duplicados se
     *pathname* contiver vários padrões ""**"" e *recursive* for
     verdadeiro.

   Alterado na versão 3.5: Suporte a globs recursivos usando ""**"".

   Alterado na versão 3.10: Adicionados os parâmetros *root_dir* e
   *dir_fd*.

   Alterado na versão 3.11: Adicionado o parâmetro *include_hidden*.

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

   Retorna um *iterador* que produz os mesmos valores que "glob()" sem
   realmente armazená-los todos simultaneamente.

   Levanta um evento de auditoria "glob.glob" com argumentos
   "pathname", "recursive".

   Levanta um evento de auditoria "glob.glob/2" com argumentos
   "pathname", "recursive", "root_dir", "dir_fd".

   Nota:

     Esta função pode retornar nomes de caminhos duplicados se
     *pathname* contiver vários padrões ""**"" e *recursive* for
     verdadeiro.

   Alterado na versão 3.5: Suporte a globs recursivos usando ""**"".

   Alterado na versão 3.10: Adicionados os parâmetros *root_dir* e
   *dir_fd*.

   Alterado na versão 3.11: Adicionado o parâmetro *include_hidden*.

glob.escape(pathname)

   Escapa todos os caracteres especiais ("'?'", "'*'" e "'['"). Isso é
   útil se você deseja corresponder a uma string literal arbitrária
   que pode conter caracteres especiais. Os caracteres especiais nos
   pontos de compartilhamento de unidade/UNC não têm escape, por
   exemplo, no Windows  "escape('//?/c:/Quo vadis?.txt')" retorna
   "'//?/c:/Quo vadis[?].txt'".

   Adicionado na versão 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.

   Por exemplo:

   >>> 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.

   Ver também:

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

   Adicionado na versão 3.13.


Exemplos
========

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/']

Se o diretório contém arquivos começando com "." eles não serão
correspondidos por padrão. Por exemplo, considere um diretório
contendo "card.gif" e ".card.gif"

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

Ver também:

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

Ver também:

  O módulo "pathlib" oferece objetos de caminho de alto nível.
