Formatação de Strings em Python

A formatação de strings permite construir strings dinamicamente inserindo variáveis, expressões e valores calculados em um modelo. Python oferece três abordagens distintas — o operador % legado, o versátil método str.format() e a sintaxe moderna de f-strings — cada uma com seus próprios pontos fortes e casos de uso apropriados.

Este capítulo aborda:

• Quando usar cada método de formatação e por quê
• O operador % (legado, ainda comum em logs e bases de código antigas)
• str.format() com marcadores posicionais e nomeados
• f-strings (a abordagem moderna recomendada)
• Especificadores de formato: largura, alinhamento, precisão, preenchimento, sinal e base
• Formatação de números, percentuais, datas e horas
• Armadilhas comuns e casos extremos

Para um mergulho profundo especificamente em f-strings — incluindo expressões, lógica condicional e melhorias do Python 3.12 — consulte o capítulo Python f-Strings.

Qual Método Você Deve Usar?

A menos que você esteja mantendo código Python 2 ou uma base de código Python 3 mais antiga, use f-strings. Elas são avaliadas em tempo de execução, não produzem overhead de chamada extra e mantêm o nome da variável próximo ao local onde ela aparece na string.

O Operador % (Formatação Legada)

O operador % substitui valores em uma string de formato usando especificadores de conversão no estilo C.

Especificadores de conversão comuns:

Largura e Precisão com %

Você pode controlar a largura do campo e a precisão decimal diretamente no especificador:

pi = 3.14159265
print("%10.3f" % pi)   # right-aligned in a 10-char field, 3 decimal places
#      3.142
print("%-10.3f|" % pi) # left-aligned
# 3.142     |
print("%010.3f" % pi)  # zero-padded
# 000003.142

Armadilha: Valores Únicos vs. Tuplas

Ao substituir um único valor, passar uma tupla é a abordagem segura:

value = "hello"
# Risky — if value were itself a tuple, this would fail:
# print("Got: %s" % value)

# Safe:
print("Got: %s" % (value,))
# Got: hello

str.format() — Formatação Flexível com Marcadores

O método str.format() substituiu o operador % no Python 2.6+. Ele usa {} como marcadores e suporta argumentos posicionais, indexados e nomeados.

Marcadores Posicionais e Indexados

Marcadores Nomeados (por Palavra-chave)

Marcadores nomeados tornam as strings de formato autodocumentadas e são especialmente úteis quando o mesmo valor aparece várias vezes ou quando a string de formato vem de um arquivo de configuração.

Reutilizando Strings de Formato

Como str.format() recebe uma string como entrada, você pode armazenar o modelo em uma variável e reutilizá-lo:

template = "Hello, {name}! You have {count} new messages."
print(template.format(name="Alice", count=3))
print(template.format(name="Bob", count=0))
# Hello, Alice! You have 3 new messages.
# Hello, Bob! You have 0 new messages.

f-Strings — Formatação Moderna em Python

As f-strings (literais de string formatados) prefixam a string com f ou F e avaliam qualquer expressão dentro de {} em tempo de execução. Elas estão disponíveis a partir do Python 3.6 e são a abordagem recomendada para código novo.

name = "John"
age = 25
print(f"My name is {name} and I am {age} years old.")
# My name is John and I am 25 years old.

As f-strings suportam qualquer expressão Python válida dentro das chaves — aritmética, chamadas de método, condicionais e muito mais:

items = ["apple", "banana", "cherry"]
print(f"Cart has {len(items)} items. First: {items[0].upper()}.")
# Cart has 3 items. First: APPLE.

x = -7
print(f"Absolute value: {abs(x)}")
# Absolute value: 7

Consulte Python f-Strings para o guia completo, incluindo depuração com =, f-strings multilinha e melhorias do Python 3.12.

Especificadores de Formato: A Mini-Linguagem

Tanto str.format() quanto f-strings usam a mesma mini-linguagem de especificação de formato dentro de {} após um dois-pontos:

{[field_name]:[fill][align][sign][#][0][width][grouping][.precision][type]}

A tabela abaixo mostra as opções mais úteis:

Alinhamento e Largura

text = "hello"
print(f"{text:<10}|")   # left-aligned in 10-char field
# hello     |
print(f"{text:>10}|")   # right-aligned
#      hello|
print(f"{text:^10}|")   # centered
#   hello   |
print(f"{text:*^10}|")  # centered, filled with *
# **hello***|

Os mesmos especificadores de alinhamento funcionam com str.format(). Aqui está um exemplo combinando alinhamento e precisão:

Formatação de Números

x = 123.456789

print(f"{x:.2f}")        # two decimal places
# 123.46

print(f"{x:,.2f}")       # thousands separator, two decimal places
# 123.46

print(f"{x:+.2f}")       # explicit plus sign for positive numbers
# +123.46

print(f"{x:10.2f}")      # right-aligned in a 10-char field
#     123.46

print(f"{x:<10.2f}|")    # left-aligned
# 123.46    |

print(f"{x:010.2f}")     # zero-padded to 10 characters
# 0000123.46

Números Grandes e Percentuais

population = 8_100_000_000
print(f"{population:,}")    # comma separator
# 8,100,000,000

print(f"{population:_}")    # underscore separator (Python 3.6+)
# 8_100_000_000

ratio = 0.8567
print(f"{ratio:.1%}")       # percentage, one decimal place
# 85.7%

Bases de Inteiros

n = 255
print(f"{n:d}")   # decimal (default)
# 255
print(f"{n:x}")   # lowercase hexadecimal
# ff
print(f"{n:X}")   # uppercase hexadecimal
# FF
print(f"{n:#x}")  # hex with 0x prefix
# 0xff
print(f"{n:o}")   # octal
# 377
print(f"{n:b}")   # binary
# 11111111
print(f"{n:#b}")  # binary with 0b prefix
# 0b11111111

Você também pode usar os mesmos especificadores com str.format():

Notação Científica

avogadro = 6.02214076e23
print(f"{avogadro:.3e}")   # scientific notation, 3 decimal places
# 6.022e+23

print(f"{avogadro:.3E}")   # uppercase E
# 6.022E+23

print(f"{avogadro:.3g}")   # general: compact form, removes trailing zeros
# 6.02e+23

Formatando Strings com format() e f-Strings

As três abordagens produzem a mesma saída para uma substituição simples:

Especificadores específicos para strings permitem controlar truncamento e preenchimento:

s = "Python"
print(f"{s:.3}")      # truncate to 3 characters
# Pyt

print(f"{s:10}")      # pad to width 10 (left-aligned by default for strings)
# Python    

print(f"{s:>10}")     # right-aligned
#     Python

print(f"{s:*^12}")    # centered, filled with *
# ***Python***

Formatando Datas e Horas

Use os códigos de formato strftime dentro das chaves ao formatar objetos datetime com f-strings ou str.format():

import datetime

date = datetime.datetime(2024, 3, 15, 10, 30, 0)

# Default string representation
print(f"Default: {date}")
# Default: 2024-03-15 10:30:00

# strftime codes inside the format spec
print(f"Formatted: {date:%B %d, %Y}")
# Formatted: March 15, 2024

print(f"Time only: {date:%H:%M:%S}")
# Time only: 10:30:00

print(f"ISO-style: {date:%Y-%m-%d}")
# ISO-style: 2024-03-15

A mesma sintaxe funciona com str.format():

import datetime
date = datetime.datetime(2024, 3, 15, 10, 30, 0)
print("The date is {:%B %d, %Y}".format(date))
# The date is March 15, 2024

Para formatação avançada de datas, consulte o capítulo Python Modify Strings que aborda técnicas de manipulação de strings.

Técnicas Avançadas

Expressões Aninhadas em f-Strings

As f-strings permitem calcular o especificador de formato dinamicamente:

width = 10
precision = 3
value = 3.14159

print(f"{value:{width}.{precision}f}")
# output:      3.142  (right-aligned in a 10-char field, 3 decimal places)

Especificador de Formato com format() e Variáveis

A mesma técnica funciona com str.format() usando {} aninhado:

width = 8
print("{:{width}}".format("left", width=width))
# left    

Formatação Condicional em f-Strings

Como as f-strings avaliam qualquer expressão, você pode usar expressões condicionais inline:

score = 73
label = f"{'pass' if score >= 60 else 'fail'}"
print(f"Score {score}: {label}")
# Score 73: pass

Depuração com = (Python 3.8+)

Acrescente = dentro de uma f-string para imprimir tanto a expressão quanto seu valor — muito útil para depuração:

x = 42
y = x * 2
print(f"{x=}, {y=}")
# x=42, y=84

Armadilhas Comuns

1. Escape de chaves. Para incluir um { ou } literal em qualquer string formatada, duplique-o:

print(f"Use {{curly braces}} in f-strings")
# Use {curly braces} in f-strings

2. Aspas dentro de f-strings. No Python 3.11 e anteriores, a expressão dentro de {} não pode usar o mesmo tipo de aspas que a f-string externa:

names = ["Alice", "Bob"]
# Wrong in Python <= 3.11:
# print(f"First: {names[0].upper()}")  -- this is fine
# print(f"{'Alice'.upper()}")          -- single quotes inside double-quoted f-string is fine
# But nesting the same quotes fails:
# print(f"{names["Alice"]}")           -- SyntaxError in <= 3.11

# Safe approach for <= 3.11:
key = "Alice"
print(f"{key.upper()}")
# ALICE

3. A armadilha da tupla com %. Ao usar formatação com % e um único valor que é ele próprio uma tupla, envolva-o:

coords = (10, 20)
# This raises TypeError because % sees a 2-element tuple:
# print("Position: %s" % coords)

# Fix: wrap in a 1-element tuple
print("Position: %s" % (coords,))
# Position: (10, 20)

4. str.format() vs. segurança. Nunca passe entrada de usuário não confiável como uma string de formato para str.format() — um modelo malicioso pode acessar atributos de objetos e vazar dados. As f-strings são sempre strings codificadas no programa, portanto não são vulneráveis a isso.

Comparação Prática

Aqui está a mesma saída produzida pelos três métodos lado a lado:

item = "widget"
qty = 42
unit_price = 4.5

# % operator
print("%-12s %4d  $%7.2f" % (item, qty, unit_price))

# str.format()
print("{:<12} {:>4}  ${:>7.2f}".format(item, qty, unit_price))

# f-string
print(f"{item:<12} {qty:>4}  ${unit_price:>7.2f}")

# All print:
# widget         42  $   4.50

Resumo

• Use f-strings para código Python 3.6+ novo: são as mais legíveis e rápidas.
• Use str.format() quando precisar de uma string de modelo reutilizável ou precisar suportar Python 2.6+.
• Use % apenas em código legado ou ao trabalhar com o módulo logging (que adia a formatação até que a entrada de log seja realmente emitida).
• A mini-linguagem de especificação de formato (width, precision, align, fill, type) se aplica da mesma forma tanto ao str.format() quanto às f-strings.

Capítulos relacionados:

• Python f-Strings — mergulho profundo em expressões f-string e recursos do Python 3.12
• Python Strings — fundamentos de strings, indexação e fatiamento
• Modify Strings — métodos de string integrados
• Escape Characters — caracteres especiais em strings

Prática