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