"string" --- Operações comuns de strings
****************************************

**Código-fonte:** Lib/string/__init__.py

======================================================================

Ver também:

  Tipo sequência de texto --- str

  Métodos de string


Constantes de strings
=====================

As constantes definidas neste módulo são:

string.ascii_letters

   A concatenação das constantes "ascii_lowercase" e "ascii_uppercase"
   descritas abaixo. Este valor não depende da localidade.

string.ascii_lowercase

   As letras minúsculas "'abcdefghijklmnopqrstuvwxyz'". Este valor não
   depende da localidade e não mudará.

string.ascii_uppercase

   As letras maiúsculas "'ABCDEFGHIJKLMNOPQRSTUVWXYZ'". Este valor não
   depende da localidade e não mudará.

string.digits

   A string "'0123456789'".

string.hexdigits

   A string "'0123456789abcdefABCDEF'".

string.octdigits

   A string "'01234567'".

string.punctuation

   String de caracteres ASCII que são considerados caracteres de
   pontuação na localidade "C": "!"#$%&'()*+,-./:;<=>?@[\]^_`{|}~".

string.printable

   String de caracteres ASCII que são considerados imprimíveis pelo
   Python. Esta é uma combinação de "digits", "ascii_letters",
   "punctuation" e "whitespace".

   Nota:

     Por design, "string.printable.isprintable()" retorna "False". Em
     particular, "string.printable" não é imprimível no sentido POSIX
     (veja *LC_CTYPE*).

string.whitespace

   Uma string contendo todos os caracteres ASCII que são considerados
   espaços em branco. Isso inclui espaço de caracteres, tabulação,
   avanço de linha, retorno, avanço de formulário e tabulação
   vertical.


Formatação personalizada de strings
===================================

A classe embutida de string fornece a capacidade de substituir
variáveis complexas e de formatar valores por meio do método
"format()" descrito na **PEP 3101**. A classe "Formatter" no módulo
"string" permite que você crie e personalize seus próprios
comportamentos de formatação de strings, usando a mesma implementação
do método embutido "format()".

class string.Formatter

   A classe "Formatter" tem os seguintes métodos públicos:

   format(format_string, /, *args, **kwargs)

      O método principal da API. Ele aceita uma string de formato e um
      conjunto arbitrário de argumentos posicionais e nomeados. É
      apenas um invólucro que chama "vformat()".

      Alterado na versão 3.7: Um argumento de string de formato é
      agora somente-posicional.

   vformat(format_string, args, kwargs)

      Esta função realiza o trabalho real de formatação. Ela é exposta
      como uma função separada para casos em que você deseja passar um
      dicionário predefinido de argumentos, em vez de desempacotar e
      empacotar novamente o dicionário como argumentos individuais
      usando a sintaxe "*args" e "**kwargs". "vformat()" faz o
      trabalho de quebrar a string de formato em dados de caracteres e
      campos de substituição. Ela chama os vários métodos descritos a
      seguir.

   Além disso, o "Formatter" define uma série de métodos que devem ser
   substituídos por subclasses:

   parse(format_string)

      Percorre format_string e retorna um iterável de tuplas
      (*literal_text*, *field_name*, *format_spec*, *conversion*).
      Isso é usado por "vformat()" para quebrar a string em texto
      literal ou em campos de substituição.

      Os valores da tupla representam, conceitualmente, um intervalo
      de texto literal, seguido de um único campo de substituição. Se
      não houver texto literal (o que pode ocorrer se dois campos de
      substituição forem consecutivos), *literal_text* será uma string
      de comprimento zero. Se não houver campo de substituição, os
      valores de *field_name*, *format_spec* e *conversion* serão
      "None". O valor de *field_name* não é modificado, e a numeração
      automática de campos posicionais não numerados é realizada por
      "vformat()".

   get_field(field_name, args, kwargs)

      Dado *field_name*, converte-o em um objeto a ser formatado. A
      autonumeração de *field_name* retornada de "parse()" é feita por
      "vformat()" antes de chamar este método. Retorna uma tupla (obj,
      used_key). A versão padrão aceita strings no formato definido na
      **PEP 3101**, como "0[name]" ou "label.title". *args* e *kwargs*
      são como os argumentos passados para "vformat()". O valor de
      retorno *used_key* tem o mesmo significado que o parâmetro *key*
      em "get_value()".

   get_value(key, args, kwargs)

      Obtém o valor de um campo. O argumento *key* será um inteiro ou
      uma string. Se for um inteiro, ele representa o índice do
      argumento posicional em *args*; se for uma string, representa um
      argumento nomeado em *kwargs*.

      O parâmetro *args* é definido para a lista de argumentos
      posicionais de "vformat()", e o parâmetro *kwargs* é definido
      para o dicionário de argumentos nomeados.

      Para nomes de campos compostos, essas funções são chamadas
      apenas para o primeiro componente do nome do campo; os
      componentes subsequentes são tratados por meio de operações
      normais de atributo e de indexação.

      Então, por exemplo, a expressão de campo '0.name' faria com que
      "get_value()" fosse chamado com o argumento *key* 0. O atributo
      "name" será pesquisado após a função "get_value()" retornar,
      chamando a função embutida "getattr()".

      Se o índice ou palavra-chave se referir a um item que não
      existe, um "IndexError" ou "KeyError" deve ser levantado.

   check_unused_args(used_args, args, kwargs)

      Implementa a verificação de argumentos não usados, se desejar.
      Os argumentos para esta função são o conjunto de todas as chaves
      de argumento realmente referidas na string de formato (inteiros
      para argumentos posicionais e strings para argumentos nomeados),
      e uma referência a *args* e *kwargs* que foi passada para
      vformat. O conjunto de argumentos não utilizados pode ser
      calculado com base nesses parâmetros. Presume-se que
      "check_unused_args()" levante uma exceção caso a verificação
      falhe.

   format_field(value, format_spec)

      "format_field()" simplesmente chama o global embutido
      "format()". O método é fornecido para que as subclasses possam
      substituí-lo.

   convert_field(value, conversion)

      Converte o valor (retornado por "get_field()") de acordo com um
      tipo de conversão (como na tupla retornada pelo método
      "parse()"). A versão padrão entende os tipos de conversão "s"
      (str), "r" (repr) e "a" (ascii).


