Esta documentação é de uma versão antiga do Python que não é mais atualizada. Você deveria atualizar e ler a documentação do Python para versão estável atual.

# `string` — Operações comuns de strings

Código Fonte: Lib/string.py

Ver também

Tipo de 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 of ASCII characters which are considered punctuation characters in the `C` locale.

`string.``printable`

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

`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 fazer substituições de variáveis complexas e formatação de valor 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 que o 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. Leva 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. Ele é exposto como uma função separada para casos onde você deseja passar um dicionário predefinido de argumentos, ao invés de desempacotar e empacotar 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 abaixo.

  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 campos de substituição.

    Os valores na tupla representam conceitualmente um intervalo de texto literal seguido por um único campo de substituição. Se não houver texto literal (o que pode acontecer se dois campos de substituição ocorrerem consecutivamente), então literal_text será uma string de comprimento zero. Se não houver campo de substituição, então os valores de field_name, format_spec e conversion serão `None`.

  `get_field`(field_name, args, kwargs)

    Dado field_name conforme retornado por `parse()` (veja acima), converte-o em um objeto a ser formatado. 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 passados para `vformat()`. O valor de retorno used_key tem o mesmo significado que o parâmetro key para `get_value()`.

  `get_value`(key, args, kwargs)

    Obtém um determinado valor de 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, então representa um argumento nomeado em kwargs.

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

    For compound field names, these functions are only called for the first component of the field name; Subsequent components are handled through normal attribute and indexing operations.

    Então, por exemplo, a expressão de campo ‘0.name’ faria com que `get_value()` fosse chamado com um argumento key de 0. O atributo `name` será pesquisado após `get_value()` retorna 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 levantada.

  `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 que foram 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 a partir desses parâmetros. Presume-se que `check_unused_args()` levata uma exceção se a verificação falhar.

  `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()`) dado 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 string formatadas, mas há diferenças.

