Módulo locale em Python

Por padrão, ao formatar números, o Python utiliza o sistema de notação numérica americano, onde os milhares são separados por vírgulas e a parte decimal é separada por um ponto. No entanto, em países da Europa continental e no Brasil, é utilizada uma convenção diferente: os milhares são separados por pontos, e a parte decimal é separada por vírgulas.

Exemplo:

# sistema americano
1,234.567

# sistema europeu e brasileiro
1.234,567

Para configurar a formatação de acordo com a convenção local, podemos utilizar o módulo integrado locale.

Função setlocale()

A função setlocale() do módulo locale permite definir a configuração regional para formatação. Ela aceita dois parâmetros:

setlocale(category, locale)

• category: define a categoria de aplicação da função, como números, moedas, ou ambos. As constantes principais são:

  • LC_ALL: aplica a localização a todas as categorias (números, moedas, datas, etc).
  • LC_NUMERIC: aplica a localização apenas a números.
  • LC_MONETARY: aplica a localização a valores monetários.
  • LC_TIME: aplica a localização a datas e horários.
  • LC_CTYPE: aplica a localização na conversão de caracteres para maiúsculas ou minúsculas.
  • LC_COLLATE: aplica a localização na comparação de strings.

• locale: especifica o código de idioma e região. Por exemplo, para o Brasil, utilizamos "pt_BR" no Windows e "pt_BR.UTF-8" no Linux e macOS.

  No Linux e macOs, é possível listar os códigos de idioma e região disponíveis no sistema executando o comando locale -a no terminal.

  No Windows, a lista de códigos de idioma e região está disponível na documentação oficial da Microsoft.

Funções para formatação de números e moedas

Para formatar números e valores monetários, o módulo locale oferece as funções:

• format(): formata um número de acordo com a configuração regional.
• currency(): formata um valor monetário.

• format_string(str, num): insere um número num no espaço reservado em uma string str. Espaços Reservados:

  • %d: número inteiro.
  • %f: número de ponto flutuante.
  • %s: string.

  Para números decimais, é possível definir a quantidade de casas após a vírgula:

  content_copyopen_in_new

  "%.2f"  # duas casas decimais

No exemplo abaixo, aplicamos a localização brasileira para números e valores monetários:

import locale

# Para Windows
locale.setlocale(locale.LC_ALL, "pt_BR")
# Para Linux e macOS
# locale.setlocale(locale.LC_ALL, "pt_BR.UTF-8")

number = 12345.6789
formatted = locale.format_string("%f", number)
print(formatted)   # 12345,678900

formatted = locale.format_string("%.2f", number)
print(formatted)    # 12345,68

formatted = locale.format_string("%d", number)
print(formatted)    # 12345

formatted = locale.format_string("%e", number)
print(formatted)    #  1,234568e+04

money = 234.678
formatted = locale.currency(money)
print(formatted)    #  R$ 234,68

Se o segundo parâmetro de setlocale() for uma string vazia, o Python utilizará a configuração regional da máquina. É possível verificar essa configuração com a função getlocale():

import locale

locale.setlocale(locale.LC_ALL, "")

number = 12345.6789
formatted = locale.format_string("%.02f", number)
print(formatted)    # 12345,68
print(locale.getlocale())
# Saída possível em Windows: ('pt_BR', 'cp1252')
# Saída possível em  Linux e macOS: ('pt_BR', 'UTF-8')

Os resultados da formatação podem variar conforme o sistema operacional e a configuração regional da máquina.

Documentação oficial

• Módulo locale