Sintaxe das strings de formato
==============================

O método "str.format()" e a classe "Formatter" compartilham a mesma
sintaxe para strings de formato (embora no caso de "Formatter", as
subclasses possam definir sua própria sintaxe de string de formato). A
sintaxe é relacionada a literais de strings formatadas e literais de
strings templates, mas é menos sofisticada e, em especial, não oferece
suporte a expressões arbitrárias em interpolações.

As strings de formato contêm "campos de substituição" entre chaves
"{}". Tudo o que não estiver entre chaves é considerado texto literal
e é copiado inalterado para a saída. Se você precisar incluir um
caractere de chave no texto literal, ele pode ser escapado
duplicando-o: "{{" e "}}".

A gramática para um campo de substituição é a seguinte:

   replacement_field: "{" [field_name] ["!" conversion] [":" format_spec] "}"
   field_name:        arg_name ("." attribute_name | "[" element_index "]")*
   arg_name:          [identifier | digit+]
   attribute_name:    identifier
   element_index:     digit+ | index_string
   index_string:      <any source character except "]"> +
   conversion:        "r" | "s" | "a"
   format_spec:       format-spec:format_spec

Em termos menos formais, o campo de substituição pode começar com um
*field_name* que especifica o objeto cujo valor deve ser formatado e
inserido na saída, em vez do próprio campo de substituição. O
*field_name* é opcionalmente seguido de um campo *conversion*, que é
precedido por um ponto de exclamação "'!'", e de um *format_spec*, que
é precedido por dois pontos "':'". Eles especificam um formato não
padrão para o valor de substituição.

Veja também a seção Minilinguagem de especificação de formato.

O próprio *field_name* começa com um *arg_name*, que pode ser um
número ou uma palavra-chave. Se for um número, ele se refere a um
argumento posicional, e se for uma palavra-chave, ele se refere a um
argumento nomeado. Um *arg_name* é tratado como um número se uma
chamada à "str.isdecimal()" na string retornar verdadeiro. Se os
arg_names numéricos em uma string de formato forem 0, 1, 2, … em
sequência, eles podem ser todos omitidos (não apenas alguns) e os
números 0, 1, 2, … serão inseridos automaticamente nessa ordem. Como
*arg_name* não está delimitado por aspas, não é possível especificar
chaves de dicionário arbitrárias (por exemplo, as strings "'10'" ou
"':-]'") em uma string de formato. O *arg_name* pode ser seguido por
qualquer número de expressões de índice ou de atributo. Uma expressão
da forma "'.name'" seleciona o atributo nomeado com "getattr()",
enquanto uma expressão da forma "'[index]'" faz uma pesquisa de índice
com "__getitem__()".

Alterado na versão 3.1: Os especificadores de argumento posicional
podem ser omitidos para "str.format()", de forma que "'{}
{}'.format(a, b)" é equivalente a "'{0} {1}'.format(a, b)".

Alterado na versão 3.4: Os especificadores de argumento posicional
podem ser omitidos para "Formatter".

Alguns exemplos simples de string de formato:

   "Primeiro, tu deverás contar até {0}"  # Referencia o primeiro argumento posicional
   "Traga-me um {}"                       # Referencia implicitamente o primeiro argumento posicional
   "De {} para {}"                        # Mesmo que "De {0} para {1}"
   "Minha missão é {nome}"                # Referencia argumento nomeado 'nome'
   "Peso em toneladas {0.peso}"           # O atributo 'peso' do primeiro argumento posicional
   "Unidades destruídas: {jogadores[0]}"  # Primeiro elemento do argumento nomeado 'jogadores'.

O campo *conversion* causa uma coerção de tipo antes da formatação.
Normalmente, o trabalho de formatação de um valor é feito pelo método
"__format__()" do próprio valor. No entanto, em alguns casos, é
desejável forçar um tipo a ser formatado como string, substituindo sua
própria definição de formatação. Ao converter o valor em uma string
antes de chamar "__format__()", a lógica de formatação normal é
contornada.

Atualmente, há suporte para três sinalizadores de conversão: "'!s'",
que chama "str()" no valor; "'!r'", que chama "repr()"; e "'!a'", que
chama "ascii()".

