# `string` --- Common string operations

Source code: Lib/string/__init__.py

Voir aussi

Type Séquence de Texte — str

Méthodes de chaînes de caractères

## Chaînes constantes

Les constantes définies dans ce module sont :

string.ascii_letters

  La concaténation des constantes `ascii_lowercase` et `ascii_uppercase` décrites ci-dessous. Cette valeur n'est pas dépendante de la configuration de la localisation.

string.ascii_lowercase

  Les lettres minuscules `'abcdefghijklmnopqrstuvwxyz'`. Cette valeur ne dépend pas de la configuration de localisation et ne changera pas.

string.ascii_uppercase

  Les lettres majuscules `'ABCDEFGHIJKLMNOPQRSTUVWXYZ'`. Cette valeur ne dépend pas de la configuration de la localisation et ne changera pas.

string.digits

  La chaîne `'0123456789'`.

string.hexdigits

  La chaîne `'0123456789abcdefABCDEF'`.

string.octdigits

  La chaîne `'01234567`.

string.punctuation

  Chaîne de caractères ASCII considérés comme ponctuation dans la configuration de localisation `C` : `!"#$%&'()*+,-./:;<=>?@[\]^_`{|}~`.

string.printable

  String of ASCII characters which are considered printable by Python. This is a combination of `digits`, `ascii_letters`, `punctuation`, and `whitespace`.

  Note

  By design, `string.printable.isprintable()` returns `False`. In particular, `string.printable` is not printable in the POSIX sense (see LC_CTYPE).

string.whitespace

  Une chaîne comprenant tous les caractères ASCII considérés comme espaces. Sont inclus les caractères espace, tabulations, saut de ligne, retour du chariot, saut de page, et tabulation verticale.

## Formatage personnalisé de chaîne

La classe primitive `str` fournit la possibilité de faire des substitutions de variables complexes et du formatage de valeurs via la méthode `format()` décrite par PEP 3101. La classe `Formatter` dans le module `string` permet de créer et personnaliser vos propres comportements de formatage de chaînes en utilisant la même implémentation que la méthode primitive `format()`.

class string.Formatter

  La classe `Formatter` a les méthodes publiques suivantes :

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

    La méthode principale de l'API. Elle prend une chaîne de format et un ensemble arbitraire d'arguments positions et mot-clefs. C'est uniquement un conteneur qui appelle `vformat()`.

    Modifié dans la version 3.7: L'argument format_string est maintenant obligatoirement un paramètre positionnel.

  vformat(format_string, args, kwargs)

    Cette fonction fait le travail effectif du formatage. Elle existe comme méthode séparée au cas où vous voudriez passer un dictionnaire d'arguments prédéfini plutôt que décompresser et recompresser le dictionnaire en arguments individuels en utilisant la syntaxe `*args` et `**kwargs`. `vformat()` s'occupe de découper la chaîne de format en données de caractères et champs de remplacement. Elle appelle les différentes méthodes décrites ci-dessous.

  De plus, la classe `Formatter` définit un certain nombre de méthodes qui ont pour vocation d'être remplacées par des sous-classes :

  parse(format_string)

    Boucle sur la chaîne de format et renvoie un itérable de quadruplets (literal_text, field_name, format_spec, conversion). Ceci est utilisé par `vformat()` pour découper la chaîne de format en littéraux ou en champs de remplacement.

    The values in the tuple conceptually represent a span of literal text followed by a single replacement field. If there is no literal text (which can happen if two replacement fields occur consecutively), then literal_text will be a zero-length string. If there is no replacement field, then the values of field_name, format_spec and conversion will be `None`. The value of field_name is unmodified and auto-numbering of non-numbered positional fields is done by `vformat()`.

  get_field(field_name, args, kwargs)

    Given field_name, convert it to an object to be formatted. Auto-numbering of field_name returned from `parse()` is done by `vformat()` before calling this method. Returns a tuple (obj, used_key). The default version takes strings of the form defined in PEP 3101, such as "0[name]" or "label.title". args and kwargs are as passed in to `vformat()`. The return value used_key has the same meaning as the key parameter to `get_value()`.

  get_value(key, args, kwargs)

    Récupère la valeur d'un champ donné. L'argument key est soit un entier, soit une chaîne. Si c'est un entier, il représente l'indice de l'argument dans args. Si c'est une chaîne de caractères, elle représente le nom de l'argument dans kwargs.

    Le paramètre args est défini par la liste des arguments positionnels de `vformat()`, et le paramètre kwargs est défini par le dictionnaire des arguments mot-clefs.

    Pour les noms de champs composés, ces fonctions sont uniquement appelées sur la première composante du nom. Les composantes suivantes sont manipulées au travers des attributs normaux et des opérations sur les indices.

    Donc par exemple, le champ-expression `0.name` amènerait `get_value()` à être appelée avec un argument key valant 0. L'attribut `name` sera recherché après l'appel `get_value()` en faisant appel à la primitive `getattr()`.

    Si l'indice ou le mot-clef fait référence à un objet qui n'existe pas, alors une exception `IndexError` ou `KeyError` doit être levée.

  check_unused_args(used_args, args, kwargs)

    Implémente une vérification pour les arguments non utilisés si désiré. L'argument de cette fonction est l'ensemble des clefs qui ont été effectivement référencées dans la chaîne de format (des entiers pour les indices et des chaînes de caractères pour les arguments nommés), et une référence vers les arguments args et kwargs qui ont été passés à `vformat`. L'ensemble des arguments non utilisés peut être calculé sur base de ces paramètres. `check_unused_args()` est censée lever une exception si la vérification échoue.

  format_field(value, format_spec)

    La méthode `format_field()` fait simplement appel à la primitive globale `format()`. Cette méthode est fournie afin que les sous-classes puissent la redéfinir.

  convert_field(value, conversion)

    Convertit la valeur (renvoyée par `get_field()`) selon un type de conversion donné (comme dans le n-uplet renvoyé par la méthode `parse()`). La version par défaut comprend 's' (`str`), 'r' (`repr`) et 'a' (ASCII) comme types de conversion.

## Syntaxe de formatage de chaîne

The `str.format()` method and the `Formatter` class share the same syntax for format strings (although in the case of `Formatter`, subclasses can define their own format string syntax). The syntax is related to that of formatted string literals and template string literals, but it is less sophisticated and, in particular, does not support arbitrary expressions in interpolations.

Les chaînes de formatage contiennent des "champs de remplacement" entourés d'accolades `{}`. Tout ce qui n'est pas placé entre deux accolades est considéré comme littéral, qui est copié tel quel dans le résultat. Si vous avez besoin d'inclure une accolade en littéral, elles peuvent être échappées en les doublant : `{{` et `}}`.

La grammaire pour un champ de remplacement est définie comme suit :

    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

En termes moins formels, un champ de remplacement peut débuter par un field_name qui spécifie l'objet dont la valeur va être formatée et insérée dans le résultat à l'endroit du champ de remplacement Le field_name peut éventuellement être suivi d'un champ conversion qui est précédé d'un point d'exclamation `'!'`, et d'un format_spec qui est précédé par deux-points `':'`. Cela définit un format personnalisé pour le remplacement d'une valeur.

Voir également la section Mini-langage de spécification de format.

The field_name itself begins with an arg_name that is either a number or a keyword. If it's a number, it refers to a positional argument, and if it's a keyword, it refers to a named keyword argument. An arg_name is treated as a number if a call to `str.isdecimal()` on the string would return true. If the numerical arg_names in a format string are 0, 1, 2, ... in sequence, they can all be omitted (not just some) and the numbers 0, 1, 2, ... will be automatically inserted in that order. Because arg_name is not quote-delimited, it is not possible to specify arbitrary dictionary keys (e.g., the strings `'10'` or `':-]'`) within a format string. The arg_name can be followed by any number of index or attribute expressions. An expression of the form `'.name'` selects the named attribute using `getattr()`, while an expression of the form `'[index]'` does an index lookup using `__getitem__()`.

Modifié dans la version 3.1: Les spécificateurs de position d'argument peuvent être omis dans les appels à `str.format()`. Donc `'{} {}'.format(a, b)` est équivalent à `'{0} {1}'.format(a, b)`.

Modifié dans la version 3.4: Les spécificateurs de position d'argument peuvent être omis pour `Formatter`.

Quelques exemples simples de formatage de chaînes :

    "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'.

The conversion field causes a type coercion before formatting. Normally, the job of formatting a value is done by the `__format__()` method of the value itself. However, in some cases it is desirable to force a type to be formatted as a string, overriding its own definition of formatting. By converting the value to a string before calling `__format__()`, the normal formatting logic is bypassed.

Actuellement, trois indicateurs sont gérés : `'!s'` qui appelle la fonction `str()` sur la valeur, `'!r'` qui appelle la fonction `repr()` et `!a` qui appelle la fonction `ascii()`.

Quelques exemples :

    "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

Le champ format_spec contient une spécification sur la manière selon laquelle la valeur devrait être représentée : des informations telles que la longueur du champ, l'alignement, le remplissage, la précision décimale, etc. Chaque type peut définir son propre "mini-langage de formatage" ou sa propre interprétation de format_spec.

La plupart des types natifs gèrent un mini-langage de formatage usuel qui est décrit dans la section suivante.

Un champ format_spec peut contenir un champ de remplacement imbriqué. Ces champs de remplacement imbriqués peuvent contenir un nom de champ, un indicateur de conversion, mais une imbrication récursive plus profonde n'est pas permise. Les champs de remplacement au sein de format_spec sont substitués avant que la chaîne format_spec ne soit interprétée. Cela permet que le formatage d'une valeur soit dynamiquement spécifié.

Voir la section Exemples de formats pour des exemples.

### Mini-langage de spécification de format

"Format specifications" are used within replacement fields contained within a format string to define how individual values are presented (see Syntaxe de formatage de chaîne, f-strings, and t-strings). They can also be passed directly to the built-in `format()` function. Each formattable type may define how the format specification is to be interpreted.

La plupart des primitives implémentent les options suivantes, même si certaines options de formatage ne sont prises en charge que pour les types numériques.

Une convention généralement admise est qu'une chaîne vide produit le même résultat que si vous aviez appelé `str()` sur la valeur. Une chaîne de format non vide modifie habituellement le résultat.

La forme générale d'un spécificateur de format standard est :

    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" | "%"

Si une valeur valide est spécifiée pour align, elle peut être précédée par un caractère fill, qui peut être n'importe quel caractère (espace par défaut si la valeur est omise). Il n'est pas possible d'utiliser une accolade littérale ("`{`" ou "`}`") comme caractère fill dans une chaîne de formatage littérale ou avec la méthode `str.format()`. Cependant, il est possible d'insérer une accolade à l'aide d'un champ de remplacement imbriqué. Cette limitation n'affecte pas la fonction `format()`.

Le sens des différentes options d'alignement est donné comme suit :

Option | Signification
--- | ---
`'<'` | Force le champ à être aligné à gauche dans l'espace disponible (c'est le spécificateur par défaut pour la plupart des objets).
`'>'` | Force le champ à être aligné à droite dans l'espace disponible (c'est le spécificateur par défaut pour les nombres).
`'='` | Forces the padding to be placed after the sign (if any) but before the digits. This is used for printing fields in the form '+000000120'. This alignment option is only valid for numeric types, excluding `complex`. It becomes the default for numbers when '0' immediately precedes the field width.
`'^'` | Force le champ à être centré dans l'espace disponible.

Notons que la longueur du champ est toujours égale à la taille nécessaire pour remplir le champ avec l'objet à moins que la valeur minimum ne soit précisée. Ainsi, si aucune valeur n'est précisée, l'option d'alignement n'a aucun sens.

L'option sign est uniquement valide pour les types numériques, et peut valoir :

Option | Signification
--- | ---
`'+'` | Indicates that a sign should be used for both positive as well as negative numbers.
`'-'` | Indicates that a sign should be used only for negative numbers (this is the default behavior).
espace | Indicates that a leading space should be used on positive numbers, and a minus sign on negative numbers.

The `'z'` option coerces negative zero floating-point values to positive zero after rounding to the format precision. This option is only valid for floating-point presentation types.

Modifié dans la version 3.11: Added the `'z'` option (see also PEP 682).

L'option `'#'` impose l'utilisation de la "forme alternative" pour la conversion. La forme alternative est définie différemment pour différent types. Cette option est uniquement valide pour les types entiers, flottants et complexes. Pour les entiers, quand l'affichage binaire, octal ou hexadécimal est utilisé, cette option ajoute le préfixe `'0b'`, `'0o'`, `'0x'` ou `'0X'` à la valeur affichée. Pour les flottants et les complexes, la forme alternative impose que le résultat de la conversion contienne toujours une virgule, même si aucun chiffre ne vient après. Normalement, une virgule apparaît dans le résultat de ces conversions seulement si un chiffre le suit. De plus, pour les conversions `'g'` et `'G'`, les zéros finaux ne sont pas retirés du résultat.

The width is a decimal integer defining the minimum total field width, including any prefixes, separators, and other formatting characters. If not specified, then the field width will be determined by the content.

When no explicit alignment is given, preceding the width field by a zero (`'0'`) character enables sign-aware zero-padding for numeric types, excluding `complex`. This is equivalent to a fill character of `'0'` with an alignment type of `'='`.

Modifié dans la version 3.10: Preceding the width field by `'0'` no longer affects the default alignment for strings.

The precision is a decimal integer indicating how many digits should be displayed after the decimal point for presentation types `'f'` and `'F'`, or before and after the decimal point for presentation types `'g'` or `'G'`. For string presentation types the field indicates the maximum field size - in other words, how many characters will be used from the field content. The precision is not allowed for integer presentation types.

The grouping option after width and precision fields specifies a digit group separator for the integral and fractional parts of a number respectively. It can be one of the following:

Option | Signification
--- | ---
`','` | Inserts a comma every 3 digits for integer presentation type `'d'` and floating-point presentation types, excluding `'n'`. For other presentation types, this option is not supported.
`'_'` | Inserts an underscore every 3 digits for integer presentation type `'d'` and floating-point presentation types, excluding `'n'`. For integer presentation types `'b'`, `'o'`, `'x'`, and `'X'`, underscores are inserted every 4 digits. For other presentation types, this option is not supported.

For a locale aware separator, use the `'n'` presentation type instead.

Modifié dans la version 3.1: Ajout de l'option `','` (voir PEP 378).

Modifié dans la version 3.6: Ajout de l'option `'_'` (voir aussi PEP 515).

Modifié dans la version 3.14: Support the grouping option for the fractional part.

Finalement, le spécificateur type détermine comment la donnée doit être représentée.

Les types disponibles de représentation de chaîne sont :

> Type | Signification
> --- | ---
> `'s'` | Format de chaîne. C'est le type par défaut pour les chaînes de caractères et peut être omis.
> `None` | Pareil que `'s'`.

Les types disponibles de représentation d'entier sont :

> Type | Signification
> --- | ---
> `'b'` | Format binaire. Affiche le nombre en base 2.
> `'c'` | Caractère. Convertit l'entier en caractère Unicode associé avant de l'afficher.
> `'d'` | Entier décimal. Affiche le nombre en base 10.
> `'o'` | Format octal. Affiche le nombre en base 8.
> `'x'` | Format hexadécimal. Affiche le nombre en base 16 en utilisant les lettres minuscules pour les chiffres au-dessus de 9.
> `'X'` | Format hexadécimal. Affiche le nombre en base 16 en utilisant les lettres majuscules pour les chiffres au-dessus de 9. Si `'#'` est présent, le préfixe `'0x'` est également passé en majuscules pour devenir `'0X'`.
> `'n'` | Number. This is the same as `'d'`, except that it uses the current locale setting to insert the appropriate digit group separators.
> `None` | Pareil que `'d'`.

In addition to the above presentation types, integers can be formatted with the floating-point presentation types listed below (except `'n'` and `None`). When doing so, `float()` is used to convert the integer to a floating-point number before formatting.

Les représentations possibles pour les `float` et les `Decimal` sont :

> Type | Signification
> --- | ---
> `'e'` | Scientific notation. For a given precision `p`, formats the number in scientific notation with the letter 'e' separating the coefficient from the exponent. The coefficient has one digit before and `p` digits after the decimal point, for a total of `p + 1` significant digits. With no precision given, uses a precision of `6` digits after the decimal point for `float`, and shows all coefficient digits for `Decimal`. If `p=0`, the decimal point is omitted unless the `#` option is used. For `float`, the exponent always contains at least two digits, and is zero if the value is zero.
> `'E'` | Notation scientifique. Pareil que `'e'` sauf que Python utilise la lettre majuscule 'E' comme séparateur.
> `'f'` | Fixed-point notation. For a given precision `p`, formats the number as a decimal number with exactly `p` digits following the decimal point. With no precision given, uses a precision of `6` digits after the decimal point for `float`, and uses a precision large enough to show all coefficient digits for `Decimal`. If `p=0`, the decimal point is omitted unless the `#` option is used.
> `'F'` | Virgule fixe. Pareil que `'f'` à part `nan` qui devient `NAN` et `inf` qui devient `INF`.
> `'g'` | Format général. Pour une précision donnée `p >= 1`, Python arrondit le nombre à `p` chiffres significatifs et puis formate le résultat soit en virgule fixe soit en notation scientifique, en fonction de la magnitude. Une précision de `0` est considérée équivalente à une précision de `1`. Les règles précises sont les suivantes : supposons que le résultat formaté avec le type de représentation `'e'` et une précision `p-1` ait un exposant `exp`. Alors, si `m <= exp <= p` où `m` vaut `–4` pour les nombres à virgule flottante et `–6` pour les `Decimals`, le nombre est formaté avec le type de représentation `'f'` et une précision `p-1-exp`. Sinon, le nombre est formaté avec le type de représentation `'e'` et une précision `p-1`. Dans les deux cas, les zéros finaux et non significatifs sont retirés, et la virgule est également retirée s'il n'y a aucun chiffre la suivant, sauf si l'option `'#'` est utilisée. Si la précision n'est pas donnée, utilise une précision de `6` chiffres significatifs pour les `float`. Pour les `Decimal`, la mantisse du résultat dépend de la valeur : la notation scientifique est utilisée pour les valeurs inférieures à `1e-6` en valeur absolue et pour celles dont le dernier chiffre significatif a une position supérieure à 1 ; dans les autres cas, la notation en virgule fixe est utilisée. Les valeurs suivantes : infini négatif, infini positif, zéro positif, zéro négatif, not a number sont formatées respectivement par `inf`, `-inf`, `0`, `-0` et `nan`, peu importe la précision.
> `'G'` | Format général. Pareil que `'G'` si ce n'est que `'E'` est utilisé si le nombre est trop grand. La représentation des infinis et de NaN sont en majuscules également.
> `'n'` | Number. This is the same as `'g'`, except that it uses the current locale setting to insert the appropriate digit group separators for the integral part of a number.
> `'%'` | Pourcentage. Multiplie le nombre par 100 et l'affiche en virgule fixe (`'f'`), suivi d'un symbole pourcent `'%'`.
> `None` | For `float` this is like the `'g'` type, except that when fixed-point notation is used to format the result, it always includes at least one digit past the decimal point, and switches to the scientific notation when `exp >= p - 1`. When the precision is not specified, the latter will be as large as needed to represent the given value faithfully. Pour les `Decimal`, c'est identique à `'g'` ou `'G'` en fonction de la valeur de `context.capitals` du contexte décimal courant. L'effet visé est de coller à la valeur renvoyée par `str()` telle que modifiée par les autres modificateurs de format.

