Python f-Strings

Os f-strings (literais de string formatados) foram introduzidos no Python 3.6 e são agora a forma recomendada de incorporar valores dentro de strings. Eles são mais rápidos do que a formatação com % e str.format(), e muito mais legíveis, pois o nome da variável fica diretamente dentro da string onde será exibido.

Este capítulo abrange:

• Sintaxe básica de f-string e como incorporar variáveis
• Avaliação de expressões, chamadas de método e chamadas de função inline
• Especificadores de formato: alinhamento, largura, precisão e bases numéricas
• Formatação de datas e uso dos especificadores de sinal e preenchimento com zeros
• O especificador de depuração = (Python 3.8+)
• f-strings multilinha e templates reutilizáveis em funções
• Armadilhas comuns e como evitá-las

Capítulos relacionados: Format Strings · Python String Formatting · Python Strings · Python Dates · Python Regex

Sintaxe Básica

Um f-string é qualquer literal de string que começa com a letra f (ou F) imediatamente antes da aspas de abertura. Qualquer expressão Python colocada dentro de chaves {} é avaliada em tempo de execução, e seu valor é convertido para uma string e inserido no resultado.

name = "Alice"
age = 30
print(f"My name is {name} and I am {age} years old.")

My name is Alice and I am 30 years old.

O prefixo f funciona com aspas simples, aspas duplas e aspas triplas:

language = "Python"
print(f'I love {language}!')          # single quotes
print(f"""I love {language}!""")      # triple quotes

I love Python!
I love Python!

Incorporando Expressões

O espaço reservado {} aceita qualquer expressão Python válida — não apenas nomes de variáveis. Você pode fazer operações aritméticas, comparações, chamar métodos, chamar funções e acessar chaves de dicionário.

Aritmética e comparações

x = 10
y = 3
print(f"{x} divided by {y} is {x / y:.2f}")
print(f"The square of {x} is {x ** 2}")
print(f"Is {x} greater than {y}? {x > y}")

10 divided by 3 is 3.33
The square of 10 is 100
Is 10 greater than 3? True

Chamadas de método

name = "alice smith"
print(f"Hello, {name.title()}!")
print(f"Uppercase: {name.upper()}")

Hello, Alice Smith!
Uppercase: ALICE SMITH

Chamadas de função e funções integradas

items = ["apples", "bananas", "cherries"]
print(f"You have {len(items)} items in the list.")

You have 3 items in the list.

Acesso a dicionário

Use aspas simples dentro das chaves para acessar chaves de dicionário (a string externa usa aspas duplas, então não há conflito):

person = {"name": "Bob", "age": 25}
print(f"Name: {person['name']}, Age: {person['age']}")

Name: Bob, Age: 25

Expressões condicionais

score = 72
print(f"Score: {score} => {'Pass' if score >= 60 else 'Fail'}")

Score: 72 => Pass

Especificadores de Formato

Após a expressão, adicione dois pontos : seguidos de uma especificação de formato para controlar como o valor é exibido. A sintaxe completa da mini-linguagem é:

{expression:[fill][align][sign][width][grouping][.precision][type]}

Você não precisa usar todas as partes — combine apenas as que precisar.

Alinhamento e largura

Use < (esquerda), > (direita) ou ^ (centro) com um número para definir a largura do campo:

name = "Alice"
print(f"|{name:<10}|")   # left-align in a field of width 10
print(f"|{name:>10}|")   # right-align
print(f"|{name:^10}|")   # center

|Alice     |
|     Alice|
|  Alice   |

Especifique um caractere de preenchimento antes do símbolo de alinhamento para preencher com algo diferente de espaços:

print(f"|{'hello':*^15}|")  # fill with * and center

|*****hello*****|

Precisão decimal

pi = 3.14159265
print(f"Pi is approximately {pi:.2f}")   # 2 decimal places
print(f"Pi is approximately {pi:.4f}")   # 4 decimal places

Pi is approximately 3.14
Pi is approximately 3.1416

Formatação de números

price = 1234567.89
print(f"{price:,.2f}")   # comma as thousands separator
print(f"{price:e}")      # scientific notation

1,234,567.89
1.234568e+06

Exiba um valor como porcentagem diretamente — o Python multiplica por 100 automaticamente:

ratio = 0.853
print(f"{ratio:.1%}")

85.3%

Especificador de sinal

Use + para sempre exibir o sinal, ou um espaço para reservar um espaço para números positivos (para que as colunas fiquem alinhadas com os negativos):

x = 42
y = -7
print(f"{x:+d}")    # +42
print(f"{y:+d}")    # -7
print(f"{x: d}")    # space before positive
print(f"{y: d}")    # -7

+42
-7
 42
-7

