2. Análise léxica¶

Um programa Python é lido por um analisador. A entrada para o analisador é um fluxo de tokens, gerado pelo analisador léxico. Este capítulo descreve como o analisador léxico divide um arquivo em tokens.

Python lê o texto do programa como pontos de código Unicode; a codificação de um arquivo de origem pode ser fornecida por uma declaração de codificação que por padrão é UTF-8, consulte PEP 3120 para obter detalhes. Se o arquivo de origem não puder ser decodificado, uma exceção SyntaxError será levantada.

2.1. Estrutura das linhas¶

Um programa Python é dividido em uma série de linhas lógicas.

2.1.1. Linhas lógicas¶

O fim de uma linha lógica é representado pelo token NEWLINE. As declarações não podem cruzar os limites da linha lógica, exceto onde NEWLINE for permitido pela sintaxe (por exemplo, entre as declarações de declarações compostas). Uma linha lógica é construída a partir de uma ou mais linhas físicas seguindo as regras explícitas ou implícitas que juntam as linhas.

2.1.2. Linhas físicas¶

Uma linha física é uma sequência de caracteres terminada por uma sequência de fim de linha. Nos arquivos de origem e cadeias de caracteres, qualquer uma das sequências de terminação de linha de plataforma padrão pode ser usada - o formato Unix usando ASCII LF (linefeed), o formato Windows usando a sequência ASCII CR LF (return seguido de linefeed) ou o antigo formato Macintosh usando o caractere ASCII CR (return). Todos esses formatos podem ser usados igualmente, independentemente da plataforma. O final da entrada também serve como um finalizador implícito para a linha física final.

Ao incorporar o Python, strings de código-fonte devem ser passadas para APIs do Python usando as convenções C padrão para caracteres de nova linha (o caractere \n, representando ASCII LF, será o terminador de linha).

2.1.3. Comentários¶