The result should be correctly rounded to a given precision `p` of digits after the decimal point. The rounding mode for `float` matches that of the `round()` builtin. For `Decimal`, the rounding mode of the current context will be used.

The available presentation types for `complex` are the same as those for `float` (`'%'` is not allowed). Both the real and imaginary components of a complex number are formatted as floating-point numbers, according to the specified presentation type. They are separated by the mandatory sign of the imaginary part, the latter being terminated by a `j` suffix. If the presentation type is missing, the result will match the output of `str()` (complex numbers with a non-zero real part are also surrounded by parentheses), possibly altered by other format modifiers.

### Exemples de formats

Cette section contient des exemples de la syntaxe de `str.format()` et des comparaisons avec l'ancien formatage par `%`.

Dans la plupart des cas, la syntaxe est similaire à l'ancien formatage par `%`, avec l'ajout de `{}` et avec `:` au lieu de `%`. Par exemple : `'%03.2f'` peut être changé en `'{03.2f}'`.

La nouvelle syntaxe de formatage gère également de nouvelles options et des options différentes, montrées dans les exemples qui suivent.

Accéder à un argument par sa position :

    >>> '{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'

Accéder à un argument par son nom :

    >>> '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'

Accéder aux attributs d'un argument :

    >>> 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)'

Accéder aux éléments d'un argument :

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