Alguns exemplos:

   "Harold é um {0!s} esperto"        # Chama str() no primeiro argumento
   "Trazei à luz o {name!r} sagrado"    # Chama repr() no primeiro argumento
   "Mais {!a}"                      # Chama ascii() no primeiro argumento

O campo *format_spec* contém uma especificação de como o valor deve
ser apresentado, incluindo detalhes como a largura do campo, o
alinhamento, o preenchimento, a precisão decimal e assim por diante.
Cada tipo de valor pode definir sua própria "minilinguagem de
formatação" ou interpretação de *format_spec*.

A maioria dos tipos embutidos oferece suporte a uma minilinguagem de
formatação comum, descrita na próxima seção.

O campo *format_spec* também pode conter campos de substituição
aninhados. Esses campos de substituição aninhados podem conter um nome
de campo, um sinalizador de conversão e uma especificação de formato,
mas um aninhamento mais profundo não é permitido. Os campos de
substituição em format_spec são substituídos antes que a string
*format_spec* seja interpretada. Isso permite que a formatação de um
valor seja especificada dinamicamente.

Veja a seção Exemplos de formato para alguns exemplos.


Minilinguagem de especificação de formato
-----------------------------------------

"Especificações de formato" são usadas nos campos de substituição
contidos em uma string de formato para definir como os valores
individuais são apresentados (consulte Sintaxe das strings de formato,
Literais de strings formatadas e Literais de string template
(t-strings)). Elas também podem ser passadas diretamente para a função
embutida "format()". Cada tipo formatável pode definir como a
especificação do formato deve ser interpretada.

A maioria dos tipos embutidos implementa as seguintes opções para
especificações de formato, embora algumas das opções de formatação
sejam válidas apenas para tipos numéricos.

Uma convenção geral é que uma especificação de formato vazia produz o
mesmo resultado que se você tivesse chamado "str()" no valor. Uma
especificação de formato não vazio geralmente modifica o resultado.

A forma geral de um *especificador de formato padrão* é:

   format_spec:             [options][width_and_precision][type]
   options:                 [[fill]align][sign]["z"]["#"]["0"]
   fill:                    <any character>
   align:                   "<" | ">" | "=" | "^"
   sign:                    "+" | "-" | " "
   width_and_precision:     [width_with_grouping][precision_with_grouping]
   width_with_grouping:     [width][grouping]
   precision_with_grouping: "." [precision][grouping] | "." grouping
   width:                   digit+
   precision:               digit+
   grouping:                "," | "_"
   type:                    "b" | "c" | "d" | "e" | "E" | "f" | "F" | "g"
                            | "G" | "n" | "o" | "s" | "x" | "X" | "%"

Se um valor *align*  válido for especificado, ele pode ser precedido
por um caractere de preenchimento *fill* que pode ser qualquer
caractere e o padrão é um espaço se omitido. Não é possível usar uma
chave literal (""{"" ou ""}"") como o caractere *fill* em uma string
formatada literal ou ao usar o método "str.format()". No entanto, é
possível inserir uma chave com um campo de substituição aninhado. Esta
limitação não afeta a função "format()".

O significado das várias opções de alinhamento é o seguinte:

+-----------+------------------------------------------------------------+
| Opção     | Significado                                                |
|===========|============================================================|
| "'<'"     | Força o alinhamento à esquerda do campo no espaço          |
|           | disponível (este é o padrão para a maioria dos objetos).   |
+-----------+------------------------------------------------------------+
| "'>'"     | Força o alinhamento à direita do campo no espaço           |
|           | disponível (este é o padrão para números).                 |
+-----------+------------------------------------------------------------+
| "'='"     | Força o preenchimento a ser colocado após o sinal (se      |
|           | houver), mas antes dos dígitos. É usado para imprimir      |
|           | campos na forma "+000000120". Esta opção de alinhamento só |
|           | é válida para tipos numéricos, excluindo "complex". Torna- |
|           | se o padrão para números quando "0" precede imediatamente  |
|           | a largura do campo.                                        |
+-----------+------------------------------------------------------------+
| "'^'"     | Força a centralização do campo no espaço disponível.       |
+-----------+------------------------------------------------------------+

Observe que, a menos que uma largura de campo mínima seja definida, a
largura do campo sempre será igual à largura dos dados que preenchem,
de modo que a opção de alinhamento não tem significado neste caso.

A opção *sign* só é válida para tipos numéricos e pode ser um dos
seguintes:

+-----------+------------------------------------------------------------+
| Opção     | Significado                                                |
|===========|============================================================|
| "'+'"     | Indica que um sinal deve ser usado para números positivos  |
|           | e negativos.                                               |
+-----------+------------------------------------------------------------+
| "'-'"     | Indica que um sinal deve ser usado apenas para números     |
|           | negativos (este é o comportamento padrão).                 |
+-----------+------------------------------------------------------------+
| espaço    | Indica que um espaço inicial deve ser usado em números     |
|           | positivos e um sinal de menos em números negativos.        |
+-----------+------------------------------------------------------------+

A opção "'z'" força valores de ponto flutuante de zero negativo para
zero positivo após o arredondamento, conforme a precisão do formato.
Esta opção só é válida para tipos de apresentação de ponto flutuante.

Alterado na versão 3.11: Adicionada a opção "'z'" (veja também **PEP
682**).

