re — expressões regulares simples

Este módulo implementa operações com expressões regulares. A sintaxe de expressões regulares suportada é um subconjunto do módulo re do CPython (e é efetivamente um subconjunto das expressões regulares estendidas POSIX).

Os operadores e sequências especiais suportados são:

.

Corresponde a qualquer carácter.

[...]

Corresponde a um conjunto de carácteres. São suportados carácteres individuais e intervalos, incluindo conjuntos negados (p. ex. [^a-c]).

^

Corresponde ao início da cadeia de carácteres.

$

Corresponde ao fim da cadeia de carácteres.

?

Corresponde a zero ou uma ocorrência do sub-padrão anterior.

*

Corresponde a zero ou mais ocorrências do sub-padrão anterior.

+

Corresponde a uma ou mais ocorrências do sub-padrão anterior.

??

Versão não-gulosa de ?, correspondendo a zero ou uma ocorrência, com preferência por zero.

*?

Versão não-gulosa de *, correspondendo a zero ou mais ocorrências, com preferência pela correspondência mais curta.

+?

Versão não-gulosa de +, correspondendo a uma ou mais ocorrências, com preferência pela correspondência mais curta.

|

Corresponde ao sub-padrão do lado esquerdo ou ao do lado direito deste operador.

(...)

Agrupamento. Cada grupo é de captura (a subcadeia capturada pode ser acedida com o método match.group()).

(?:...)

Agrupamento sem captura. Cada grupo é correspondido segundo as mesmas regras do agrupamento normal, mas não fará parte do objeto de correspondência.

\d

Corresponde a um dígito. Equivalente a [0-9].

\D

Corresponde a um não-dígito. Equivalente a [^0-9].

\s

Corresponde a espaço em branco. Equivalente a [ \t-\r].

\S

Corresponde a não-espaço em branco. Equivalente a [^ \t-\r].

\w

Corresponde a «carácteres de palavra» (apenas ASCII). Equivalente a [A-Za-z0-9_].

\W

Corresponde a não-«carácteres de palavra» (apenas ASCII). Equivalente a [^A-Za-z0-9_].

\

Carácter de escape. Qualquer outro carácter que se siga à barra invertida, exceto os listados acima, é tratado literalmente. Por exemplo, \* equivale ao carácter literal * (não é tratado como o operador *). Note que \r, \n, etc. não são tratados de forma especial e equivalerão às letras literais r, n, etc. Por esta razão, não é recomendável usar cadeias Python em bruto (r"") para expressões regulares. Por exemplo, r"\r\n" quando usado como expressão regular equivale a "rn". Para corresponder ao carácter CR seguido de LF, use "\r\n".

NÃO SUPORTADO:

  • repetições contadas ({m,n})

  • grupos nomeados ((?P<name>...))

  • asserções mais avançadas (\b, \B)

  • escapes de carácteres especiais como \r, \n - use antes os escapes próprios do Python

  • etc.

Exemplo:

import re

# As re doesn't support escapes itself, use of r"" strings is not
# recommended.
regex = re.compile("[\r\n]")

regex.split("line1\rline2\nline3\r\n")

# Result:
# ['line1', 'line2', 'line3', '', '']

Funções

re.compile(regex_str: str, flags: int = 0) → 'regex'

Compila uma expressão regular e devolve um objeto regex.

re.search(regex_str: str, string: str) → 'match | None'

Compila regex_str e procura-o numa string. Ao contrário de match, esta função procura na cadeia a primeira posição que corresponda à expressão regular (que ainda pode ser 0 se a expressão regular estiver ancorada).

re.sub(regex_str: str, replace: str | Callable, string: str, count: int = 0, flags: int = 0, /) → str

Compila regex_str e procura-o em string, substituindo todas as correspondências por replace, e devolvendo a nova cadeia.

replace pode ser uma cadeia ou uma função. Se for uma cadeia, as sequências de escape da forma \<number> e \g<number> podem ser usadas para expandir para o grupo correspondente (ou uma cadeia vazia para grupos sem correspondência). Se replace for uma função, deve aceitar um único argumento (a correspondência) e devolver uma cadeia de substituição.