Remplacer `%s` et `%r` :

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

Aligner le texte et spécifier une longueur minimale :

    >>> '{:<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***********'

Remplacer `%+f`, `%-f`, et `%f` et spécifier un signe :

    >>> '{:+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'

Remplacer `%x` et `%o` et convertir la valeur dans différentes bases :

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

Using the comma or the underscore as a digit group separator:

    >>> '{:,}'.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'

Exprimer un pourcentage :

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

Utiliser un formatage propre au type :

    >>> 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'

Arguments imbriqués et des exemples plus complexes :

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

## Template strings ($-strings)

Note

The feature described here was introduced in Python 2.4; a simple templating method based upon regular expressions. It predates `str.format()`, formatted string literals, and template string literals.

It is unrelated to template string literals (t-strings), which were introduced in Python 3.14. These evaluate to `string.templatelib.Template` objects, found in the `string.templatelib` module.

Template strings provide simpler string substitutions as described in PEP 292. A primary use case for template strings is for internationalization (i18n) since in that context, the simpler syntax and functionality makes it easier to translate than other built-in string formatting facilities in Python. As an example of a library built on template strings for i18n, see the flufl.i18n package.

Les chaînes modèles prennent en charge les substitutions basées sur `$` en utilisant les règles suivantes :

- `$$` est un échappement ; il est remplacé par un simple `$`.