A opção "'#'" faz com que a "forma alternativa" seja usada na
conversão. A forma alternativa é definida de forma diferente para cada
tipo. Esta opção é válida apenas para tipos inteiros, pontos
flutuantes e complexos. Para inteiros, quando a saída binária, octal
ou hexadecimal é usada, esta opção adiciona o prefixo respectivo
"'0b'", "'0o'", "'0x'" ou "'0X'" ao valor de saída. Para pontos
flutuantes e complexos, a forma alternativa faz com que o resultado da
conversão sempre contenha um caractere de ponto decimal, mesmo que não
haja nenhum dígito após. Normalmente, um caractere de ponto decimal
aparece no resultado dessas conversões apenas se houver um dígito
depois. Além disso, nas conversões "'g'" e "'G'", os zeros finais não
são removidos do resultado.

O *width* é um número inteiro decimal que define a largura mínima
total do campo, incluindo quaisquer prefixos, separadores e outros
caracteres de formatação. Se não for especificado, a largura do campo
será determinada pelo conteúdo.

Quando nenhum alinhamento explícito é fornecido, preceder o campo
*width* com um caractere zero ("'0'") habilita o preenchimento por
zero, com reconhecimento de sinal, para tipos numéricos, exceto
"complex". Isso é equivalente a um caractere *fill* de valor "'0'" e
*alignment* de "'='".

Alterado na versão 3.10: Preceder o campo *width* com "'0'" não afeta
mais o alinhamento padrão de strings.

*precision* é um número decimal que indica quantos dígitos devem ser
exibidos depois do ponto decimal para um valor de ponto flutuante
formatado com "'f'" e "'F'", ou antes e depois do ponto decimal para
um valor de ponto flutuante formatado com "'g'" ou "'G'". Para tipos
não numéricos, o campo indica o tamanho máximo do campo -- em outras
palavras, quantos caracteres serão usados do conteúdo do campo.
*precision* não é permitido para valores inteiros.

A opção *grouping* após os campos *width* e *precision* especifica um
separador de grupo de dígitos para as partes inteira e fracionária de
um número, respectivamente. Pode ser um dos seguintes:

+-----------+------------------------------------------------------------+
| Opção     | Significado                                                |
|===========|============================================================|
| "','"     | Insere uma vírgula a cada 3 dígitos para tipos de          |
|           | apresentação inteiros "'d'" e de ponto flutuante,          |
|           | excluindo "'n'". Não há suporte para essa opção em outros  |
|           | tipos de apresentação.                                     |
+-----------+------------------------------------------------------------+
| "'_'"     | Insere um sublinhado a cada 3 dígitos para tipos de        |
|           | apresentação inteiros "'d'" e tipos de apresentação de     |
|           | ponto flutuante, excluindo "'n'". Para os tipos de         |
|           | apresentação inteiros "'b'", "'o'", "'x'" e "'X'", os      |
|           | sublinhados são inseridos a cada 4 dígitos. Para outros    |
|           | tipos de apresentação, esta opção não é suportada.         |
+-----------+------------------------------------------------------------+

Para um separador com reconhecimento de localidade, use o tipo de
apresentação "'n'".

Alterado na versão 3.1: Adicionada a opção "','" (veja também **PEP
378**).

Alterado na versão 3.6: Adicionada a opção "'_'" (veja também **PEP
515**).

Alterado na versão 3.14: Suporte a opção *grouping* para a parte
fracionária.

Finalmente, o *type* determina como os dados devem ser apresentados.

Os tipos de apresentação de string disponíveis são:

   +-----------+------------------------------------------------------------+
   | Tipo      | Significado                                                |
   |===========|============================================================|
   | "'s'"     | Formato de string. Este é o tipo padrão para strings e     |
   |           | pode ser omitido.                                          |
   +-----------+------------------------------------------------------------+
   | None      | O mesmo que "'s'".                                         |
   +-----------+------------------------------------------------------------+

Os tipos de apresentação inteira disponíveis são:

   +-----------+------------------------------------------------------------+
   | Tipo      | Significado                                                |
   |===========|============================================================|
   | "'b'"     | Formato binário. Exibe o número na base 2.                 |
   +-----------+------------------------------------------------------------+
   | "'c'"     | Caractere. Converte o inteiro no caractere Unicode         |
   |           | correspondente antes de imprimir.                          |
   +-----------+------------------------------------------------------------+
   | "'d'"     | Inteiro decimal. Exibe o número na base 10.                |
   +-----------+------------------------------------------------------------+
   | "'o'"     | Formato octal. Exibe o número na base 8.                   |
   +-----------+------------------------------------------------------------+
   | "'x'"     | Formato hexadecimal. Exibe o número na base 16, usando     |
   |           | letras minúsculas para os dígitos acima de 9.              |
   +-----------+------------------------------------------------------------+
   | "'X'"     | Formato hexadecimal. Exibe o número na base 16, usando     |
   |           | letras maiúsculas para os dígitos acima de 9. No caso de   |
   |           | "'#'" ser especificado, o prefixo "'0x'" será maiúsculo    |
   |           | para "'0X'" também.                                        |
   +-----------+------------------------------------------------------------+
   | "'n'"     | Número. É o mesmo que "'d'", exceto que usa a configuração |
   |           | de localidade atual para inserir os separadores de grupo   |
   |           | de dígitos apropriados.                                    |
   +-----------+------------------------------------------------------------+
   | None      | O mesmo que "'d'".                                         |
   +-----------+------------------------------------------------------------+

