7.1. string — Opérations usuelles sur des chaînes

Code source : Lib/string.py

---

The string module contains a number of useful constants and classes, as well as some deprecated legacy functions that are also available as methods on strings. In addition, Python’s built-in string classes support the sequence type methods described in the Sequence Types — str, unicode, list, tuple, bytearray, buffer, xrange section, and also the string-specific methods described in the Méthodes de chaînes de caractères section. To output formatted strings use template strings or the % operator described in the String Formatting Operations section. Also, see the re module for string functions based on regular expressions.

7.1.1. 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 l’environnement linguistique.

string.ascii_lowercase

Les lettres minuscules 'abcdefghijklmnopqrstuvwxyz. Cette valeur de dépend pas de l’environnement linguistique et ne changera pas.

string.ascii_uppercase

Les lettres majuscules 'ABCDEFGHIJKLMNOPQRSTUVWXYZ'. Cette valeur de dépend pas de l’environnement linguistique et ne changera pas.

string.digits

La chaîne '0123456789'.

string.hexdigits

La chaîne '0123456789abcdefABCDEF'.

string.letters

The concatenation of the strings lowercase and uppercase described below. The specific value is locale-dependent, and will be updated when locale.setlocale() is called.

string.lowercase

A string containing all the characters that are considered lowercase letters. On most systems this is the string 'abcdefghijklmnopqrstuvwxyz'. The specific value is locale-dependent, and will be updated when locale.setlocale() is called.

string.octdigits

La chaîne '01234567.

string.punctuation

Chaîne de caractères ASCII considérés comme ponctuation dans l’environnement linguistique C.

string.printable

String of characters which are considered printable. This is a combination of digits, letters, punctuation, and whitespace.

string.uppercase

A string containing all the characters that are considered uppercase letters. On most systems this is the string 'ABCDEFGHIJKLMNOPQRSTUVWXYZ'. The specific value is locale-dependent, and will be updated when locale.setlocale() is called.

string.whitespace

A string containing all characters that are considered whitespace. On most systems this includes the characters space, tab, linefeed, return, formfeed, and vertical tab.

7.1.2. Formatage personnalisé de chaîne

Nouveau dans la version 2.6.