Um comentário inicia com um caracter cerquilha (#) que não é parte de uma string literal, e termina com o fim da linha física. Um comentário significa o fim da linha lógica a menos que regras de junção de linha implicitas sejam invocadas. Comentários são ignorados pela sintaxe.

2.1.4. Declarações de codificação¶

Se um comentário na primeira ou segunda linha de um script Python corresponde com a expressão regular coding[=:]\s*([-\w.]+), esse comentário é processado com uma declaração de codificação; o primeiro grupo dessa expressão indica a codificação do arquivo do código-fonte. A declaração de codificação deve aparecer em uma linha exclusiva para tal. Se está na segunda linha, a primeira linha também deve ser uma linha somente com comentário. As formas recomendadas de uma declaração de codificação são:

# -*- coding: <encoding-name> -*-

que é reconhecido também por GNU Emacs, e

# vim:fileencoding=<encoding-name>

que é reconhecido pelo VIM de Bram Moolenaar.

Se nenhuma codificação é declarada, a codificação padrão é UTF-8. Se a codificação implícita ou explícita de um arquivo é UTF-8, uma marca inicial de ordem de byte UTF-8 (b’xefxbbxbf’) será ignorada em vez de ser um erro de sintaxe.

Se uma codificação é declarada, o nome da codificação deve ser reconhecida pelo Python (veja Standard Encodings). A codificação é usada por toda análise léxica, incluindo literais strings, comment and identificadores.

2.1.5. Junção de linha explícita¶

Duas ou mais linhas físicas podem ser juntadas em linhas lógicas usando o caractere contrabarra (\) da seguinte forma: quando uma linha física termina com uma contrabarra que não é parte da uma literal string ou comentário, ela é juntada com a linha seguinte formando uma única linha lógica, removendo a contrabarra e o caractere de fim de linha seguinte. Por exemplo:

if 1900 < year < 2100 and 1 <= month <= 12 \
   and 1 <= day <= 31 and 0 <= hour < 24 \
   and 0 <= minute < 60 and 0 <= second < 60:   # Looks like a valid date
        return 1

Uma linha terminada em uma contrabarra não pode conter um comentário. Uma barra invertida não continua um comentário. Uma contrabarra não continua um token, exceto para strings literais (ou seja, tokens diferentes de strings literais não podem ser divididos em linhas físicas usando uma contrabarra). Uma contrabarra é ilegal em qualquer outro lugar em uma linha fora de uma string literal.

2.1.6. Junção de linha implícita¶

Expressões entre parênteses, colchetes ou chaves podem ser quebradas em mais de uma linha física sem a necessidade do uso de contrabarras. Por exemplo:

month_names = ['Januari', 'Februari', 'Maart',      # These are the
               'April',   'Mei',      'Juni',       # Dutch names
               'Juli',    'Augustus', 'September',  # for the months
               'Oktober', 'November', 'December']   # of the year

Linhas continuadas implicitamente podem conter comentários. O recuo das linhas de continuação não é importante. Linhas de continuação em branco são permitidas. Não há token NEWLINE entre linhas de continuação implícitas. Linhas continuadas implicitamente também podem ocorrer dentro de strings com aspas triplas (veja abaixo); nesse caso, eles não podem conter comentários.

2.1.7. Linhas em branco¶

Uma linha lógica que contém apenas espaços, tabulações, quebras de página e possivelmente um comentário é ignorada (ou seja, nenhum token NEWLINE é gerado). Durante a entrada interativa de instruções, o tratamento de uma linha em branco pode diferir dependendo da implementação do interpretador. No interpretador interativo padrão, uma linha lógica totalmente em branco (ou seja, uma que não contenha nem mesmo espaço em branco ou um comentário) encerra uma instrução de várias linhas.

2.1.8. Indentação¶

O espaço em branco (espaços e tabulações) no início de uma linha lógica é usado para calcular o nível de indentação da linha, que por sua vez é usado para determinar o agrupamento de instruções.

As tabulações são substituídas (da esquerda para a direita) por um a oito espaços, de modo que o número total de caracteres até e incluindo a substituição seja um múltiplo de oito (essa é intencionalmente a mesma regra usada pelo Unix). O número total de espaços que precedem o primeiro caractere não em branco determina o recuo da linha. O recuo não pode ser dividido em várias linhas físicas usando contrabarra; o espaço em branco até a primeira contrabarra determina a indentação.

A indentação é rejeitada como inconsistente se um arquivo de origem mistura tabulações e espaços de uma forma que torna o significado dependente do valor de uma tabulação em espaços; uma exceção TabError é levantada nesse caso.

Nota de compatibilidade entre plataformas: devido à natureza dos editores de texto em plataformas não-UNIX, não é aconselhável usar uma mistura de espaços e tabulações para o recuo em um único arquivo de origem. Deve-se notar também que diferentes plataformas podem limitar explicitamente o nível máximo de indentação.

Um caractere de quebra de página pode estar presente no início da linha; ele será ignorado para os cálculos de indentação acima. Os caracteres de quebra de página que ocorrem em outro lugar além do espaço em branco inicial têm um efeito indefinido (por exemplo, eles podem redefinir a contagem de espaços para zero).

Os níveis de indentação das linhas consecutivas são usados para gerar tokens INDENT e DEDENT, usando uma pilha, como segue.

Antes da leitura da primeira linha do arquivo, um único zero é colocado na pilha; isso nunca mais será exibido. Os números colocados na pilha sempre aumentarão estritamente de baixo para cima. No início de cada linha lógica, o nível de indentação da linha é comparado ao topo da pilha. Se for igual, nada acontece. Se for maior, ele é colocado na pilha e um token INDENT é gerado. Se for menor, deve ser um dos números que aparecem na pilha; todos os números maiores na pilha são retirados e, para cada número retirado, um token DEDENT é gerado. Ao final do arquivo, um token DEDENT é gerado para cada número restante na pilha que seja maior que zero.

Aqui está um exemplo de um trecho de código Python indentado corretamente (embora confuso):

def perm(l):
        # Compute the list of all permutations of l
    if len(l) <= 1:
                  return [l]
    r = []
    for i in range(len(l)):
             s = l[:i] + l[i+1:]
             p = perm(s)
             for x in p:
              r.append(l[i:i+1] + x)
    return r

O exemplo a seguir mostra vários erros de indentação:

 def perm(l):                       # error: first line indented
for i in range(len(l)):             # error: not indented
    s = l[:i] + l[i+1:]
        p = perm(l[:i] + l[i+1:])   # error: unexpected indent
        for x in p:
                r.append(l[i:i+1] + x)
            return r                # error: inconsistent dedent

(Na verdade, os três primeiros erros são detectados pelo analisador sintático; apenas o último erro é encontrado pelo analisador léxico — o recuo de não corresponde a um nível retirado da pilha.)

2.1.9. Espaços em branco entre tokens¶

Exceto no início de uma linha lógica ou em string literais, os caracteres de espaço em branco (espaço, tabulação e quebra de página) podem ser usados alternadamente para separar tokens. O espaço em branco é necessário entre dois tokens somente se sua concatenação puder ser interpretada como um token diferente (por exemplo, ab é um token, mas a b são dois tokens).

2.2. Outros tokens¶

Além de NEWLINE, INDENT e DEDENT, existem as seguintes categorias de tokens: identificadores, palavras-chave, literais, operadores e delimitadores. Caracteres de espaço em branco (exceto terminadores de linha, discutidos anteriormente) não são tokens, mas servem para delimitar tokens. Onde existe ambiguidade, um token compreende a string mais longa possível que forma um token legal, quando lido da esquerda para a direita.

2.3. Identificadores e palavras-chave¶

Identificadores (também chamados de nomes) são descritos pelas seguintes definições lexicais.

A sintaxe dos identificadores em Python é baseada no anexo do padrão Unicode UAX-31, com elaboração e alterações conforme definido abaixo; veja também PEP 3131 para mais detalhes.

Dentro do intervalo ASCII (U+0001..U+007F), os caracteres válidos para identificadores são os mesmos de Python 2.x: as letras maiúsculas e minúsculas de A até Z, o sublinhado _ e, exceto para o primeiro caractere, os dígitos 0 até 9.

Python 3.0 introduz caracteres adicionais fora do intervalo ASCII (consulte PEP 3131). Para esses caracteres, a classificação utiliza a versão do Banco de Dados de Caracteres Unicode incluída no módulo unicodedata.

Os identificadores têm comprimento ilimitado. Maiúsculas são diferentes de minúsculas.

identifier   ::=  xid_start xid_continue*
id_start     ::=  <all characters in general categories Lu, Ll, Lt, Lm, Lo, Nl, the underscore, and characters with the Other_ID_Start property>
id_continue  ::=  <all characters in id_start, plus characters in the categories Mn, Mc, Nd, Pc and others with the Other_ID_Continue property>
xid_start    ::=  <all characters in id_start whose NFKC normalization is in "id_start xid_continue*">
xid_continue ::=  <all characters in id_continue whose NFKC normalization is in "id_continue*">

Os códigos de categoria Unicode mencionados acima significam:

Lu - letras maiúsculas
Ll - letras minúsculas
Lt - letras em titlecase
Lm - letras modificadoras
Lo - outras letras
Nl - letras numéricas
Mn - marcas sem espaçamento
Mc - marcas de combinação de espaçamento
Nd - números decimais
Pc - pontuações de conectores
Other_ID_Start - explicit list of characters in PropList.txt to support backwards compatibility
Other_ID_Continue - igualmente

Todos os identificadores são convertidos no formato normal NFKC durante a análise; a comparação de identificadores é baseada no NFKC.

A non-normative HTML file listing all valid identifier characters for Unicode 14.0.0 can be found at https://www.unicode.org/Public/14.0.0/ucd/DerivedCoreProperties.txt

2.3.1. Palavras reservadas¶

Os seguintes identificadores são usados como palavras reservadas, ou palavras-chave da linguagem, e não podem ser usados como identificadores comuns. Eles devem ser escritos exatamente como estão escritos aqui:

False      await      else       import     pass
None       break      except     in         raise
True       class      finally    is         return
and        continue   for        lambda     try
as         def        from       nonlocal   while
assert     del        global     not        with
async      elif       if         or         yield

2.3.2. Palavras reservadas contextuais¶

Novo na versão 3.10.

Some identifiers are only reserved under specific contexts. These are known as soft keywords. The identifiers match, case and _ can syntactically act as keywords in contexts related to the pattern matching statement, but this distinction is done at the parser level, not when tokenizing.

As soft keywords, their use with pattern matching is possible while still preserving compatibility with existing code that uses match, case and _ as identifier names.

2.3.3. Classes reservadas de identificadores¶

Certas classes de identificadores (além de palavras reservadas) possuem significados especiais. Essas classes são identificadas pelos padrões de caracteres de sublinhado iniciais e finais:

_*

Não importado por from module import *.

_

Em um padrão case de uma instrução match, _ é uma palavra reservada contextual que denota um curinga.

Isoladamente, o interpretador interativo disponibiliza o resultado da última avaliação na variável _. (Ele é armazenado no módulo builtins, juntamente com funções embutidas como print.)

Em outros lugares, _ é um identificador comum. Muitas vezes é usado para nomear itens “especiais”, mas não é especial para o Python em si.

Nota

O nome _ é frequentemente usado em conjunto com internacionalização; consulte a documentação do módulo gettext para obter mais informações sobre esta convenção.

Também é comumente usado para variáveis não utilizadas.

__*__

Nomes definidos pelo sistema, informalmente conhecidos como nomes “dunder”. Esses nomes e suas implementações são definidos pelo interpretador (incluindo a biblioteca padrão). Os nomes de sistema atuais são discutidos na seção Nomes de métodos especiais e em outros lugares. Provavelmente mais nomes serão definidos em versões futuras do Python. Qualquer uso de nomes __*__, em qualquer contexto, que não siga o uso explicitamente documentado, está sujeito a quebra sem aviso prévio.

__*

Nomes de classes privadas. Os nomes nesta categoria, quando usados no contexto de uma definição de classe, são reescritos para usar uma forma desfigurada para ajudar a evitar conflitos de nomes entre atributos “privados” de classes base e derivadas. Consulte a seção Identificadores (Nomes).

2.4. Literais¶

Literais são notações para valores constantes de alguns tipos embutidos.

2.4.1. Literais de string e bytes¶

Literais de string são descritos pelas seguintes definições lexicais:

stringliteral   ::=  [stringprefix](shortstring | longstring)
stringprefix    ::=  "r" | "u" | "R" | "U" | "f" | "F"
                     | "fr" | "Fr" | "fR" | "FR" | "rf" | "rF" | "Rf" | "RF"
shortstring     ::=  "'" shortstringitem* "'" | '"' shortstringitem* '"'
longstring      ::=  "'''" longstringitem* "'''" | '"""' longstringitem* '"""'
shortstringitem ::=  shortstringchar | stringescapeseq
longstringitem  ::=  longstringchar | stringescapeseq
shortstringchar ::=  <any source character except "\" or newline or the quote>
longstringchar  ::=  <any source character except "\">
stringescapeseq ::=  "\" <any source character>

bytesliteral   ::=  bytesprefix(shortbytes | longbytes)
bytesprefix    ::=  "b" | "B" | "br" | "Br" | "bR" | "BR" | "rb" | "rB" | "Rb" | "RB"
shortbytes     ::=  "'" shortbytesitem* "'" | '"' shortbytesitem* '"'
longbytes      ::=  "'''" longbytesitem* "'''" | '"""' longbytesitem* '"""'
shortbytesitem ::=  shortbyteschar | bytesescapeseq
longbytesitem  ::=  longbyteschar | bytesescapeseq
shortbyteschar ::=  <any ASCII character except "\" or newline or the quote>
longbyteschar  ::=  <any ASCII character except "\">
bytesescapeseq ::=  "\" <any ASCII character>

Uma restrição sintática não indicada por essas produções é que não são permitidos espaços em branco entre o stringprefix ou bytesprefix e o restante do literal. O conjunto de caracteres de origem é definido pela declaração de codificação; é UTF-8 se nenhuma declaração de codificação for fornecida no arquivo de origem; veja a seção Declarações de codificação.

In plain English: Both types of literals can be enclosed in matching single quotes (') or double quotes ("). They can also be enclosed in matching groups of three single or double quotes (these are generally referred to as triple-quoted strings). The backslash (\) character is used to escape characters that otherwise have a special meaning, such as newline, backslash itself, or the quote character.

Literais de bytes são sempre prefixados com 'b' ou 'B'; eles produzem uma instância do tipo bytes em vez do tipo str. Eles só podem conter caracteres ASCII; bytes com valor numérico igual ou superior a 128 devem ser expressos com escapes.

Literais de string e bytes podem opcionalmente ser prefixados com uma letra 'r' ou 'R'; essas strings são chamadas de strings brutas e tratam as barras invertidas como caracteres literais. Como resultado, em literais de string, os escapes '\U' e '\u' em strings brutas não são tratados de maneira especial. Dado que os literais unicode brutos de Python 2.x se comportam de maneira diferente dos de Python 3.x, não há suporte para a sintaxe 'ur' .

Novo na versão 3.3: O prefixo 'rb' de literais de bytes brutos foi adicionado como sinônimo de 'br'.

O suporte para o literal legado unicode (u'value') foi reintroduzido para simplificar a manutenção de bases de código duplas Python 2.x e 3.x. Consulte PEP 414 para obter mais informações.

Uma string literal com 'f' ou 'F' em seu prefixo é uma string literal formatada; veja Literais de strings formatadas. O 'f' pode ser combinado com 'r', mas não com 'b' ou 'u', portanto strings formatadas brutas são possíveis, mas literais de bytes formatados não são.

Em literais com aspas triplas, novas linhas e aspas sem escape são permitidas (e são retidas), exceto que três aspas sem escape em uma linha encerram o literal. (Uma “aspas” é o caractere usado para abrir o literal, ou seja, ' ou ".)

2.4.1.1. Sequências de escape¶

A menos que um prefixo 'r' ou 'R' esteja presente, as sequências de escape em literais de string e bytes são interpretadas de acordo com regras semelhantes àquelas usadas pelo Standard C. As sequências de escape reconhecidas são:

Sequência de escape	Significado	Notas
`\`<newline>	A barra invertida e a nova linha foram ignoradas	(1)
`\\`	Contrabarra (`\`)
`\'`	Aspas simples (`'`)
`\"`	Aspas duplas (`"`)
`\a`	ASCII Bell (BEL) - um sinal audível é emitido
`\b`	ASCII Backspace (BS) - apaga caractere à esquerda
`\f`	ASCII Formfeed (FF) - quebra de página
`\n`	ASCII Linefeed (LF) - quebra de linha
`\r`	ASCII Carriage Return (CR) - retorno de carro
`\t`	ASCII Horizontal Tab (TAB) - tabulação horizontal
`\v`	ASCII Vertical Tab (VT) - tabulação vertical
`\ooo`	Caractere com valor octal ooo	(2,4)
`\xhh`	Caractere com valor hexadecimal hh	(3,4)

As sequências de escape apenas reconhecidas em literais de strings são:

Sequência de escape	Significado	Notas
`\N{name}`	Caractere chamado name no banco de dados Unicode	(5)
`\uxxxx`	Caractere com valor hexadecimal de 16 bits xxxx	(6)
`\Uxxxxxxxx`	Caractere com valor hexadecimal de 32 bits xxxxxxxx	(7)

Notas:

Uma contrabarra pode ser adicionada ao fim da linha para ignorar a nova linha:
```
>>> 'This string will not include \
... backslashes or newline characters.'
'This string will not include backslashes or newline characters.'
```
O mesmo resultado pode ser obtido usando strings com aspas triplas, ou parênteses e concatenação de literal string.
Como no padrão C, são aceitos até três dígitos octais.

Alterado na versão 3.11: Octal escapes with value larger than 0o377 produce a DeprecationWarning. In a future Python version they will be a SyntaxWarning and eventually a SyntaxError.
Ao contrário do padrão C, são necessários exatamente dois dígitos hexadecimais.
Em um literal de bytes, os escapes hexadecimais e octais denotam o byte com o valor fornecido. Em uma literal de string, esses escapes denotam um caractere Unicode com o valor fornecido.
Alterado na versão 3.3: O suporte para apelidos de nome [1] foi adicionado.
São necessários exatos quatro dígitos hexadecimais.
Qualquer caractere Unicode pode ser codificado desta forma. São necessários exatamente oito dígitos hexadecimais.

Ao contrário do padrão C, todas as sequências de escape não reconhecidas são deixadas inalteradas na string, ou seja, a contrabarra é deixada no resultado. (Esse comportamento é útil durante a depuração: se uma sequência de escape for digitada incorretamente, a saída resultante será mais facilmente reconhecida como quebrada.) Também é importante observar que as sequências de escape reconhecidas apenas em literais de string se enquadram na categoria de escapes não reconhecidos para literais de bytes.

Alterado na versão 3.6: Unrecognized escape sequences produce a DeprecationWarning. In a future Python version they will be a SyntaxWarning and eventually a SyntaxError.

Mesmo em um literal bruto, as aspas podem ser escapadas com uma contrabarra, mas a barra invertida permanece no resultado; por exemplo, r"\"" é uma literal de string válida que consiste em dois caracteres: uma contrabarra e aspas duplas; r"\" não é uma literal de string válida (mesmo uma string bruta não pode terminar em um número ímpar de contrabarras). Especificamente, um literal bruto não pode terminar em uma única contrabarra (já que a contrabarra escaparia do seguinte caractere de aspas). Observe também que uma única contrabarra seguida por uma nova linha é interpretada como esses dois caracteres como parte do literal, não como uma continuação de linha.

2.4.2. Concatenação de literal de string¶

São permitidos vários literais de strings ou bytes adjacentes (delimitados por espaços em branco), possivelmente usando diferentes convenções de delimitação de strings, e seu significado é o mesmo de sua concatenação. Assim, "hello" 'world' é equivalente a "helloworld". Este recurso pode ser usado para reduzir o número de barras invertidas necessárias, para dividir strings longas convenientemente em linhas longas ou até mesmo para adicionar comentários a partes de strings, por exemplo:

re.compile("[A-Za-z_]"       # letter or underscore
           "[A-Za-z0-9_]*"   # letter, digit or underscore
          )

Observe que esse recurso é definido no nível sintático, mas implementado em tempo de compilação. O operador ‘+’ deve ser usado para concatenar expressões de string em tempo de execução. Observe também que a concatenação literal pode usar diferentes estilos de delimitação de strings para cada componente (mesmo misturando strings brutas e strings com aspas triplas), e literais de string formatados podem ser concatenados com literais de string simples.

2.4.3. Literais de strings formatadas¶

Novo na versão 3.6.

Um literal de string formatado ou f-string é uma literal de string prefixado com 'f' ou 'F'. Essas strings podem conter campos de substituição, que são expressões delimitadas por chaves {}. Embora outros literais de string sempre tenham um valor constante, strings formatadas são, na verdade, expressões avaliadas em tempo de execução.

As sequências de escape são decodificadas como em literais de string comuns (exceto quando um literal também é marcado como uma string bruta). Após a decodificação, a gramática do conteúdo da string é:

f_string          ::=  (literal_char | "{{" | "}}" | replacement_field)*
replacement_field ::=  "{" f_expression ["="] ["!" conversion] [":" format_spec] "}"
f_expression      ::=  (conditional_expression | "*" or_expr)
                         ("," conditional_expression | "," "*" or_expr)* [","]
                       | yield_expression
conversion        ::=  "s" | "r" | "a"
format_spec       ::=  (literal_char | replacement_field)*
literal_char      ::=  <any code point except "{", "}" or NULL>

As partes da string fora das chaves são tratadas literalmente, exceto que quaisquer chaves duplas '{{' ou '}}' são substituídas pela chave única correspondente. Uma única chave de abertura '{' marca um campo de substituição, que começa com uma expressão Python. Para exibir o texto da expressão e seu valor após a avaliação (útil na depuração), um sinal de igual '=' pode ser adicionado após a expressão. Um campo de conversão, introduzido por um ponto de exclamação '!', pode vir a seguir. Um especificador de formato também pode ser anexado, introduzido por dois pontos ':'. Um campo de substituição termina com uma chave de fechamento '}'.

Expressions in formatted string literals are treated like regular Python expressions surrounded by parentheses, with a few exceptions. An empty expression is not allowed, and both lambda and assignment expressions := must be surrounded by explicit parentheses. Replacement expressions can contain line breaks (e.g. in triple-quoted strings), but they cannot contain comments. Each expression is evaluated in the context where the formatted string literal appears, in order from left to right.

Alterado na versão 3.7: Antes do Python 3.7, uma expressão await e compreensões contendo uma cláusula async for eram ilegais nas expressões em literais de string formatados devido a um problema com a implementação.

Quando o sinal de igual '=' for fornecido, a saída terá o texto da expressão, o '=' e o valor avaliado. Os espaços após a chave de abertura '{', dentro da expressão e após '=' são todos preservados na saída. Por padrão, '=' faz com que repr() da expressão seja fornecida, a menos que haja um formato especificado. Quando um formato é especificado, o padrão é o str() da expressão, a menos que uma conversão '!r' seja declarada.

Novo na versão 3.8: O sinal de igual '='.

Se uma conversão for especificada, o resultado da avaliação da expressão será convertido antes da formatação. A conversão '!s' chama str() no resultado, '!r' chama repr() e '!a' chama ascii().

O resultado é então formatado usando o protocolo format(). O especificador de formato é passado para o método __format__() da expressão ou resultado da conversão. Uma string vazia é passada quando o especificador de formato é omitido. O resultado formatado é então incluído no valor final de toda a string.

Os especificadores de formato de nível superior podem incluir campos de substituição aninhados. Esses campos aninhados podem incluir seus próprios campos de conversão e especificadores de formato, mas podem não incluir campos de substituição aninhados mais profundamente. A minilinguagem do especificador de formato é a mesma usada pelo método str.format().

Literais de string formatados podem ser concatenados, mas os campos de substituição não podem ser divididos entre literais.

Alguns exemplos de literais de string formatados:

>>> name = "Fred"
>>> f"He said his name is {name!r}."
"He said his name is 'Fred'."
>>> f"He said his name is {repr(name)}."  # repr() is equivalent to !r
"He said his name is 'Fred'."
>>> width = 10
>>> precision = 4
>>> value = decimal.Decimal("12.34567")
>>> f"result: {value:{width}.{precision}}"  # nested fields
'result:      12.35'
>>> today = datetime(year=2017, month=1, day=27)
>>> f"{today:%B %d, %Y}"  # using date format specifier
'January 27, 2017'
>>> f"{today=:%B %d, %Y}" # using date format specifier and debugging
'today=January 27, 2017'
>>> number = 1024
>>> f"{number:#0x}"  # using integer format specifier
'0x400'
>>> foo = "bar"
>>> f"{ foo = }" # preserves whitespace
" foo = 'bar'"
>>> line = "The mill's closed"
>>> f"{line = }"
'line = "The mill\'s closed"'
>>> f"{line = :20}"
"line = The mill's closed   "
>>> f"{line = !r:20}"
'line = "The mill\'s closed" '

A consequence of sharing the same syntax as regular string literals is that characters in the replacement fields must not conflict with the quoting used in the outer formatted string literal:

f"abc {a["x"]} def"    # error: outer string literal ended prematurely
f"abc {a['x']} def"    # workaround: use different quoting

Backslashes are not allowed in format expressions and will raise an error:

f"newline: {ord('\n')}"  # raises SyntaxError

To include a value in which a backslash escape is required, create a temporary variable.

>>> newline = ord('\n')
>>> f"newline: {newline}"
'newline: 10'

Literais de string formatados não podem ser usados como strings de documentação, mesmo que não incluam expressões.

>>> def foo():
...     f"Not a docstring"
...
>>> foo.__doc__ is None
True

Consulte também PEP 498 para a proposta que adicionou literais de string formatados e str.format(), que usa um mecanismo de string de formato relacionado.

2.4.4. Literais numéricos¶

Existem três tipos de literais numéricos: inteiros, números de ponto flutuante e números imaginários. Não existem literais complexos (números complexos podem ser formados adicionando um número real e um número imaginário).

Observe que os literais numéricos não incluem um sinal; uma frase como -1 é, na verdade, uma expressão composta pelo operador unário ‘-2’ e o literal 1.

2.4.5. Inteiros literais¶

Literais inteiros são descritos pelas seguintes definições léxicas:

integer      ::=  decinteger | bininteger | octinteger | hexinteger
decinteger   ::=  nonzerodigit (["_"] digit)* | "0"+ (["_"] "0")*
bininteger   ::=  "0" ("b" | "B") (["_"] bindigit)+
octinteger   ::=  "0" ("o" | "O") (["_"] octdigit)+
hexinteger   ::=  "0" ("x" | "X") (["_"] hexdigit)+
nonzerodigit ::=  "1"..."9"
digit        ::=  "0"..."9"
bindigit     ::=  "0" | "1"
octdigit     ::=  "0"..."7"
hexdigit     ::=  digit | "a"..."f" | "A"..."F"

Não há limite para o comprimento de literais inteiros além do que pode ser armazenado na memória disponível.

Os sublinhados são ignorados para determinar o valor numérico do literal. Eles podem ser usados para agrupar dígitos para maior legibilidade. Um sublinhado pode ocorrer entre dígitos e após especificadores de base como 0x.

Observe que não são permitidos zeros à esquerda em um número decimal diferente de zero. Isto é para desambiguação com literais octais de estilo C, que o Python usava antes da versão 3.0.

Alguns exemplos de literais inteiros:

7     2147483647                        0o177    0b100110111
3     79228162514264337593543950336     0o377    0xdeadbeef
      100_000_000_000                   0b_1110_0101

Alterado na versão 3.6: Os sublinhados agora são permitidos para fins de agrupamento de literais.

2.4.6. Literais de ponto flutuante¶

Literais de ponto flutuante são descritos pelas seguintes definições léxicas:

floatnumber   ::=  pointfloat | exponentfloat
pointfloat    ::=  [digitpart] fraction | digitpart "."
exponentfloat ::=  (digitpart | pointfloat) exponent
digitpart     ::=  digit (["_"] digit)*
fraction      ::=  "." digitpart
exponent      ::=  ("e" | "E") ["+" | "-"] digitpart

Observe que as partes inteiras e expoentes são sempre interpretadas usando base 10. Por exemplo, 077e010 é válido e representa o mesmo número que 77e10. O intervalo permitido de literais de ponto flutuante depende da implementação. Assim como em literais inteiros, os sublinhados são permitidos para agrupamento de dígitos.

Alguns exemplos de literais de ponto flutuante:

3.14    10.    .001    1e100    3.14e-10    0e0    3.14_15_93

Alterado na versão 3.6: Os sublinhados agora são permitidos para fins de agrupamento de literais.

2.4.7. Literais imaginários¶

Os literais imaginários são descritos pelas seguintes definições léxicas:

imagnumber ::=  (floatnumber | digitpart) ("j" | "J")

Um literal imaginário produz um número complexo com uma parte real igual a 0.0. Os números complexos são representados como um par de números de ponto flutuante e têm as mesmas restrições em seu alcance. Para criar um número complexo com uma parte real diferente de zero, adicione um número de ponto flutuante a ele, por exemplo, (3 + 4j). Alguns exemplos de literais imaginários:

3.14j   10.j    10j     .001j   1e100j   3.14e-10j   3.14_15_93j

2.5. Operadores¶

Os seguintes tokens são operadores:

+       -       *       **      /       //      %      @
<<      >>      &       |       ^       ~       :=
<       >       <=      >=      ==      !=

2.6. Delimitadores¶

Os seguintes tokens servem como delimitadores na gramática:

(       )       [       ]       {       }
,       :       .       ;       @       =       ->
+=      -=      *=      /=      //=     %=      @=
&=      |=      ^=      >>=     <<=     **=

O ponto também pode ocorrer em literais de ponto flutuante e imaginário. Uma sequência de três períodos tem um significado especial como um literal de reticências. A segunda metade da lista, os operadores de atribuição aumentada, servem lexicalmente como delimitadores, mas também realizam uma operação.

Os seguintes caracteres ASCII imprimíveis têm um significado especial como parte de outros tokens ou são significativos para o analisador léxico:

'       "       #       \

Os seguintes caracteres ASCII imprimíveis não são usados em Python. Sua ocorrência fora de literais de string e comentários é um erro incondicional:

$       ?       `

Notas de rodapé