Além dos tipos de apresentação acima, os inteiros podem ser formatados
com os tipos de apresentação de ponto flutuante listados abaixo
(exceto "'n'" e "None"). Ao fazer isso, "float()" é usado para
converter o inteiro em um número de ponto flutuante antes da
formatação.

Os tipos de apresentação disponíveis para valores "float" e "Decimal"
são:

   +-----------+------------------------------------------------------------+
   | Tipo      | Significado                                                |
   |===========|============================================================|
   | "'e'"     | Notação científica. Para uma dada precisão "p", formata o  |
   |           | número em notação científica com a letra "e" separando o   |
   |           | coeficiente do expoente. O coeficiente tem um dígito antes |
   |           | e "p" dígitos depois do ponto decimal, totalizando "p + 1" |
   |           | dígitos significativos. Sem precisão fornecida, usa uma    |
   |           | precisão de "6" dígitos após o ponto decimal para "float"  |
   |           | e mostra todos os dígitos de coeficiente para "Decimal".   |
   |           | Se "p=0", o ponto decimal é omitido a menos que a opção    |
   |           | "#" seja usada.  Para "float", o expoente sempre contém    |
   |           | pelo menos dois dígitos e é zero se o valor for zero.      |
   +-----------+------------------------------------------------------------+
   | "'E'"     | Notação científica. O mesmo que "'e'", exceto que usa um   |
   |           | 'E' maiúsculo como caractere separador.                    |
   +-----------+------------------------------------------------------------+
   | "'f'"     | Notação de ponto fixo. Para uma dada precisão "p", formata |
   |           | o número como um número decimal com exatamente "p" dígitos |
   |           | após o ponto decimal. Sem precisão fornecida, usa uma      |
   |           | precisão de "6" dígitos após o ponto decimal para "float"  |
   |           | e uma precisão grande o suficiente para mostrar todos os   |
   |           | dígitos de coeficiente para "Decimal". Se "p=0", o ponto   |
   |           | decimal é omitido a menos que a opção "#" seja usada.      |
   +-----------+------------------------------------------------------------+
   | "'F'"     | Notação de ponto fixo. O mesmo que "'f'", mas converte     |
   |           | "nan" para "NAN" e "inf" para "INF".                       |
   +-----------+------------------------------------------------------------+
   | "'g'"     | Formato geral. Para uma determinada precisão "p >= 1",     |
   |           | isso arredonda o número para "p" dígitos significativos e, |
   |           | então, formata o resultado em ponto fixo ou em notação     |
   |           | científica, conforme sua magnitude. Uma precisão de "0" é  |
   |           | tratada como equivalente a uma precisão de "1".  As regras |
   |           | precisas são as seguintes: suponha que o resultado         |
   |           | formatado com tipo de apresentação "'e'" e precisão "p-1"  |
   |           | teria o expoente "exp". Então, se "m <= exp < p", onde "m" |
   |           | é -4 para pontos flutuantes e -6 para "Decimals", o número |
   |           | é formatado com o tipo de apresentação "'f'" e precisão    |
   |           | "p-1-exp". Caso contrário, o número é formatado com o tipo |
   |           | de apresentação "'e'" e a precisão "p-1". Em ambos os      |
   |           | casos, zeros à direita insignificantes são removidos do    |
   |           | significando, e o ponto decimal também é removido se não   |
   |           | houver dígitos restantes após ele, a menos que a opção     |
   |           | "'#'" seja usada.  Sem precisão fornecida, usa uma         |
   |           | precisão de "6" dígitos significativos para "float". Para  |
   |           | "Decimal", o coeficiente do resultado é formado a partir   |
   |           | dos dígitos do coeficiente do valor; a notação científica  |
   |           | é usada para valores menores que "1e-6" em valor absoluto  |
   |           | e valores em que o valor posicional do dígito menos        |
   |           | significativo é maior que 1, e a notação de ponto fixo é   |
   |           | usada de outra forma.  Infinito positivo e negativo, zero  |
   |           | positivo e negativo e não- números, são formatados como    |
   |           | "inf", "-inf", "0", "-0" e "nan", respectivamente,         |
   |           | independentemente da precisão.                             |
   +-----------+------------------------------------------------------------+
   | "'G'"     | Formato geral. O mesmo que "'g'", exceto muda para "'E'"   |
   |           | se o número ficar muito grande. As representações de       |
   |           | infinito e de NaN também são maiúsculas.                   |
   +-----------+------------------------------------------------------------+
   | "'n'"     | Número. É o mesmo que "'g'", exceto que usa a configuração |
   |           | de localidade atual para inserir os separadores de grupo   |
   |           | de dígitos apropriados na parte inteira de um número.      |
   +-----------+------------------------------------------------------------+
   | "'%'"     | Porcentagem. Multiplica o número por 100 e exibe no        |
   |           | formato fixo ("'f'"), seguido de um sinal de porcentagem.  |
   +-----------+------------------------------------------------------------+
   | None      | Para "float", é o como o tipo "'g'", exceto que quando a   |
   |           | notação de ponto fixo é usada para formatar o resultado,   |
   |           | ela sempre inclui pelo menos um dígito após o ponto        |
   |           | decimal, e troca para a notação científica quando "exp >=  |
   |           | p - 1". Quando a precisão não é especificada, este último  |
   |           | será tão grande quanto necessário para representar o valor |
   |           | fornecido fielmente.  Para "Decimal", é o mesmo que "'g'"  |
   |           | ou "'G'", dependendo do valor de "context.capitals" no     |
   |           | contexto decimal atual.  O efeito geral é combinar a saída |
   |           | de "str()" conforme alterada pelos demais modificadores de |
   |           | formato.                                                   |
   +-----------+------------------------------------------------------------+

