Python / str() / Converter um objeto em uma string

str() do Python retorna uma representação legível de um objeto como string. Use-a para combinar números e texto ou guardar uma representação textual, sem alterar o tipo do objeto original. Decodificar bytes ou gerar JSON exige operações próprias para esses objetivos.

Conversão básica e tipo retornado

str(object) retorna um objeto str, por exemplo a partir de números e booleanos. Sem argumento, str() cria uma string vazia. Normalmente usa a representação __str__(), que uma classe personalizada pode definir. Consulte a referência oficial do tipo str.

Os exemplos precisam apenas de Python 3 e da biblioteca padrão. Salve o programa completo em UTF-8 como str_example.py e execute python str_example.py no terminal. Alguns ambientes usam python3. Os exemplos seguintes também são independentes: substitua o conteúdo do mesmo arquivo e execute novamente.

number = 42
text = str(number)
print(number, type(number).__name__)
print(text, type(text).__name__)
print("ID-" + text)
print(repr(str()))
print(str(None))

Saída esperada:

42 int
42 str
ID-42
''
None

Os dois valores aparecem como 42, mas seus tipos diferem. number continua inteiro; text é string. O '' mostrado com repr() tem comprimento zero. str(None) produz o texto None, não um valor vazio.

Conversão difere de formatação numérica

str() produz a representação básica de um número, sem definir casas decimais ou moeda. Para uma regra específica de exibição, utilize uma string formatada, como uma f-string.

price = 12.5
print(str(price))
print(f"{price:.2f}")
print("price=" + str(price))

12.5
12.50
price=12.5

12.50 é uma string exibida com duas casas decimais. O número original price permanece inalterado. Arredondamento de exibição e precisão de cálculo são questões separadas.

Decodificar bytes para obter texto

bytes armazena dados em bytes, enquanto str armazena texto Unicode. Apenas str(raw) fornece a representação do objeto bytes. Para recuperar os caracteres, informe a codificação real com decode() ou str(raw, encoding).

raw = "café".encode("utf-8")
print(str(raw))
print(raw.decode("utf-8"))
print(str(raw, "utf-8"))

b'caf\xc3\xa9'
café
café

O prefixo b e os escapes da primeira linha representam bytes. Somente as duas próximas linhas os decodificam como UTF-8. Se o arquivo ou a resposta foi codificado de outro modo, use essa codificação. Definir errors="ignore" só para ocultar erros pode descartar dados.

Escolher entre str(), repr() e JSON

str() é voltado à exibição legível; repr() ajuda a inspecionar uma representação durante o desenvolvimento. Mesmo repr() não garante código reconstruível para todo objeto. Para intercâmbio de dados use json.dumps(), que gera JSON, JavaScript Object Notation, um formato de texto padronizado.

import json

data = {"active": True, "count": 0}
print(str(data))
print(json.dumps(data))
print(str("hello\nworld"))
print(repr("hello\nworld"))

{'active': True, 'count': 0}
{"active": true, "count": 0}
hello
world
'hello\nworld'

O str() do dicionário usa aspas de Python e True, portanto não é automaticamente JSON. Uma quebra de linha é exibida de fato com str(); repr() mostra um escape como \n.

Transformar apenas None em texto vazio

Use is None se somente o valor ausente None deve virar vazio. str(value or "") também esvazia 0 e False, podendo perder seu significado.

for value in (None, 0, False):
    text = "" if value is None else str(value)
    print(repr(text))

''
'0'
'False'

Tratar erros de concatenação e decodificação

Um + direto entre string e número causa TypeError. Converta o número com str() ou use uma f-string. Bytes incompatíveis com a codificação escolhida causam UnicodeDecodeError: confira a codificação original e se os dados estão completos.

try:
    print("ID-" + 42)
except TypeError:
    print("TypeError")

try:
    str(b"\xff", "utf-8")
except UnicodeDecodeError:
    print("UnicodeDecodeError")

TypeError
UnicodeDecodeError

O último exemplo captura exceções para exibir seus tipos. A conversão também pode falhar se um __str__() personalizado retornar um tipo errado ou gerar uma exceção internamente. Nem toda falha decorre da concatenação.