- `$identifier` dénomme un substituant lié à la clef `"identifier"`. Par défaut, `"identifier"` est restreint à toute chaîne de caractères ASCII alphanumériques sensibles à la casse (avec les underscores) commençant avec un underscore ou un caractère alphanumérique. Le premier caractère n'étant pas un identifieur après le `$` termine la spécification du substituant.

- `${identifier}` est équivalent à `$identifier`. Cette notation est requise quand un caractère valide pour une clef de substituant suit directement le substituant mais ne fait pas partie du substituant, comme `"${noun}ification"`.

Tout autre présence du symbole `$` dans une chaîne résultera en la levée d'une `ValueError`.

Le module `string` fournit une classe `Template` qui implémente ces règles. Les méthodes de `Template` sont :

class string.Template(template)

  Le constructeur prend un seul argument qui est la chaîne du template.

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

    Applique les substitutions du template, et la renvoie dans une nouvelle chaîne. mapping est un objet dictionnaire-compatible qui lie les substituants dans le template. De même, vous pouvez fournir des arguments mot-clefs tels que les mot-clefs sont les substituants. Quand à la fois mapping et kwds sont donnés et qu'il y a des doublons, les substituants de kwds sont prioritaires.

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

    Comme `substitute()`, si ce n'est qu'au lieu de lever une `KeyError` si un substituant n'est ni dans mapping, ni dans kwds, c'est le nom du substituant inchangé qui apparaît dans la chaîne finale. Également, à l'inverse de `substitute()`, toute autre apparition de `$` renverra simplement `$` au lieu de lever une exception `ValueError`.

    Bien que d'autres exceptions peuvent toujours être levées, cette méthode est dite sûre car elle tente de toujours renvoyer une chaîne utilisable au lieu de lever une exception. Ceci dit, `safe_substitute()` est tout sauf sûre car elle ignore silencieusement toute malformation dans le template qui contient des délimiteurs fantômes, des accolades non fermées, ou des substituants qui ne sont pas des identificateurs Python valides.

  is_valid()

    Returns `False` if the template has invalid placeholders that will cause `substitute()` to raise `ValueError`.

    Ajouté dans la version 3.11.

  get_identifiers()

    Returns a list of the valid identifiers in the template, in the order they first appear, ignoring any invalid identifiers.

    Ajouté dans la version 3.11.

  Les instances de la classe `Template` fournissent également un attribut public :

  template

    C'est l'objet template passé comme argument au constructeur. En général, vous ne devriez pas le changer, mais un accès en lecture-seule n'est pas possible à fournir.