O resultado deve ser arredondado corretamente para uma dada precisão
"p" de dígitos após o ponto decimal. O modo de arredondamento para
"float" corresponde ao da função embutida "round()". Para "Decimal", o
modo de arredondamento do contexto atual será aplicado.

Os tipos de apresentação disponíveis para "complex" são os mesmos que
para "float" ("'%'" não é permitido). Os componentes real e imaginário
de um número complexo são formatados como números de ponto flutuante,
conforme o tipo de apresentação especificado. Eles são separados pelo
sinal obrigatório da parte imaginária, que é terminada por um sufixo
"j". Se o tipo de apresentação estiver faltando, o resultado
corresponderá à saída de "str()" (números complexos com uma parte real
diferente de zero também são cercados por parênteses), possivelmente
alterado por outros modificadores de formato.


Exemplos de formato
-------------------

Esta seção contém exemplos da sintaxe de "str.format()" e comparação
com a antiga formatação com "%".

Na maioria dos casos, a sintaxe é semelhante à antiga formatação com
"%", com a adição de "{}" e o uso de ":" em vez de "%". Por exemplo,
"'%03.2f'" pode ser traduzido para "'{:03.2f}'".

A nova sintaxe de formato também oferece suporte a novas e diferentes
opções, como mostradas nos exemplos a seguir.

Acessando argumentos por posição:

   >>> '{0}, {1}, {2}'.format('a', 'b', 'c')
   'a, b, c'
   >>> '{}, {}, {}'.format('a', 'b', 'c')  # somente 3.1+
   'a, b, c'
   >>> '{2}, {1}, {0}'.format('a', 'b', 'c')
   'c, b, a'
   >>> '{2}, {1}, {0}'.format(*'abc')      # desempacotando sequência de argumentos
   'c, b, a'
   >>> '{0}{1}{0}'.format('abra', 'cad')   # índices dos argumentos podem ser repetidos
   'abracadabra'

Acessando argumentos por nome:

   >>> 'Coordinates: {latitude}, {longitude}'.format(latitude='37.24N', longitude='-115.81W')
   'Coordinates: 37.24N, -115.81W'
   >>> coord = {'latitude': '37.24N', 'longitude': '-115.81W'}
   >>> 'Coordinates: {latitude}, {longitude}'.format(**coord)
   'Coordinates: 37.24N, -115.81W'

Acessando atributos dos argumentos:

   >>> c = 3-5j
   >>> ('The complex number {0} is formed from the real part {0.real} '
   ...  'and the imaginary part {0.imag}.').format(c)
   'The complex number (3-5j) is formed from the real part 3.0 and the imaginary part -5.0.'
   >>> class Point:
   ...     def __init__(self, x, y):
   ...         self.x, self.y = x, y
   ...     def __str__(self):
   ...         return 'Point({self.x}, {self.y})'.format(self=self)
   ...
   >>> str(Point(4, 2))
   'Point(4, 2)'

Acessando itens dos argumentos:

   >>> coord = (3, 5)
   >>> 'X: {0[0]};  Y: {0[1]}'.format(coord)
   'X: 3;  Y: 5'

Substituindo "%s" e "%r":

   >>> "repr() mostra aspas: {!r}; str() não mostra: {!s}".format('teste1', 'teste2')
   "repr() mostra aspas: 'teste1'; str() não mostra: teste2"

Alinhando o texto e especificando uma largura:

   >>> '{:<30}'.format('alinhado à esquerda')
   'alinhado à esquerda           '
   >>> '{:>30}'.format('alinhado à direita')
   '            alinhado à direita'
   >>> '{:^30}'.format('centralizado')
   '         centralizado         '
   >>> '{:*^30}'.format('centralizado')  # usa '*' como preenchimento
   '*********centralizado*********'

Substituindo "%+f", "%-f" e "% f" e especificando um sinal:

   >>> '{:+f}; {:+f}'.format(3.14, -3.14)  # mostra sempre
   '+3.140000; -3.140000'
   >>> '{: f}; {: f}'.format(3.14, -3.14)  # mostra um espaço para números positivos
   ' 3.140000; -3.140000'
   >>> '{:-f}; {:-f}'.format(3.14, -3.14)  # mostra apenas o sinal de menos -- o mesmo que '{:f}; {:f}'
   '3.140000; -3.140000'