The built-in str and unicode classes provide the ability to do complex variable substitutions and value formatting via the str.format() method described in PEP 3101. The Formatter class in the string module allows you to create and customize your own string formatting behaviors using the same implementation as the built-in format() method.

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().

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 tuples (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 tuple 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 tuple renvoyé par parse() (voir ci-dessus), le convertit en un objet à formater. Renvoie un tuple (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 la 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 puisse la redéfinir.

convert_field(value, conversion)

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

7.1.3. Syntaxe de formatage de chaîne

La méthode str.format() et la classe Formatter utilisent la même syntaxe pour le formatage de chaînes (même si pour Formatter, les sous-classes peuvent définir leur propre syntaxe de chaînes de format).

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éfini comme suit :

replacement_field ::=  "{" [field_name] ["!" conversion] [":" format_spec] "}"
field_name        ::=  arg_name ("." attribute_name | "[" element_index "]")*
arg_name          ::=  [identifier | integer]
attribute_name    ::=  identifier
element_index     ::=  integer | index_string
index_string      ::=  <any source character except "]"> +
conversion        ::=  "r" | "s"
format_spec       ::=  <described in the next section>

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.

Le champ field_name débute par un arg_name qui est soit un nombre, soit un mot-clef. Si c’est un nombre, il fait référence à un des arguments positionnels et si c’est un mot-clef, il fait référence à un des arguments nommés. Si les valeurs numériques de arg_name dans une chaîne de format sont 0, 1, 2, … dans l’ordre, elles peuvent être omises (toutes ou aucune), et les nombres 0, 1, 2, … seront automatiquement insérés dans cet ordre. Puisque arg_name n’est pas délimité par des guillemets, il n’est pas possible de spécifier des clefs de dictionnaire arbitraires (par exemple les chaînes '10' ou ':-]') dans une chaîne de format. La valeur arg_name peut être suivie par un nombre d’indices ou d’expressions quelconque. Une expression de la forme '.name' sélectionne l’attribut nommé en utilisant getattr() alors qu’une expression de la forme '[index]' recherche l’indice en utilisant __getitem__().

Modifié dans la version 2.7: The positional argument specifiers can be omitted for str.format() and unicode.format(), so '{} {}' is equivalent to '{0} {1}', u'{} {}' is equivalent to u'{0} {1}'.

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

Le champ conversion crée une contrainte de type avant de formater. Normalement, le travail de formatage d’une valeur est fait par la méthode __format__() de la valeur elle-même. Cependant, dans certains cas, il est désirable de forcer un type à être formaté en une chaîne, en ré-définissant sa propre définition de formatage. En convertissant une valeur en chaîne de caractère avant d’appeler la méthode __format__(), on outrepasse la logique usuelle de formatage.

Two conversion flags are currently supported: '!s' which calls str() on the value, and '!r' which calls repr().

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

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

7.1.3.1. Mini-langage de spécification de format

Les « spécifications de format » sont utilisées pour les champs de remplacement contenus dans une chaîne de format pour définir comment la valeur doit être représentée (voir Syntaxe de formatage de chaîne). Elles peuvent également être passées directement à la primitive format(). Chaque type formatable peut définir comment interpréter la spécification de format.

La plupart des primitives implémentent les les options suivantes, même si certaines options de formatage ne sont supportées 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 typiquement le résultat.

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

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

Si une valeur align valide est spécifiée, la valeur peut être représentée par un caractère fill de remplissage qui peut être n’importe quel caractère et qui vaut espace par défaut si il est omis. Il est impossible d’utiliser un littéral “accolade” (« { » ou « } ») en tant que caractère fill quand la méthode str.format() est utilisée. Cependant, il est possible d’insérer une accolade avec un champ de remplacement imbriqué. Cette limite 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).
'='	Force le remplissage (padding) à être placé après le signe (si signe il y a) mais avant les chiffres. L’option est utilisée pour afficher les champs sous la forme « +000000120 ». Cette option d’alignement est valide uniquement pour les types numériques. Elle devient activée par défaut quand « 0 » précède directement la largeur de champ.
'^'	Force le champ à être centré dans l’espace disponible.

Notons que la longueur du champ est toujours égale à la 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 type 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 '#' option is only valid for integers, and only for binary, octal, or hexadecimal output. If present, it specifies that the output will be prefixed by '0b', '0o', or '0x', respectively.

L’option ',' signale l’utilisation d’une virgule comme séparateur des milliers. Pour un séparateur conscient de l’environnement linguistique, utilisez plutôt le type de présentation entière 'n'.

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

width est un entier en base 10 qui définit la longueur minimale du champ. 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 champs 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 '='.

La valeur precision est un nombre en base 10 indiquant combien de chiffres doivent être affichés après la virgule pour une valeur à virgule flottante formatée avec 'f' ou 'F', ou avant et après le point-décimal pour une valeur à virgule flottante formatée avec 'g' ou 'G'. Pour les types non numériques, ce champ indique la taille maximale du champ, autrement dit, combien de caractères du champ sont utilisés. Le spécificateur precision n’est pas autorisé sur les entiers.

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 le 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.
'n'	Nombre. Pareil que 'd' si ce n’est que l’environnement linguistique est utilisé afin de déterminer le séparateur de nombres approprié.
None	Pareil que 'd'.

En plus des types de représentation ci-dessus, les entiers peuvent aussi être formatés avec les types de représentation des flottants listés ci-dessous (à l’exception de 'n' et None). Dans ce cas, la fonction float() est utilisée pour convertir l’entier en flottant avant le formatage.

les types de représentation pour les nombres flottants et les valeurs décimales sont :

Type	Signification
'e'	Notation par exposant. Affiche le nombre dans sa notation scientifique en utilisant la lettre “e” pour indiquer l’exposant. La précision par défaut est 6.
'E'	Notation par exposant. Pareil que 'e' sauf l’utilisation de la lettre majuscule “E” comme séparateur.
'f'	Fixed-point notation. Displays the number as a fixed-point number. The default precision is 6.
'F'	Fixed point notation. Same as 'f'.
'g'	Format général. Pour une précision donnée p >= 1, ceci 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. 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 1 ait un exposant exp. Alors, si -4 <= exp <= p, 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. 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. Une précision de 0 est interprétée comme une précision de 1. La précision par défaut est 6.
'G'	Format général. Pareil que 'G' si ce n’est que 'E' est utilisé si le nombre est trop grand. Également, la représentation des infinis et de Nan sont en majuscules également.
'n'	Nombre. Pareil que 'g', si ce n’est que l’environnement linguistique est pris 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	The same as 'g'.

7.1.3.2. 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 cases, 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}'.

The new format syntax also supports new and different options, shown in the following examples.

Accéder à un argument par sa position :