Preenchimento com zeros

Preencha um inteiro com uma largura fixa usando zeros à esquerda com 0 antes do número de largura:

print(f"{42:010d}")   # zero-pad to 10 digits

0000000042

Combine sinal e preenchimento com zeros — o sinal ocupa a primeira posição:

x = 42
print(f"{x:+010d}")   # +000000042

+000000042

Bases inteiras

x = 255
print(f"{x:d}")    # decimal   -> 255
print(f"{x:x}")    # hex lower -> ff
print(f"{x:X}")    # hex upper -> FF
print(f"{x:o}")    # octal     -> 377
print(f"{x:b}")    # binary    -> 11111111

255
ff
FF
377
11111111

Formatação de Datas

Ao colocar um objeto datetime ou date dentro de um f-string, você pode usar os códigos de formato strftime após os dois pontos para controlar a saída diretamente — sem necessidade de chamar .strftime():

from datetime import date
today = date(2024, 6, 19)
print(f"Today is {today:%B %d, %Y}")
print(f"ISO format: {today:%Y-%m-%d}")

Today is June 19, 2024
ISO format: 2024-06-19

Consulte o capítulo Python Dates para a lista completa de códigos de formato strftime.

O Especificador de Depuração = (Python 3.8+)

Adicionar = após o nome da expressão imprime tanto o texto da expressão quanto seu valor. Isso evita que você precise digitar o nome da variável duas vezes e é muito útil para depuração rápida:

val = 42
result = val * 2
print(f"{val=}, {result=}")

val=42, result=84

Valores string recebem tratamento de repr() para que você possa ver as aspas:

name = "Alice"
print(f"{name=}")

name='Alice'

Você pode combinar = com um especificador de formato — coloque o especificador após =:

pi = 3.14159265
print(f"{pi=:.3f}")

pi=3.142

f-Strings Multilinha

Para textos mais longos, você pode estender um f-string por várias linhas. Duas abordagens funcionam bem.

Concatenação implícita de strings (sem necessidade de barra invertida dentro de parênteses):

name = "Alice"
age = 30
city = "London"
profile = (
    f"Name : {name}\n"
    f"Age  : {age}\n"
    f"City : {city}"
)
print(profile)

Name : Alice
Age  : 30
City : London

f-string com aspas triplas — as quebras de linha são literais, então \n não é necessário:

name = "Alice"
age = 30
report = f"""
Name : {name}
Age  : {age}
""".strip()
print(report)

Name : Alice
Age  : 30

Templates Reutilizáveis

Os f-strings são avaliados imediatamente, portanto você não pode armazená-los como uma variável de template e preenchê-los depois. Use uma função em vez disso:

def greet(name, role):
    return f"Hello, {name}! Your role is {role}."

print(greet("Alice", "admin"))
print(greet("Bob", "editor"))

Hello, Alice! Your role is admin.
Hello, Bob! Your role is editor.

Se você realmente precisar de um template adiado, use str.format() — consulte Format Strings.

Chaves Literais na Saída

Para incluir um caractere { ou } literal na saída, duplique-o:

value = 42
print(f"The answer is {{value}} = {value}")

The answer is {value} = 42

Armadilhas Comuns

Barras invertidas dentro da expressão (Python < 3.12)

Antes do Python 3.12, uma barra invertida não é permitida dentro da expressão {} de um f-string. A solução alternativa é calcular o valor em uma variável primeiro:

items = ["a", "b", "c"]

# This raises SyntaxError on Python < 3.12:
# print(f"{'\n'.join(items)}")

# Workaround — pre-compute:
joined = "\n".join(items)
print(f"Items:\n{joined}")

Items:
a
b
c

O Python 3.12 removeu essa restrição, portanto barras invertidas agora são válidas dentro de expressões f-string.

Usar o mesmo tipo de aspas dentro da expressão

Se o f-string externo usa aspas duplas, use aspas simples para chaves de dicionário dentro de {}. Se você precisar do mesmo tipo de aspas, mude as aspas externas ou use uma variável:

person = {"name": "Bob"}

# Works — single quotes inside double-quoted f-string
print(f"Name: {person['name']}")

# Also works — pre-assign the key
key = "name"
print(f"Name: {person[key]}")

Name: Bob
Name: Bob

f-strings não são preguiçosos

Um f-string avalia todas as expressões no momento em que a linha é executada. Se você atribuir um f-string a uma variável, ele captura os valores atuais — alterar as variáveis depois não tem efeito sobre a string já avaliada:

x = 5
msg = f"x is {x}"
x = 99
print(msg)   # still shows 5, not 99

x is 5

Use uma função (como mostrado acima) quando precisar de um template que seja avaliado posteriormente.

Referência Rápida

Prática