Voici un exemple de comment utiliser un 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'

Usage avancé : vous pouvez faire dériver vos sous-classes de `Template` pour personnaliser la syntaxe des substituants, les caractères délimiteurs, ou l'entièreté de l'expression rationnelle utilisée pour analyser les chaînes templates. Pour faire cela, vous pouvez redéfinir les attributs suivants :

- delimiter — La chaîne littérale décrivant le délimiteur pour introduire un substituant. Sa valeur par défaut est `$`. Notez qu'elle ne doit pas être une expression rationnelle, puisque l'implémentation appelle `re.escape()` sur cette chaîne si nécessaire. Notez aussi que le délimiteur ne peut pas être changé après la création de la classe.

- idpattern — L'expression rationnelle décrivant le motif pour les substituants non entourés d'accolades. La valeur par défaut de cette expression rationnelle est `(?a:[_a-z][_a-z0-9]*)`. Si idpattern est donné et braceidpattern est `None`, ce motif est aussi utilisé pour les marqueurs entre accolades.

  Note

  Puisque par défaut flags vaut `re.IGNORECASE`, des caractères non-ASCII peuvent correspondre au motif `[a-z]`. C'est pourquoi on utilise une option locale `a` ici.

  Modifié dans la version 3.7: braceidpattern peut être utilisé pour définir des motifs des motifs différents suivant qu’ils sont à l’intérieur ou à l’extérieur des accolades.