>>> '{0}, {1}, {2}'.format('a', 'b', 'c')
'a, b, c'
>>> '{}, {}, {}'.format('a', 'b', 'c')  # 2.7+ 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(object):
...     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.5
>>> total = 22
>>> 'Correct answers: {:.2%}'.format(points/total)
'Correct answers: 88.64%'

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),
...     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

7.1.4. Chaînes modèles

Nouveau dans la version 2.4.

Les modèles (templates) fournissent des substitutions de chaînes plus simples comme décrit dans PEP 292. À la place des substitutions habituelles basées sur %, les Templates supportent les substitutions basées sur $ en utilisant les règles suivantes :

• $$ est un échappement ; il est remplacé par un simple $.

• $identifier names a substitution placeholder matching a mapping key of "identifier". By default, "identifier" must spell a Python identifier. The first non-identifier character after the $ character terminates this placeholder specification.

• ${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[, **kws])

Performs the template substitution, returning a new string. mapping is any dictionary-like object with keys that match the placeholders in the template. Alternatively, you can provide keyword arguments, where the keywords are the placeholders. When both mapping and kws are given and there are duplicates, the placeholders from kws take precedence.

safe_substitute(mapping[, **kws])

Like substitute(), except that if placeholders are missing from mapping and kws, instead of raising a KeyError exception, the original placeholder will appear in the resulting string intact. Also, unlike with substitute(), any other appearances of the $ will simply return $ instead of raising ValueError.

While other exceptions may still occur, this method is called « safe » because it always tries to return a usable string instead of raising an exception. In another sense, safe_substitute() may be anything other than safe, since it will silently ignore malformed templates containing dangling delimiters, unmatched braces, or placeholders that are not valid Python identifiers.

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 ests $. Notez qu’il ne doit pas être une expression rationnelle, puisque l’implémentation appellera re.escape() sur cette chaîne si nécessaire.

• idpattern – L’expression rationnelle décrivant le motif pour les substituants non entourés d’accolades (les accolades sont ajoutées automatiquement si c’est approprié). La valeur par défaut de cette expression rationnelle est [_a-z][_a-z0-9]*.

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

7.1.5. String functions

The following functions are available to operate on string and Unicode objects. They are not available as string methods.

string.capwords(s[, sep])

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.

string.maketrans(from, to)

Return a translation table suitable for passing to translate(), that will map each character in from into the character at the same position in to; from and to must have the same length.

Note

Don’t use strings derived from lowercase and uppercase as arguments; in some locales, these don’t have the same length. For case conversions, always use str.lower() and str.upper().

7.1.6. Deprecated string functions

The following list of functions are also defined as methods of string and Unicode objects; see section Méthodes de chaînes de caractères for more information on those. You should consider these functions as deprecated, although they will not be removed until Python 3. The functions defined in this module are:

string.atof(s)

Obsolète depuis la version 2.0: Use the float() built-in function.

Convert a string to a floating point number. The string must have the standard syntax for a floating point literal in Python, optionally preceded by a sign (+ or -). Note that this behaves identical to the built-in function float() when passed a string.

Note

When passing in a string, values for NaN and Infinity may be returned, depending on the underlying C library. The specific set of strings accepted which cause these values to be returned depends entirely on the C library and is known to vary.

string.atoi(s[, base])

Obsolète depuis la version 2.0: Use the int() built-in function.

Convert string s to an integer in the given base. The string must consist of one or more digits, optionally preceded by a sign (+ or -). The base defaults to 10. If it is 0, a default base is chosen depending on the leading characters of the string (after stripping the sign): 0x or 0X means 16, 0 means 8, anything else means 10. If base is 16, a leading 0x or 0X is always accepted, though not required. This behaves identically to the built-in function int() when passed a string. (Also note: for a more flexible interpretation of numeric literals, use the built-in function eval().)

string.atol(s[, base])

Obsolète depuis la version 2.0: Use the long() built-in function.

Convert string s to a long integer in the given base. The string must consist of one or more digits, optionally preceded by a sign (+ or -). The base argument has the same meaning as for atoi(). A trailing l or L is not allowed, except if the base is 0. Note that when invoked without base or with base set to 10, this behaves identical to the built-in function long() when passed a string.

string.capitalize(word)

Return a copy of word with only its first character capitalized.

string.expandtabs(s[, tabsize])

Expand tabs in a string replacing them by one or more spaces, depending on the current column and the given tab size. The column number is reset to zero after each newline occurring in the string. This doesn’t understand other non-printing characters or escape sequences. The tab size defaults to 8.

string.find(s, sub[, start[, end]])