Se count for especificado e não-zero, a substituição parará após esse número de substituições. O argumento flags é ignorado.

Objetos Regex

Expressão regular compilada. As instâncias desta classe são criadas com re.compile().

class re.regex

Objeto de expressão regular compilada devolvido por re.compile().

match(string: str, pos: int = 0, endpos: int | None = None) → 'match | None'

Aplica esta expressão regular compilada a string, ancorada no início da região de pesquisa, e devolve um objeto match, ou None se a expressão regular não corresponder. Este é o equivalente compilado do match a nível de módulo, e é muito mais eficiente quando o mesmo padrão é aplicado a múltiplas cadeias.

O parâmetro opcional pos indica um índice em string onde a pesquisa deve começar; o valor predefinido é 0. Isto não é completamente equivalente a fatiar a cadeia; o padrão '^' corresponde ao verdadeiro início da cadeia e às posições imediatamente após uma nova linha, mas não necessariamente ao índice onde a pesquisa começa.

O parâmetro opcional endpos limita até onde string é pesquisada; é como se a cadeia tivesse endpos carácteres de comprimento, pelo que apenas os carácteres de pos a endpos - 1 são pesquisados. Se endpos for None (o valor predefinido), toda a cadeia é pesquisada.

search(string: str, pos: int = 0, endpos: int | None = None) → 'match | None'

Percorre string à procura da primeira posição onde esta expressão regular compilada produz uma correspondência, e devolve um objeto match, ou None se nenhuma posição corresponder. Este é o equivalente compilado da função search() a nível de módulo, e é muito mais eficiente quando o mesmo padrão é aplicado a múltiplas cadeias.

O parâmetro opcional pos indica um índice em string onde a pesquisa deve começar; o valor predefinido é 0. Isto não é completamente equivalente a fatiar a cadeia; o padrão '^' corresponde ao verdadeiro início da cadeia e às posições imediatamente após uma nova linha, mas não necessariamente ao índice onde a pesquisa começa.

O parâmetro opcional endpos limita até onde string é pesquisada; é como se a cadeia tivesse endpos carácteres de comprimento, pelo que apenas os carácteres de pos a endpos - 1 são pesquisados. Se endpos for None (o valor predefinido), toda a cadeia é pesquisada.

sub(replace: str | Callable, string: str, count: int = 0, flags: int = 0, /) → str

Procura esta expressão regular compilada em string, substituindo todas as correspondências por replace, e devolve a nova cadeia. Este é o equivalente compilado da função sub() a nível de módulo, e é muito mais eficiente quando o mesmo padrão é aplicado a múltiplas cadeias.

replace pode ser uma cadeia ou uma função. Se for uma cadeia, as sequências de escape da forma \<number> e \g<number> podem ser usadas para expandir para o grupo correspondente (ou uma cadeia vazia para grupos sem correspondência). Se replace for uma função, deve aceitar um único argumento (a correspondência) e devolver uma cadeia de substituição.

Se count for especificado e não-zero, a substituição parará após esse número de substituições. O argumento flags é ignorado.

split(string: str, max_split: int = -1, /) → List[str]

Divide uma string usando a expressão regular. Se max_split for fornecido, especifica o número máximo de divisões a efetuar. Devolve uma lista de cadeias (pode ter até max_split+1 elementos se for especificado).

Objetos de correspondência

Um objeto de correspondência contém o resultado de uma correspondência bem-sucedida.

class re.match(regex_str: str, string: str)

Faz corresponder regex_str a string, ancorado no início da cadeia, e devolve um objeto de correspondência, ou None se não corresponder. Este é o atalho a nível de módulo: re.match(regex_str, string) equivale a re.compile(regex_str).match(string).

O mesmo objeto de correspondência é também devolvido por search(), pelos métodos compilados regex.match() / regex.search(), e é passado à função de substituição usada por sub().

group(index: int) → str

Devolve a (sub)cadeia correspondente. index é 0 para a correspondência completa, 1 e superior para cada grupo de captura. Apenas grupos numéricos são suportados.