- braceidpattern — Similaire à idpattern mais décrit le motif quand il est placé entre accolades. La valeur par défaut est `None` ce qui signifie que seul idpattern est pris en compte (le motif est le même, qu’il soit à l’intérieur d’accolades ou non). S’il est donné, cela vous permet de définir des motifs entre accolades différents des motifs sans accolades.

  Ajouté dans la version 3.7.

- flags — L'indicateur d'expression rationnelle qui sera appliqué lors de la compilation de l'expression rationnelle pour reconnaître les substitutions. La valeur par défaut est `re.IGNORECASE`. Notez que `re.VERBOSE` sera toujours ajouté à l'indicateur. Donc, un idpattern personnalisé doit suivre les conventions des expressions rationnelles verbose.

  Ajouté dans la version 3.2.

Également, vous pouvez fournir le motif d'expression rationnelle en entier en redéfinissant l'attribut pattern. Si vous faites cela, la valeur doit être un objet 'expression rationnelle' avec quatre groupes de capture de noms. Les groupes de capture correspondent aux règles données au-dessus, ainsi qu'à la règle du substituant invalide :

- escaped — Ce groupe lie les séquences échappées (par exemple `$$`) dans le motif par défaut.

- named — Ce groupe lie les substituants non entourés d'accolades ; il ne devrait pas inclure le délimiteur dans le groupe de capture.

- braced — Ce groupe lie le nom entouré d'accolades ; il ne devrait inclure ni le délimiteur, ni les accolades dans le groupe de capture.

- invalid — Ce groupe lie tout autre motif de délimitation (habituellement, un seul délimiteur) et il devrait apparaître en dernier dans l'expression rationnelle.

The methods on this class will raise `ValueError` if the pattern matches the template without one of these named groups matching.

## Fonctions d'assistance

string.capwords(s, sep=None)

  Divise l'argument en mots en utilisant `str.split()`, capitalise chaque mot en utilisant `str.capitalize()` et assemble les mots capitalisés en utilisant `str.join()`. Si le second argument optionnel sep est absent ou vaut `None`, les séquences de caractères blancs sont remplacées par un seul espace et les espaces débutant et finissant la chaîne sont retirés. Sinon, sep et utilisé pour séparer et ré-assembler les mots.