Substituindo "%x" e "%o" e convertendo o valor para bases diferentes:

   >>> # format também tem suporte a números binários
   >>> "int: {0:d};  hex: {0:x};  oct: {0:o};  bin: {0:b}".format(42)
   'int: 42;  hex: 2a;  oct: 52;  bin: 101010'
   >>> # com 0x, 0o ou 0b como prefixo:
   >>> "int: {0:d};  hex: {0:#x};  oct: {0:#o};  bin: {0:#b}".format(42)
   'int: 42;  hex: 0x2a;  oct: 0o52;  bin: 0b101010'

Usando a vírgula ou o sublinhado como separador de grupos de dígitos:

   >>> '{:,}'.format(1234567890)
   '1,234,567,890'
   >>> '{:_}'.format(1234567890)
   '1_234_567_890'
   >>> '{:_b}'.format(1234567890)
   '100_1001_1001_0110_0000_0010_1101_0010'
   >>> '{:_x}'.format(1234567890)
   '4996_02d2'
   >>> '{:_}'.format(123456789.123456789)
   '123_456_789.12345679'
   >>> '{:.,}'.format(123456789.123456789)
   '123456789.123,456,79'
   >>> '{:,._}'.format(123456789.123456789)
   '123,456,789.123_456_79'

Expressando uma porcentagem:

   >>> points = 19
   >>> total = 22
   >>> 'Correct answers: {:.2%}'.format(points/total)
   'Correct answers: 86.36%'

Usando formatação específica do tipo:

   >>> import datetime as dt
   >>> d = dt.datetime(2010, 7, 4, 12, 15, 58)
   >>> '{:%Y-%m-%d %H:%M:%S}'.format(d)
   '2010-07-04 12:15:58'

Aninhando argumentos e exemplos mais complexos:

   >>> for align, text in zip('<^>', ['left', 'center', 'right']):
   ...     '{0:{fill}{align}16}'.format(text, fill=align, align=align)
   ...
   'left<<<<<<<<<<<<'
   '^^^^^center^^^^^'
   '>>>>>>>>>>>right'
   >>>
   >>> octets = [192, 168, 0, 1]
   >>> '{:02X}{:02X}{:02X}{:02X}'.format(*octets)
   'C0A80001'
   >>> int(_, 16)
   3232235521
   >>>
   >>> width = 5
   >>> for num in range(5,12):
   ...     for base in 'dXob':
   ...         print('{0:{width}{base}}'.format(num, base=base, width=width), end=' ')
   ...     print()
   ...
       5     5     5   101
       6     6     6   110
       7     7     7   111
       8     8    10  1000
       9     9    11  1001
      10     A    12  1010
      11     B    13  1011


Strings template ($-strings)
============================

Nota:

  O recurso descrito aqui foi introduzido no Python 2.4; um método de
  modelagem simples baseado em expressões regulares. Ele é anterior a
  "str.format()", literais de strings formatadas e literais de strings
  templates.Não tem relação com os literais de string template
  (t-strings), introduzidos no Python 3.14. Estes são avaliados como
  objetos da classe "string.templatelib.Template", encontrados no
  módulo "string.templatelib".

Strings template fornecem substituições de string mais simples,
conforme descrito em **PEP 292**. Um caso de uso primário para strings
template é a internacionalização (i18n), uma vez que, nesse contexto,
a sintaxe e a funcionalidade mais simples tornam mais fácil traduzir
do que outros recursos embutidos de formatação de strings no Python.
Como um exemplo de biblioteca construída sobre strings template para
i18n, veja o pacote flufl.i18n.

Strings template oferecem suporte a substituições baseadas em "$",
usando as seguintes regras:

* "$$" é um escape; é substituído por um único "$".

* "$identifier" nomeia um espaço reservado de substituição
  correspondente à chave de mapeamento ""identifier"". Por padrão,
  ""identifier"" é restrito a qualquer string ASCII alfanumérica que
  não distingue maiúsculas e minúsculas (incluindo sublinhados) e que
  começa com um sublinhado ou com uma letra ASCII. O primeiro
  caractere não identificador após o caractere "$" termina esta
  especificação de espaço reservado.

* "${identifier}"  é equivalente a "$identifier". É necessário quando
  caracteres identificadores válidos seguem o marcador de posição, mas
  não fazem parte do marcador, como ""${noun}ification"".

Qualquer outra ocorrência de "$" na string resultará em uma
"ValueError" sendo levantada.

O módulo "string" fornece uma classe "Template" que implementa essas
regras. Os métodos de "Template" são:

class string.Template(template)

   O construtor recebe um único argumento que é a string template

   substitute(mapping={}, /, **kwds)

      Executa a substituição do modelo, retornando uma nova string.
      *mapping* é qualquer objeto dicionário ou similar com chaves que
      correspondem aos marcadores de posição no modelo. Como
      alternativa, você pode fornecer argumentos nomeados, os quais
      são espaços reservados. Quando *mapping* e *kwds* são fornecidos
      e há duplicatas, os marcadores de *kwds* têm precedência.

   safe_substitute(mapping={}, /, **kwds)

      Como "substitute()", exceto que se os espaços reservados
      estiverem faltando em *mapping* e *kwds*, em vez de levantar uma
      exceção "KeyError", o espaço reservado original aparecerá na
      string resultante intacta. Além disso, ao contrário de
      "substitute()", qualquer outra ocorrência de "$" simplesmente
      retornará "$" em vez de levantar "ValueError".

      Embora outras exceções ainda possam ocorrer, esse método é
      chamado de "seguro" porque sempre tenta retornar uma string
      utilizável em vez de levantar uma exceção. Em outro sentido,
      "safe_substitute()" pode ser qualquer coisa diferente de seguro,
      uma vez que irá ignorar silenciosamente modelos malformados
      contendo delimitadores pendentes, chaves não correspondidas ou
      espaços reservados que não são identificadores Python válidos.

   is_valid()

      Retorna "False" se o modelo tiver espaços reservados inválidos
      que farão com que "substitute()" levante "ValueError".

      Adicionado na versão 3.11.

   get_identifiers()

      Retorna uma lista dos identificadores válidos no modelo, na
      ordem em que aparecem pela primeira vez, ignorando quaisquer
      identificadores inválidos.

      Adicionado na versão 3.11.

   Instâncias de "Template" também fornecem um atributo de dados
   públicos:

   template

      Este é o objeto passado para o argumento *template* do
      construtor. Em geral, você não deve alterá-lo, mas o acesso
      somente leitura não é obrigatório.