As strings de formato contêm “campos de substituição” entre chaves `{}`. Tudo o que não estiver entre chaves é considerado texto literal, que é copiado inalterado para a saída. Se você precisar incluir um caractere de chave no texto literal, ele pode ser escapado duplicando: `{{` 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       ::=  <described in the next section>

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 campo de substituição. O field_name é opcionalmente seguido por um campo conversion, que é precedido por um ponto de exclamação `'!'`, e 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 é 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. 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 é delimitado por aspas, não é possível especificar chaves de dicionário arbitrárias (por exemplo, as strings `'10'` ou `':-]'`) dentro de uma string de formato. O arg_name pode ser seguido por qualquer número de expressões de índice ou atributo. Uma expressão da forma `'.name'` seleciona o atributo nomeado usando `getattr()`, enquanto uma expressão da forma `'[index]'` faz uma pesquisa de índice usando `__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:

    "First, thou shalt count to {0}"  # References first positional argument
    "Bring me a {}"                   # Implicitly references the first positional argument
    "From {} to {}"                   # Same as "From {0} to {1}"
    "My quest is {name}"              # References keyword argument 'name'
    "Weight in tons {0.weight}"       # 'weight' attribute of first positional arg
    "Units destroyed: {players[0]}"   # First element of keyword argument 'players'.

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 uma 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.

Três sinalizadores de conversão são atualmente suportados: `'!s'`, que chama `str()` no valor; `'!r'`, que chama `repr()`; e `'!a'`, que chama `ascii()`.

Alguns exemplos:

    "Harold's a clever {0!s}"        # Calls str() on the argument first
    "Bring out the holy {name!r}"    # Calls repr() on the argument first
    "More {!a}"                      # Calls ascii() on the argument first

O campo format_spec contém uma especificação de como o valor deve ser apresentado, incluindo detalhes como largura do campo, alinhamento, preenchimento, 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, que é descrita na próxima seção.

Um campo format_spec também pode incluir campos de substituição aninhados dentro dele. Esses campos de substituição aninhados podem conter um nome de campo, sinalizador de conversão e 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 e Literais de string formatados). 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 suportadas apenas pelos tipos numéricos.

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

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

    format_spec     ::=  [[fill]align][sign][#][0][width][grouping_option][.precision][type]
    fill            ::=  <any character>
    align           ::=  "<" | ">" | "=" | "^"
    sign            ::=  "+" | "-" | " "
    width           ::=  digit+
    grouping_option ::=  "_" | ","
    precision       ::=  digit+
    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 dentro do espaço disponível (este é o padrão para a maioria dos objetos).
> `'>'` | Força o alinhamento à direita do campo dentro do 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. Torna-se o padrão 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á do mesmo tamanho que os dados para preenchê-lo, 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.

The `'#'` option causes the “alternate form” to be used for the conversion. The alternate form is defined differently for different types. This option is only valid for integer, float, complex and Decimal types. For integers, when binary, octal, or hexadecimal output is used, this option adds the prefix respective `'0b'`, `'0o'`, or `'0x'` to the output value. For floats, complex and Decimal the alternate form causes the result of the conversion to always contain a decimal-point character, even if no digits follow it. Normally, a decimal-point character appears in the result of these conversions only if a digit follows it. In addition, for `'g'` and `'G'` conversions, trailing zeros are not removed from the result.

A opção `','` sinaliza o uso de uma vírgula para um separador de milhares. Para um separador que reconhece a localidade, use o tipo de apresentação inteiro `'n'`.

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

A opção `'_'` sinaliza o uso de um sublinhado para um separador de milhares para tipos de apresentação de ponto flutuante e para o tipo de apresentação de inteiro `'d'`. Para os tipos de apresentação inteiros `'b'`, `'o'`, `'x'` e `'X'`, sublinhados serão inseridos a cada 4 dígitos. Para outros tipos de apresentação, especificar esta opção é um erro.

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

width é um número inteiro decimal que define a largura total mínima 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 largura com um caractere zero (`'0'`) habilita o preenchimento por zero com reconhecimento de sinal para tipos numéricos. Isso é equivalente a um caractere de fill* de `'0'` com um tipo de alignment de `'='`.

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.

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'` | Decimal Integer. Outputs the number in base 10.
> `'o'` | Octal format. Outputs the number in base 8.
> `'x'` | Hex format. Outputs the number in base 16, using lower-case letters for the digits above 9.
> `'X'` | Formato hexadecimal. Produz o número na base 16, usando letras maiúsculas para os dígitos acima de 9.
> `'n'` | Número. É o mesmo que `'d'`, exceto que usa a configuração local atual para inserir os caracteres separadores de número 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.

The available presentation types for floating point and decimal values are:

> Tipo | Significado
> --- | ---
> `'e'` | Exponent notation. Prints the number in scientific notation using the letter ‘e’ to indicate the exponent. The default precision is `6`.
> `'E'` | Exponent notation. Same as `'e'` except it uses an upper case ‘E’ as the separator character.
> `'f'` | Fixed-point notation. Displays the number as a fixed-point number. The default precision is `6`.
> `'F'` | Notação de ponto fixo. O mesmo que `'f'`, mas converte `nan` para `NAN` e `inf` para `INF`.
> `'g'` | General format. For a given precision `p >= 1`, this rounds the number to `p` significant digits and then formats the result in either fixed-point format or in scientific notation, depending on its magnitude. The precise rules are as follows: suppose that the result formatted with presentation type `'e'` and precision `p-1` would have exponent `exp`. Then if `-4 <= exp < p`, the number is formatted with presentation type `'f'` and precision `p-1-exp`. Otherwise, the number is formatted with presentation type `'e'` and precision `p-1`. In both cases insignificant trailing zeros are removed from the significand, and the decimal point is also removed if there are no remaining digits following it, unless the `'#'` option is used. Infinito positivo e negativo, zero positivo e negativo e nans, são formatados como `inf`, `-inf`, `0`, `-0` e `nan`, respectivamente, independentemente da precisão. A precision of `0` is treated as equivalent to a precision of `1`. The default precision is `6`.
> `'G'` | Formato geral. O mesmo que `'g'`, exceto muda para `'E'` se o número ficar muito grande. As representações de infinito e NaN também são maiúsculas.
> `'n'` | Número. É o mesmo que `'g'`, exceto que usa a configuração da localidade atual para inserir os caracteres separadores de número apropriados.
> `'%'` | Porcentagem. Multiplica o número por 100 e exibe no formato fixo (`'f'`), seguido por um sinal de porcentagem.
> None | Similar to `'g'`, except that fixed-point notation, when used, has at least one digit past the decimal point. The default precision is as high as needed to represent the particular value. The overall effect is to match the output of `str()` as altered by the other format modifiers.

