2. Análise léxica¶
Um programa Python é lido por um analisador. A entrada para o analisador é um fluxo de tokens, gerados pelo analisador léxico (também conhecido como tokenizador). 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¶
The end of a logical line is represented by the token NEWLINE
.
Statements cannot cross logical line boundaries except where NEWLINE
is allowed by the syntax (e.g., between statements in compound statements).
A logical line is constructed from one or more physical lines by following
the explicit or implicit
line joining rules.
2.1.2. Linhas físicas¶
A physical line is a sequence of characters terminated by one the following end-of-line sequences:
the Unix form using ASCII LF (linefeed),
the Windows form using the ASCII sequence CR LF (return followed by linefeed),
the ‘Classic Mac OS’ form using the ASCII CR (return) character.
Regardless of platform, each of these sequences is replaced by a single ASCII LF (linefeed) character. (This is done even inside string literals.) Each line can use any of the sequences; they do not need to be consistent within a file.
The end of input also serves as an implicit terminator for the final physical line.
Formally:
newline: <ASCII LF> | <ASCII CR> <ASCII LF> | <ASCII CR>
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: <nome-codificação> -*-
que é reconhecido também por GNU Emacs, e
# vim:fileencoding=<nome-codificação>
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'\xef\xbb\xbf'
) 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.
All lexical analysis, including string literals, comments and identifiers, works on Unicode text decoded using the source encoding. Any Unicode code point, except the NUL control character, can appear in Python source.
source_character: <any Unicode code point, except NUL>
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: # Parece ser uma data válida
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', # Estes são os
'April', 'Mei', 'Juni', # nomes holandeses
'Juli', 'Augustus', 'September', # para os meses
'Oktober', 'November', 'December'] # do ano
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 multilinha.
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):
# Calcula a lista de todas as permutações de 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): # erro: primeira linha indentada
for i in range(len(l)): # erro: não indentada
s = l[:i] + l[i+1:]
p = perm(l[:i] + l[i+1:]) # erro: indentação inesperada
for x in p:
r.append(l[i:i+1] + x)
return r # erro: desindentação inconsistente
(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). Entretanto, +a
e + a
produzem dois tokens, +
e a
, pois +a
não é um token válido.
2.1.10. Marcador de fim¶
No final da entrada não interativa, o analisador léxico gera um token ENDMARKER
.
2.2. Outros tokens¶
Além de NEWLINE
, INDENT
e DEDENT
, existem as seguintes categorias de tokens: identificadores, palavras-chave (NAME
), literais (tal como NUMBER
e STRING
) e outros símbolos (operadores e delimitadores, OP
). Caracteres de espaço em branco (exceto terminadores lógicos 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. Nomes (identificadores e palavras reservadas)¶
Tokens NAME
representam identificadores, palavras reservadas e palavras reservadas contextuais.
Dentro do intervalo ASCII (U+0001..U+007F), os caracteres válidos para nomes incluem letras maiúsculas e minúsculas (A-Z
e a-z
), o sublinhado _
e, exceto pelo primeiro caractere, os dígitos 0
a 9
.
Os nomes devem conter pelo menos um caractere, mas não há limite máximo de tamanho. Maiúsculas e minúsculas são relevantes.
Além de A-Z
, a-z
, _
e 0-9
, os nomes também podem usar caracteres “letras ou similares” e “números ou similares” de fora do intervalo ASCII, conforme detalhado abaixo.
Todos os identificadores são convertidos no formato normal NFKC durante a análise; a comparação de identificadores é baseada no NFKC.
Formalmente, o primeiro caractere de um identificador normalizado deve pertencer ao conjunto id_start
, que é a união de:
Categoria Unicode
<Lu>
- letras maiúsculas (incluiA
aZ
)Categoria Unicode
<Ll>
- letras minúsculas (incluia
az
)Categoria Unicode
<Lt>
- letras em titlecase (coloca em maiúsculo a primeira letra de cada palavra principal)Categoria Unicode
<Lm>
- letras modificadorasCategoria Unicode
<Lo>
- outras letrasCategoria Unicode
<Nl>
- números de letras{
"_"
} - o underscore (sublinhado)<Other_ID_Start>
- um conjunto explícito de caracteres em PropList.txt para oferecer suporte à retrocompatibilidade
Os caracteres restantes devem pertencer ao conjunto id_continue
, que é a união de:
todos os caracteres em
id_start
Categoria Unicode
<Nd>
- números decimais (inclui0
a9
)Categoria Unicode
<Pc>
- pontuações de conectoresCategoria Unicode
<Mn>
- marcas sem espaçamentoCategoria Unicode
<Mc>
- espaçamento combinando marcas<Other_ID_Continue>
- outro conjunto explícito de caracteres em PropList.txt para oferecer suporte à retrocompatibilidade
As categorias Unicode usam a versão do Unicode Character Database (em português, banco de dados de caracteres Unicode) incluída no módulo unicodedata
.
Esses conjuntos são baseados no anexo padrão Unicode UAX-31. Veja também PEP 3131 para mais detalhes.
De forma ainda mais formal, os nomes são descritos pelas seguintes definições lexicais:
NAME:xid_start
xid_continue
* id_start: <Lu> | <Ll> | <Lt> | <Lm> | <Lo> | <Nl> | "_" | <Other_ID_Start> id_continue:id_start
| <Nd> | <Pc> | <Mn> | <Mc> | <Other_ID_Continue> xid_start: <all characters inid_start
whose NFKC normalization is in (id_start
xid_continue
*)"> xid_continue: <all characters inid_continue
whose NFKC normalization is in (id_continue
*)"> identifier: <NAME
, except keywords>
Uma lista não normativa de todos os caracteres identificadores válidos, conforme definido pelo Unicode, está disponível no arquivo DerivedCoreProperties.txt no Unicode Character Database.
2.3.1. Palavras reservadas¶
Os nomes a seguir são usados como palavras reservadas 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¶
Adicionado na versão 3.10.
Alguns nomes são reservados apenas em contextos específicos. São conhecidos como palavras reservadas contextuais:
Elas agem sintaticamente como palavra reservada em seus contextos específicos, mas essa distinção é feita no nível do analisador sintático, não na tokenização.
Como palavras reservadas contextuais, seu uso na gramática é possível preservando a compatibilidade com o código existente que usa esses nomes como identificadores.
Alterado na versão 3.12: type
é agora uma palavra reservada contextual.
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çãomatch
,_
é 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ódulobuiltins
, juntamente com funções embutidas comoprint
.)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ódulogettext
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.
In terms of lexical analysis, Python has string, bytes and numeric literals.
Other “literals” are lexically denoted using keywords
(None
, True
, False
) and the special
ellipsis token (...
).
2.5. Literais de string e bytes¶
String literals are text enclosed in single quotes ('
) or double
quotes ("
). For example:
"spam"
'eggs'
The quote used to start the literal also terminates it, so a string literal can only contain the other quote (except with escape sequences, see below). For example:
'Say "Hello", please.'
"Don't do that!"
Except for this limitation, the choice of quote character ('
or "
)
does not affect how the literal is parsed.
Inside a string literal, the backslash (\
) character introduces an
escape sequence, which has special meaning depending on the character
after the backslash.
For example, \"
denotes the double quote character, and does not end
the string:
>>> print("Say \"Hello\" to everyone!")
Say "Hello" to everyone!
See escape sequences below for a full list of such sequences, and more details.
2.5.1. Triple-quoted strings¶
Strings can also be enclosed in matching groups of three single or double quotes. These are generally referred to as triple-quoted strings:
"""This is a triple-quoted string."""
In triple-quoted literals, unescaped quotes are allowed (and are
retained), except that three unescaped quotes in a row terminate the literal,
if they are of the same kind ('
or "
) used at the start:
"""This string has "quotes" inside."""
Unescaped newlines are also allowed and retained:
'''This triple-quoted string
continues on the next line.'''
2.5.2. String prefixes¶
String literals can have an optional prefix that influences how the content of the literal is parsed, for example:
b"data"
f'{result=}'
The allowed prefixes are:
r
: Raw stringf
: Formatted string literal (“f-string”)t
: Template string literal (“t-string”)u
: No effect (allowed for backwards compatibility)
See the linked sections for details on each type.
Prefixes are case-insensitive (for example, ‘B
’ works the same as ‘b
’).
The ‘r
’ prefix can be combined with ‘f
’, ‘t
’ or ‘b
’, so ‘fr
’,
‘rf
’, ‘tr
’, ‘rt
’, ‘br
’, and ‘rb
’ are also valid prefixes.
Adicionado 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.
2.5.3. Formal grammar¶
String literals, except “f-strings” and “t-strings”, are described by the following lexical definitions.
These definitions use negative lookaheads (!
)
to indicate that an ending quote ends the literal.
STRING: [stringprefix
] (stringcontent
) stringprefix: <("r" | "u" | "b" | "br" | "rb"), case-insensitive> stringcontent: | "'''" ( !"'''"longstringitem
)* "'''" | '"""' ( !'"""'longstringitem
)* '"""' | "'" ( !"'"stringitem
)* "'" | '"' ( !'"'stringitem
)* '"' stringitem:stringchar
|stringescapeseq
stringchar: <anysource_character
, except backslash and newline> longstringitem:stringitem
| newline stringescapeseq: "\" <anysource_character
>
Note that as in all lexical definitions, whitespace is significant. In particular, the prefix (if any) must be immediately followed by the starting quote.
2.5.4. Sequências de escape¶
Unless an ‘r
’ or ‘R
’ prefix is present, escape sequences in string and
bytes literals are interpreted according to rules similar to those used by
Standard C. The recognized escape sequences are:
Sequência de escape |
Significado |
---|---|
|
|
|
|
|
|
|
|
|
ASCII Bell (BEL) - um sinal audível é emitido |
|
ASCII Backspace (BS) - apaga caractere à esquerda |
|
ASCII Formfeed (FF) - quebra de página |
|
ASCII Linefeed (LF) - quebra de linha |
|
ASCII Carriage Return (CR) - retorno de carro |
|
ASCII Horizontal Tab (TAB) - tabulação horizontal |
|
ASCII Vertical Tab (VT) - tabulação vertical |
|
|
|
|
|
|
|
|
|
2.5.4.1. Ignored end of line¶
Uma contrabarra pode ser adicionada ao fim da linha para ignorar a nova linha:
>>> 'Esta string não vai incluir \
... contrabarras e caracteres de nova linha.'
'Esta string não vai incluir contrabarras e caracteres de nova linha.'
O mesmo resultado pode ser obtido usando strings com aspas triplas, ou parênteses e concatenação de literal string.
2.5.4.2. Escaped characters¶
To include a backslash in a non-raw Python string
literal, it must be doubled. The \\
escape sequence denotes a single
backslash character:
>>> print('C:\\Program Files')
C:\Program Files
Similarly, the \'
and \"
sequences denote the single and double
quote character, respectively:
>>> print('\' and \"')
' and "
2.5.4.3. Octal character¶
The sequence \ooo
denotes a character with the octal (base 8)
value ooo:
>>> '\120'
'P'
Up to three octal digits (0 through 7) are accepted.
In a bytes literal, character means a byte with the given value. In a string literal, it means a Unicode character with the given value.
Alterado na versão 3.11: Octal escapes with value larger than 0o377
(255) produce a
DeprecationWarning
.
Alterado na versão 3.12: Octal escapes with value larger than 0o377
(255) produce a
SyntaxWarning
.
In a future Python version they will raise a SyntaxError
.
2.5.4.4. Hexadecimal character¶
The sequence \xhh
denotes a character with the hex (base 16)
value hh:
>>> '\x50'
'P'
Ao contrário do padrão C, são necessários exatamente dois dígitos hexadecimais.
In a bytes literal, character means a byte with the given value. In a string literal, it means a Unicode character with the given value.
2.5.4.5. Named Unicode character¶
The sequence \N{name}
denotes a Unicode character
with the given name:
>>> '\N{LATIN CAPITAL LETTER P}'
'P'
>>> '\N{SNAKE}'
'🐍'
This sequence cannot appear in bytes literals.
Alterado na versão 3.3: Support for name aliases has been added.
2.5.4.6. Hexadecimal Unicode characters¶
These sequences \uxxxx
and \Uxxxxxxxx
denote the
Unicode character with the given hex (base 16) value.
Exactly four digits are required for \u
; exactly eight digits are
required for \U
.
The latter can encode any Unicode character.
>>> '\u1234'
'ሴ'
>>> '\U0001f40d'
'🐍'
These sequences cannot appear in bytes literals.
2.5.4.7. Unrecognized escape sequences¶
Unlike in Standard C, all unrecognized escape sequences are left in the string unchanged, that is, the backslash is left in the result:
>>> print('\q')
\q
>>> list('\q')
['\\', 'q']
Note that for bytes literals, the escape sequences only recognized in string
literals (\N...
, \u...
, \U...
) fall into the category of
unrecognized escapes.
Alterado na versão 3.6: Sequências de escape não reconhecidas produzem um DeprecationWarning
.
Alterado na versão 3.12: Unrecognized escape sequences produce a SyntaxWarning
.
In a future Python version they will raise a SyntaxError
.
2.5.5. Bytes literals¶
Bytes literals are always prefixed with ‘b
’ or ‘B
’; they produce an
instance of the bytes
type instead of the str
type.
They may only contain ASCII characters; bytes with a numeric value of 128
or greater must be expressed with escape sequences (typically
Hexadecimal character or Octal character):
>>> b'\x89PNG\r\n\x1a\n'
b'\x89PNG\r\n\x1a\n'
>>> list(b'\x89PNG\r\n\x1a\n')
[137, 80, 78, 71, 13, 10, 26, 10]
Similarly, a zero byte must be expressed using an escape sequence (typically
\0
or \x00
).
2.5.6. Raw string literals¶
Both string and bytes literals may optionally be prefixed with a letter ‘r
’
or ‘R
’; such constructs are called raw string literals
and raw bytes literals respectively and treat backslashes as
literal characters.
As a result, in raw string literals, escape sequences
are not treated specially:
>>> r'\d{4}-\d{2}-\d{2}'
'\\d{4}-\\d{2}-\\d{2}'
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.5.7. Literais de strings formatadas¶
Adicionado na versão 3.6.
A formatted string literal or f-string is a string literal
that is prefixed with ‘f
’ or ‘F
’. These strings may contain
replacement fields, which are expressions delimited by curly braces {}
.
While other string literals always have a constant value, formatted strings
are really expressions evaluated at run time.
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 '}'
.
Expressões em literais de strings formatadas são tratadas como expressões regulares do Python entre parênteses, com algumas exceções. Uma expressão vazia não é permitida e as expressões lambda
e de atribuição :=
devem ser colocadas entre parênteses explícitos. Cada expressão é avaliada no contexto onde o literal de string formatada aparece, na ordem da esquerda para a direita. As expressões de substituição podem conter novas linhas em f-strings tanto entre aspas simples quanto em triplas e podem conter comentários. Tudo o que vem depois de um #
dentro de um campo de substituição é um comentário (até mesmo chaves e aspas). Nesse caso, os campos de substituição deverão ser fechados em uma linha diferente.
>>> f"abc{a # Este é um comentário }"
... + 3}"
'abc5'
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 strings formatadas devido a um problema com a implementação.
Alterado na versão 3.12: Antes do Python 3.12, comentários não eram permitidos dentro de campos de substituição em f-strings.
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.
Adicionado 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 strings formatadas podem ser concatenados, mas os campos de substituição não podem ser divididos entre literais.
Alguns exemplos de literais de string formatada:
>>> nome = "Fred"
>>> f"Ele falou que o nome dele é {nome!r}."
"Ele falou que o nome dele é 'Fred'."
>>> f"Ele falou que o nome dele é {repr(nome)}." # repr() é um equivalente a !r
"Ele falou que o nome dele é 'Fred'."
>>> largura = 10
>>> precisão = 4
>>> valor = decimal.Decimal("12.34567")
>>> f"resultado: {valor:{largura}.{precisão}}" # campos aninhados
'resultado: 12.35'
>>> hoje = datetime(year=2017, month=1, day=27)
>>> f"{hoje:%B %d, %Y}" # usando especificador de formato de data
'January 27, 2017'
>>> f"{hoje=:%B %d, %Y}" # usando especificador de formato de data e depuração
'hoje=January 27, 2017'
>>> número = 1024
>>> f"{número:#0x}" # usando especificador de formato de número inteiro
'0x400'
>>> foo = "bar"
>>> f"{ foo = }" # preserva espaço em branco
" foo = 'bar'"
>>> linha = "Olha a caixa d'água"
>>> f"{linha = }"
'linha = "Olha a caixa d\'água"'
>>> f"{linha = :20}"
"linha = Olha a caixa d'água "
>>> f"{linha = !r:20}"
'linha = "Olha a caixa d\'água"'
É permitido reutilizar o tipo de aspas externas da f-string dentro de um campo de substituição:
>>> a = dict(x=2)
>>> f"abc {a["x"]} def"
'abc 2 def'
Alterado na versão 3.12: Antes do Python 3.12, a reutilização do mesmo tipo de aspas externas da f-string dentro de um campo de substituição não era possível.
Contrabarras também são permitidas em campos de substituição e são avaliadas da mesma forma que em qualquer outro contexto:
>>> a = ["a", "b", "c"]
>>> print(f"A lista a contém:\n{"\n".join(a)}")
A lista a contém:
a
b
c
Alterado na versão 3.12: Antes do Python 3.12, contrabarras não eram permitidas dentro de um campo de substituição em uma f-string.
Literais de strings formatadas não podem ser usados como strings de documentação, mesmo que não incluam expressões.
>>> def foo():
... f"Não é uma docstring"
...
>>> foo.__doc__ is None
True
Consulte também PEP 498 para a proposta que adicionou literais de strings formatadas e str.format()
, que usa um mecanismo de string de formato relacionado.
2.5.8. Literais de strings templates (t-strings)¶
Adicionado na versão 3.14.
A template string literal or t-string is a string literal
that is prefixed with ‘t
’ or ‘T
’.
These strings follow the same syntax and evaluation rules as
formatted string literals, with the following differences:
Rather than evaluating to a
str
object, template string literals evaluate to astring.templatelib.Template
object.O protocolo
format()
não é usado. Em vez disso, o especificador de formato e conversões (se houver alguma) são passados para um novo objetoInterpolation
que é criado para cada expressão avaliada. Cabe ao código que processa o objetoTemplate
resultante decidir como tratar especificadores de formato e conversões.Format specifiers containing nested replacement fields are evaluated eagerly, prior to being passed to the
Interpolation
object. For instance, an interpolation of the form{amount:.{precision}f}
will evaluate the inner expression{precision}
to determine the value of theformat_spec
attribute. Ifprecision
were to be2
, the resulting format specifier would be'.2f'
.When the equals sign
'='
is provided in an interpolation expression, the text of the expression is appended to the literal string that precedes the relevant interpolation. This includes the equals sign and any surrounding whitespace. TheInterpolation
instance for the expression will be created as normal, except thatconversion
will be set to ‘r
’ (repr()
) by default. If an explicit conversion or format specifier are provided, this will override the default behaviour.
2.6. Literais numéricos¶
Tokens NUMBER
representam literais numéricos, dos quais existem três tipos: inteiros, números de ponto flutuante e números imaginários.
NUMBER:integer
|floatnumber
|imagnumber
O valor numérico de um literal numérico é o mesmo que seria se fosse passado como uma string para os construtores de classe int
, float
ou complex
, respectivamente. Observe que nem todas as entradas válidas para esses construtores também são literais válidos.
Literais numéricos não incluem um sinal; uma frase como -1
é, na verdade, uma expressão composta pelo operador unário ‘-
’ e o literal 1
.
2.6.1. Inteiros literais¶
Literais inteiros denotam números inteiros. Por exemplo:
7
3
2147483647
Não há limite para o comprimento de literais inteiros, exceto o que pode ser armazenado na memória disponível:
7922816251426433759354395033679228162514264337593543950336
Sublinhados podem ser usados para agrupar dígitos para melhor legibilidade e são ignorados para determinar o valor numérico do literal. Por exemplo, os seguintes literais são equivalentes:
100_000_000_000
100000000000
1_00_00_00_00_000
Sublinhados só podem ocorrer entre dígitos. Por exemplo, _123
, 321_
e 123__321
não são literais válidos.
Os números inteiros podem ser especificados em binário (base 2), octal (base 8) ou hexadecimal (base 16) usando os prefixos 0b
, 0o
e 0x
, respectivamente. Os dígitos hexadecimais de 10 a 15 são representados pelas letras A
-F
, sem distinção entre maiúsculas e minúsculas. Por exemplo:
0b100110111
0b_1110_0101
0o177
0o377
0xdeadbeef
0xDead_Beef
Um sublinhado pode seguir o especificador base. Por exemplo, 0x_1f
é um literal válido, mas 0_x1f
e 0x__1f
não são.
Zeros à esquerda em um número decimal diferente de zero não são permitidos. Por exemplo, 0123
não é um literal válido. Isso serve para desambiguação com literais octais no estilo C, que o Python usava antes da versão 3.0.
Formalmente, literais inteiros são descritos pelas seguintes definições lexicais:
integer:decinteger
|bininteger
|octinteger
|hexinteger
|zerointeger
decinteger:nonzerodigit
(["_"]digit
)* bininteger: "0" ("b" | "B") (["_"]bindigit
)+ octinteger: "0" ("o" | "O") (["_"]octdigit
)+ hexinteger: "0" ("x" | "X") (["_"]hexdigit
)+ zerointeger: "0"+ (["_"] "0")* nonzerodigit: "1"..."9" digit: "0"..."9" bindigit: "0" | "1" octdigit: "0"..."7" hexdigit:digit
| "a"..."f" | "A"..."F"
Alterado na versão 3.6: Os sublinhados agora são permitidos para fins de agrupamento de literais.
2.6.2. Literais de ponto flutuante¶
Literais de ponto flutuante (float), como 3.14
ou 1.5
, denotam aproximações de números reais.
Eles consistem em partes inteiras e fracionárias, cada uma composta por dígitos decimais. As partes são separadas por um ponto decimal, .
:
2.71828
4.0
Ao contrário dos literais inteiros, zeros à esquerda são permitidos nas partes numéricas. Por exemplo, 077.010
é válido e denota o mesmo número que 77.10
.
Assim como em literais inteiros, sublinhados simples podem ocorrer entre dígitos para ajudar na legibilidade:
96_485.332_123
3.14_15_93
Qualquer uma dessas partes, mas não ambas, pode estar vazia. Por exemplo:
10. # (equivalente a 10.0)
.001 # (equivalente a 0.001)
Opcionalmente, o inteiro e a fração podem ser seguidos por um expoente: a letra e
ou E
, seguida por um sinal opcional, +
ou -
, e um número no mesmo formato das partes inteira e fracionária. O e
ou E
representa “dez vezes elevado à potência de”:
1.0e3 # (representa 1.0×10³ ou 1000.0)
1.166e-5 # (representa 1.166×10⁻⁵ ou 0.00001166)
6.02214076e+23 # (representa 6.02214076×10²³ ou 602214076000000000000000.)
Em floats com apenas partes inteiras e expoentes, o ponto decimal pode ser omitido:
1e3 # (equivalente a 1.e3 e 1.0e3)
0e0 # (equivalente a 0.)
Formalmente, literais de ponto flutuante são descritos pelas seguintes definições léxicas:
floatnumber: |digitpart
"." [digitpart
] [exponent
] | "."digitpart
[exponent
] |digitpart
exponent
digitpart:digit
(["_"]digit
)* exponent: ("e" | "E") ["+" | "-"]digitpart
Alterado na versão 3.6: Os sublinhados agora são permitidos para fins de agrupamento de literais.
2.6.3. Literais imaginários¶
Python possui objetos número complexo, mas não possui literais complexos. Em vez disso, literais imaginários denotam números complexos com parte real zero.
Por exemplo, na matemática, o número complexo 3+4.2i é escrito como o número real 3 somado ao número imaginário 4.2i. Python usa uma sintaxe semelhante, exceto que a unidade imaginária é escrita como j
em vez de i:
3+4.2j
Esta é uma expressão composta pelo literal inteiro 3
, o operador ‘+
’ e o literal imaginário 4.2j
. Como esses são três tokens separados, espaços em branco são permitidos entre eles:
3 + 4.2j
Nenhum espaço em branco é permitido dentro de cada token. Em particular, o sufixo j
não pode ser separado do número que o precede.
O número antes do j
tem a mesma sintaxe de um literal de ponto flutuante. Portanto, os seguintes são literais imaginários válidos:
4.2j
3.14j
10.j
.001j
1e100j
3.14e-10j
3.14_15_93j
Ao contrário de um literal de ponto flutuante, o ponto decimal pode ser omitido se o número imaginário tiver apenas uma parte inteira. O número ainda é avaliado como um número de ponto flutuante, não um inteiro.
10j
0j
1000000000000000000000000j # equivalente a 1e+24j
O sufixo j
não diferencia maiúsculas de minúsculas. Isso significa que você pode usar J
em vez disso:
3.14J # equivalente a 3.14j
Formalmente, literais imaginários são descritos pela seguinte definição léxica:
imagnumber: (floatnumber
|digitpart
) ("j" | "J")
2.7. Operators and delimiters¶
The following grammar defines operator and delimiter tokens,
that is, the generic OP
token type.
A list of these tokens and their names
is also available in the token
module documentation.
OP: | assignment_operator | bitwise_operator | comparison_operator | enclosing_delimiter | other_delimiter | arithmetic_operator | "..." | other_op assignment_operator: "+=" | "-=" | "*=" | "**=" | "/=" | "//=" | "%=" | "&=" | "|=" | "^=" | "<<=" | ">>=" | "@=" | ":=" bitwise_operator: "&" | "|" | "^" | "~" | "<<" | ">>" comparison_operator: "<=" | ">=" | "<" | ">" | "==" | "!=" enclosing_delimiter: "(" | ")" | "[" | "]" | "{" | "}" other_delimiter: "," | ":" | "!" | ";" | "=" | "->" arithmetic_operator: "+" | "-" | "**" | "*" | "//" | "/" | "%" other_op: "." | "@"
Nota
Generally, operators are used to combine expressions, while delimiters serve other purposes. However, there is no clear, formal distinction between the two categories.
Some tokens can serve as either operators or delimiters, depending on usage.
For example, *
is both the multiplication operator and a delimiter used
for sequence unpacking, and @
is both the matrix multiplication and
a delimiter that introduces decorators.
For some tokens, the distinction is unclear.
For example, some people consider .
, (
, and )
to be delimiters, while others
see the getattr()
operator and the function call operator(s).
Some of Python’s operators, like and
, or
, and not in
, use
keyword tokens rather than “symbols” (operator tokens).
A sequence of three consecutive periods (...
) has a special
meaning as an Ellipsis
literal.
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.