"string" --- Common string operations
*************************************

**Code source :** Lib/string.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

   Chaîne de caractères ASCII considérés comme affichables. C'est une
   combinaison de "digits", "ascii_letters", "punctuation", et
   "whitespace".

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.

      Les valeurs dans le *n*-uplet représentent conceptuellement un
      ensemble de littéraux suivis d'un unique champ de remplacement.
      S'il n'y a pas de littéral, (ce qui peut arriver si deux champs
      de remplacement sont placés côte à côte), alors *literal_text*
      est une chaîne vide. S'il n'y a pas de champ de remplacement,
      les valeurs *field_name*, *format_spec* et *conversion* sont
      mises à "None".

   get_field(field_name, args, kwargs)

      Récupère le champ *field_name* du *n*-uplet renvoyé par
      "parse()" (voir ci-dessus), le convertit en un objet à formater.
      Renvoie une paire (*obj*, *used_key*). La version par défaut
      prend une chaîne de la forme définie par **PEP 3101**, telle que
      ""0[name]"" ou ""label.title"". *args* et *kwargs* sont tels que
      ceux passés à "vformat()". La valeur renvoyée *used_key* a le
      même sens que le paramètre *key* de "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
==============================

La méthode "str.format()" et la classe "Formatter" partagent la même
syntaxe pour les chaînes de formatage (bien que dans le cas de
"Formatter" les sous-classes puissent définir leur propre syntaxe).
La syntaxe est liée à celle des chaînes de formatage littérales, mais
elle est moins sophistiquée, et surtout ne permet pas d'inclure des
expressions arbitraires.

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

Les "Spécifications de format" sont utilisées avec les champs de
remplacement contenus dans les chaînes de formatage, pour définir
comment les valeurs doivent être représentées (voir Syntaxe de
formatage de chaîne et f-strings). Elles peuvent aussi être passées
directement à la fonction native "format()".  Chaque type *formatable*
peut définir comment les spécifications sur les valeurs de ce type
doivent être interprétées.

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     ::= [[fill]align][sign]["z"]["#"]["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" | "%"

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.  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                                              |
|===========|============================================================|
| "'+'"     | indique que le signe doit être affiché pour les nombres    |
|           | tant positifs que négatifs.                                |
+-----------+------------------------------------------------------------+
| "'-'"     | indique que le signe doit être affiché uniquement pour les |
|           | nombres négatifs (c'est le comportement par défaut).       |
+-----------+------------------------------------------------------------+
| espace    | indique qu'un espace doit précéder les nombres positifs et |
|           | qu'un signe moins doit précéder les nombres négatifs.      |
+-----------+------------------------------------------------------------+

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.

L'option "','" signale l'utilisation d'une virgule comme séparateur
des milliers. Pour un séparateur prenant en compte la configuration de
localisation, utilisez plutôt le type de présentation entière "'n'".

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

The "'_'" option signals the use of an underscore for a thousands
separator for floating-point presentation types and for integer
presentation type "'d'".  For integer presentation types "'b'", "'o'",
"'x'", and "'X'", underscores will be inserted every 4 digits.  For
other presentation types, specifying this option is an error.

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

*width* est un entier en base 10 qui définit la longueur minimale de
tout le champ, y compris les préfixes, séparateurs et autres
caractères de formatage. Si elle n'est pas spécifiée, alors le champ
*width* est déterminé par le contenu.

Quand aucun alignement explicite n'est donné, précéder le champ
*width* d'un caractère zéro ("'0'") active le remplissage par zéro des
types numériques selon leur signe.  Cela est équivalent à un caractère
de remplissage *fill* valant "'0'" avec le type d'alignement
*alignment* valant "'='".

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.

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'"     | Nombre. Pareil que "'d'" si ce n'est que ce sont les       |
   |           | paramètres de localisation qui sont utilisés afin de       |
   |           | déterminer le séparateur de nombres approprié.             |
   +-----------+------------------------------------------------------------+
   | "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'"     | Notation scientifique. Pour une précision donnée "p",      |
   |           | formate le nombre en notation scientifique avec la lettre  |
   |           | "'e'" séparant la mantisse de l'exposant. La mantisse      |
   |           | possède un chiffre devant et "p" chiffres après la virgule |
   |           | (représentée par un point en Python, conformément à la     |
   |           | convention anglo-saxonne), ce qui donne "p+1" chiffres     |
   |           | significatifs. Si la précision n'est pas donnée, utilise   |
   |           | une précision de "6" chiffres après la virgule pour les    |
   |           | "float" et affiche tous les chiffres de la mantisse pour   |
   |           | les "Decimal". S'il n'y a pas de chiffre après la virgule, |
   |           | la virgule (c.-à-d. le point décimal en Python) n'est pas  |
   |           | affichée à moins que l'option "#" ne soit utilisée.        |
   +-----------+------------------------------------------------------------+
   | "'E'"     | Notation scientifique. Pareil que "'e'" sauf que Python    |
   |           | utilise la lettre majuscule 'E' comme séparateur.          |
   +-----------+------------------------------------------------------------+
   | "'f'"     | Notation en virgule fixe. Pour une précision donnée "p",   |
   |           | formate le nombre sous la forme décimale avec exactement   |
   |           | "p" chiffres après la virgule (représentée par un point en |
   |           | Python, conformément à la convention anglo-saxonne). Si la |
   |           | précision n'est pas donnée, utilise une précision de "6"   |
   |           | chiffres après la virgule pour les "float" et affiche tous |
   |           | les chiffres pour les "Decimal". S'il n'y a pas de chiffre |
   |           | après la virgule, la virgule (c.-à-d. le point décimal en  |
   |           | Python) n'est pas affichée à moins que l'option "#" ne     |
   |           | soit utilisée.                                             |
   +-----------+------------------------------------------------------------+
   | "'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'"     | Nombre. Pareil que "'g'", si ce n'est que la configuration |
   |           | de localisation est prise en compte pour insérer le        |
   |           | séparateur approprié.                                      |
   +-----------+------------------------------------------------------------+
   | "'%'"     | Pourcentage. Multiplie le nombre par 100 et l'affiche en   |
   |           | virgule fixe ("'f'"), suivi d'un symbole pourcent "'%'".   |
   +-----------+------------------------------------------------------------+
   | "None"    | Pour les "float", c'est identique à "'g'", si ce n'est que |
   |           | lorsque la notation en virgule fixe est utilisée, il y a   |
   |           | toujours au moins un chiffre après la virgule. La          |
   |           | précision utilisée est celle nécessaire pour afficher la   |
   |           | valeur donnée fidèlement.  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.       |
   +-----------+------------------------------------------------------------+


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'

Utiliser une virgule comme séparateur des milliers :

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

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


Chaînes modèles
===============

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.