### Exemplos de formato

Esta seção contém exemplos da sintaxe de:meth:str.format e comparação com a antiga formatação `%`.

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

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

Acessando os argumentos por posição:

    >>> '{0}, {1}, {2}'.format('a', 'b', 'c')
    'a, b, c'
    >>> '{}, {}, {}'.format('a', 'b', 'c')  # 3.1+ only
    'a, b, c'
    >>> '{2}, {1}, {0}'.format('a', 'b', 'c')
    'c, b, a'
    >>> '{2}, {1}, {0}'.format(*'abc')      # unpacking argument sequence
    'c, b, a'
    >>> '{0}{1}{0}'.format('abra', 'cad')   # arguments' indices can be repeated
    'abracadabra'

Acessando os 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 os 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 os itens dos argumentos:

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

Substituindo `%s` e `%r`:

    >>> "repr() shows quotes: {!r}; str() doesn't: {!s}".format('test1', 'test2')
    "repr() shows quotes: 'test1'; str() doesn't: test2"

Alinhando o texto e especificando uma largura:

    >>> '{:<30}'.format('left aligned')
    'left aligned                  '
    >>> '{:>30}'.format('right aligned')
    '                 right aligned'
    >>> '{:^30}'.format('centered')
    '           centered           '
    >>> '{:*^30}'.format('centered')  # use '*' as a fill char
    '***********centered***********'

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

    >>> '{:+f}; {:+f}'.format(3.14, -3.14)  # show it always
    '+3.140000; -3.140000'
    >>> '{: f}; {: f}'.format(3.14, -3.14)  # show a space for positive numbers
    ' 3.140000; -3.140000'
    >>> '{:-f}; {:-f}'.format(3.14, -3.14)  # show only the minus -- same as '{:f}; {:f}'
    '3.140000; -3.140000'

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

    >>> # format also supports binary numbers
    >>> "int: {0:d};  hex: {0:x};  oct: {0:o};  bin: {0:b}".format(42)
    'int: 42;  hex: 2a;  oct: 52;  bin: 101010'
    >>> # with 0x, 0o, or 0b as prefix:
    >>> "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 como um separador de milhares:

    >>> '{:,}'.format(1234567890)
    '1,234,567,890'

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
    >>> d = datetime.datetime(2010, 7, 4, 12, 15, 58)
    >>> '{:%Y-%m-%d %H:%M:%S}'.format(d)
    '2010-07-04 12:15:58'

Argumentos de aninhamento 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 de modelo

Strings de modelo fornecem substituições de string mais simples, conforme descrito em PEP 292. Um caso de uso primário para strings de modelo é para 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 de modelo para i18n, veja o pacote flufl.i18n.

Strings de modelo 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 correspondendo a uma chave de mapeamento de `"identifier"`. Por padrão, `"identifier"` é restrito a qualquer string ASCII alfanumérica que não faz distinção entre maiúsculas e minúsculas (incluindo sublinhados) que começa com um sublinhado ou 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 de modelo.

  `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 espacos reservados que não são identificadores Python válidos.

  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 de modelo. 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.

  Novo 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 idpatterns personalizados devem seguir as convenções para expressões regulares verbosas.

  Novo 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.

## 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.