Return the lowest index in s where the substring sub is found such that sub is wholly contained in s[start:end]. Return -1 on failure. Defaults for start and end and interpretation of negative values is the same as for slices.

string.rfind(s, sub[, start[, end]])

Like find() but find the highest index.

string.index(s, sub[, start[, end]])

Like find() but raise ValueError when the substring is not found.

string.rindex(s, sub[, start[, end]])

Like rfind() but raise ValueError when the substring is not found.

string.count(s, sub[, start[, end]])

Return the number of (non-overlapping) occurrences of substring sub in string s[start:end]. Defaults for start and end and interpretation of negative values are the same as for slices.

string.lower(s)

Return a copy of s, but with upper case letters converted to lower case.

string.split(s[, sep[, maxsplit]])

Return a list of the words of the string s. If the optional second argument sep is absent or None, the words are separated by arbitrary strings of whitespace characters (space, tab, newline, return, formfeed). If the second argument sep is present and not None, it specifies a string to be used as the word separator. The returned list will then have one more item than the number of non-overlapping occurrences of the separator in the string. If maxsplit is given, at most maxsplit number of splits occur, and the remainder of the string is returned as the final element of the list (thus, the list will have at most maxsplit+1 elements). If maxsplit is not specified or -1, then there is no limit on the number of splits (all possible splits are made).

The behavior of split on an empty string depends on the value of sep. If sep is not specified, or specified as None, the result will be an empty list. If sep is specified as any string, the result will be a list containing one element which is an empty string.

string.rsplit(s[, sep[, maxsplit]])

Return a list of the words of the string s, scanning s from the end. To all intents and purposes, the resulting list of words is the same as returned by split(), except when the optional third argument maxsplit is explicitly specified and nonzero. If maxsplit is given, at most maxsplit number of splits – the rightmost ones – occur, and the remainder of the string is returned as the first element of the list (thus, the list will have at most maxsplit+1 elements).

Nouveau dans la version 2.4.

string.splitfields(s[, sep[, maxsplit]])

This function behaves identically to split(). (In the past, split() was only used with one argument, while splitfields() was only used with two arguments.)

string.join(words[, sep])

Concatenate a list or tuple of words with intervening occurrences of sep. The default value for sep is a single space character. It is always true that string.join(string.split(s, sep), sep) equals s.

string.joinfields(words[, sep])

This function behaves identically to join(). (In the past, join() was only used with one argument, while joinfields() was only used with two arguments.) Note that there is no joinfields() method on string objects; use the join() method instead.

string.lstrip(s[, chars])

Return a copy of the string with leading characters removed. If chars is omitted or None, whitespace characters are removed. If given and not None, chars must be a string; the characters in the string will be stripped from the beginning of the string this method is called on.

Modifié dans la version 2.2.3: The chars parameter was added. The chars parameter cannot be passed in earlier 2.2 versions.

string.rstrip(s[, chars])

Return a copy of the string with trailing characters removed. If chars is omitted or None, whitespace characters are removed. If given and not None, chars must be a string; the characters in the string will be stripped from the end of the string this method is called on.

Modifié dans la version 2.2.3: The chars parameter was added. The chars parameter cannot be passed in earlier 2.2 versions.

string.strip(s[, chars])

Return a copy of the string with leading and trailing characters removed. If chars is omitted or None, whitespace characters are removed. If given and not None, chars must be a string; the characters in the string will be stripped from the both ends of the string this method is called on.

Modifié dans la version 2.2.3: The chars parameter was added. The chars parameter cannot be passed in earlier 2.2 versions.

string.swapcase(s)

Return a copy of s, but with lower case letters converted to upper case and vice versa.

string.translate(s, table[, deletechars])

Delete all characters from s that are in deletechars (if present), and then translate the characters using table, which must be a 256-character string giving the translation for each character value, indexed by its ordinal. If table is None, then only the character deletion step is performed.

string.upper(s)

Return a copy of s, but with lower case letters converted to upper case.

string.ljust(s, width[, fillchar])

string.rjust(s, width[, fillchar])

string.center(s, width[, fillchar])

These functions respectively left-justify, right-justify and center a string in a field of given width. They return a string that is at least width characters wide, created by padding the string s with the character fillchar (default is a space) until the given width on the right, left or both sides. The string is never truncated.

string.zfill(s, width)

Pad a numeric string s on the left with zero digits until the given width is reached. Strings starting with a sign are handled correctly.

string.replace(s, old, new[, maxreplace])

Return a copy of string s with all occurrences of substring old replaced by new. If the optional argument maxreplace is given, the first maxreplace occurrences are replaced.