Aqui está um exemplo de como usar uma instância de Template:

   >>> from string import Template
   >>> s = Template('$who likes $what')
   >>> s.substitute(who='tim', what='kung pao')
   'tim likes kung pao'
   >>> d = dict(who='tim')
   >>> Template('Give $who $100').substitute(d)
   Traceback (most recent call last):
   ...
   ValueError: Invalid placeholder in string: line 1, col 11
   >>> Template('$who likes $what').substitute(d)
   Traceback (most recent call last):
   ...
   KeyError: 'what'
   >>> Template('$who likes $what').safe_substitute(d)
   'tim likes $what'

Uso avançado: você pode derivar subclasses de "Template" para
personalizar a sintaxe do espaço reservado, caractere delimitador ou
toda a expressão regular usada para analisar strings template. Para
fazer isso, você pode substituir estes atributos de classe:

* *delimiter* -- Este é a string literal que descreve um delimitador
  de introdução do espaço reservado. O valor padrão é "$". Note que
  esta *não* deve ser uma expressão regular, já que a implementação
  irá chamar "re.escape()" nesta string conforme necessário. Observe
  também que você não pode alterar o delimitador após a criação da
  classe (ou seja, um delimitador diferente deve ser definido no
  espaço de nomes da classe da subclasse).

* *idpattern* -- Esta é a expressão regular que descreve o padrão para
  espaço reservado sem envolto em chaves. O valor padrão é a expressão
  regular "(?a:[_a-z][_a-z0-9]*)". Se for fornecido e *braceidpattern*
  for "None", esse padrão também se aplicará o espaço reservado com
  chaves.

  Nota:

    Uma vez que *flags* padrão é "re.IGNORECASE", o padrão "[a-z]"
    pode corresponder a alguns caracteres não ASCII. É por isso que
    usamos o sinalizador local "a" aqui.

  Alterado na versão 3.7: *braceidpattern* pode ser usado para definir
  padrões separados usados dentro e fora das chaves.

* *braceidpattern* -- É como *idpattern*, mas descreve o padrão para
  espaços reservados com chaves. O padrão é "None", o que significa
  recorrer a *idpattern* (ou seja, o mesmo padrão é usado dentro e
  fora das chaves). Se fornecido, permite definir padrões diferentes
  para espaço reservado com e sem chaves.

  Adicionado na versão 3.7.

* *flags* -- Os sinalizadores de expressão regular que serão aplicados
  ao compilar a expressão regular usada para reconhecer substituições.
  O valor padrão é "re.IGNORECASE". Note que "re.VERBOSE" sempre será
  adicionado aos sinalizadores, então *idpattern*s personalizados
  devem seguir as convenções para expressões regulares verbosas.

  Adicionado na versão 3.2.

Como alternativa, você pode fornecer todo o padrão de expressão
regular substituindo o atributo *pattern* de classe. Se você fizer
isso, o valor deve ser um objeto de expressão regular com quatro
grupos de captura nomeados. Os grupos de captura correspondem às
regras fornecidas acima, junto com a regra inválida do espaço
reservado:

* *escaped* -- Este grupo corresponde à sequência de escape, por
  exemplo "$$", no padrão.

* *named* -- Este grupo corresponde ao nome do espaço reservado sem
  chaves; não deve incluir o delimitador no grupo de captura.

* *braced* -- Este grupo corresponde ao nome do espaço reservado entre
  chaves; ele não deve incluir o delimitador ou chaves no grupo de
  captura.

* *invalid* -- Esse grupo corresponde a qualquer outro padrão de
  delimitador (geralmente um único delimitador) e deve aparecer por
  último na expressão regular.

Os métodos nesta classe irão levantar "ValueError" se o padrão
corresponder ao modelo sem que um desses grupos nomeados corresponda.


Funções auxiliares
==================

string.capwords(s, sep=None)

   Divide o argumento em palavras usando "str.split()", coloca cada
   palavra em maiúscula usando "str.capitalize()", e junte as palavras
   em maiúsculas usando "str.join()". Se o segundo argumento opcional
   *sep* estiver ausente ou "None", os caracteres de espaço em branco
   são substituídos por um único espaço e os espaços em branco à
   esquerda e à direita são removidos, caso contrário *sep* é usado
   para dividir e unir as palavras.
