4. Types natifs¶
Les sections suivantes décrivent les types standards intégrés à l’interpréteur.
Les principaux types natifs sont les numériques, les séquences, les dictionnaires, les classes, les instances et les exceptions.
Certaines classes de collection sont mutables. Les méthodes qui ajoutent, retirent, ou réorganisent leurs éléments sur place, et qui ne renvoient pas un élément spécifique, ne renvoient jamais l’instance de la collection elle-même, mais None
.
Certaines opérations sont prises en charge par plusieurs types d’objets; en particulier, pratiquement tous les objets peuvent être comparés, testés (valeur booléenne), et convertis en une chaîne (avec la fonction repr()
ou la fonction légèrement différente str()
). Cette dernière est implicitement utilisée quand un objet est écrit par la fonction print()
.
4.1. Valeurs booléennes¶
Tout objet peut être testé typiquement dans une condition if
ou while
ou comme opérande des opérations booléennes ci-dessous. Les valeurs suivantes sont considérées comme fausses :
None
False
zéro de tout type numérique, par exemple,
0
,0.0
,0j
.toute séquence vide, par exemple,
''
,()
,[]
.toute dictionnaire vide, par exemple,
{}
.pour les instances de classes définies par l’utilisateur, si la classe définit une méthode
__bool__()
ou__len__()
, lorsque cette méthode renvoie le nombre entier zéro ou la valeurFalse
de la classebool
. [1]
Toutes les autres valeurs sont considérées comme vraies — donc des objets de beaucoup de types sont toujours vrais.
Les opérations et fonctions natives dont le résultat est booléen donnent toujours 0
ou False
pour faux et 1
ou True
pour vrai, sauf indication contraire. (Exception importante : les opérations booléennes or
et and
renvoient toujours l’une de leurs opérandes.)
4.2. Opérations booléennes — and
, or
, not
¶
Ce sont les opérations booléennes, classées par priorité ascendante :
Opération | Résultat | Notes |
---|---|---|
x or y |
si x est faux, alors y, sinon x | (1) |
x and y |
si x est faux, alors x, sinon y | (2) |
not x |
si x est faux, alors True , sinon False |
(3) |
Notes :
- This is a short-circuit operator, so it only evaluates the second
argument if the first one is
False
. - This is a short-circuit operator, so it only evaluates the second
argument if the first one is
True
. not
a une priorité inférieure à celle des opérateurs non-booléens, doncnot a == b
est interprété commenot (a == b)
eta == not b
est une erreur de syntaxe.
4.3. Comparaisons¶
Il y a huit opérations de comparaison en Python. Elles ont toutes la même priorité (qui est supérieure à celle des opérations booléennes). Les comparaisons peuvent être enchaînées arbitrairement; par exemple, x < y <= z
est équivalent à x < y and y <= z
, sauf que y n’est évalué qu’une seule fois (mais dans les deux cas z n’est pas évalué du tout quand x < y
est faux).
Ce tableau résume les opérations de comparaison :
Opération | Signification |
---|---|
< |
strictement inférieur |
<= |
inférieur ou égal |
> |
strictement supérieur |
>= |
supérieur ou égal |
== |
égal |
!= |
différent |
is |
identité d’objet |
is not |
contraire de l’identité d’objet |
Les objets de différents types, à l’exception de différents types numériques, ne peuvent en aucun cas être égaux. En outre, certains types (par exemple, les objets fonction) ne gèrent qu’une une notion dégénérée de la comparaisonoù deux objets de ce type sont inégaux. Les opérateurs <
, <=
, >
et >=
lèvent une exception TypeError
lorsqu’on compare un nombre complexe avec un autre type natif numérique, lorsque les objets sont de différents types qui ne peuvent pas être comparés, ou dans d’autres cas où il n’y a pas d’ordre défini.
Des instances différentes d’une classe sont normalement considérées différentes à moins que la classe ne définisse la méthode __eq__()
.
Les instances d’une classe ne peuvent pas être ordonnées par rapport à d’autres instances de la même classe, ou d’autres types d’objets, à moins que la classe ne définisse suffisamment de méthodes parmi __lt__()
, __le__()
, __gt__()
et __ge__()
(en général, __lt__()
et __eq__()
sont suffisantes, si vous voulez les significations classiques des opérateurs de comparaison).
Le comportement des opérateurs is
et is not
ne peut pas être personnalisé; aussi ils peuvent être appliqués à deux objets quelconques et ne soulèvent jamais d’exception.
Deux autres opérations avec la même priorité syntaxique, in
et not in
, sont pris en charge uniquement par des types séquence (ci-dessous).
4.4. Types numériques — int
, float
, complex
¶
Il existe trois types numériques distincts: integers, floating point numbers et complex numbers. En outre, les booléens sont un sous-type des entiers. Les entiers ont une précision illimitée. Les nombres à virgule flottante sont généralement implémentés en utilisant des double
en C; des informations sur la précision et la représentation interne des nombres à virgule flottante pour la machine sur laquelle le programme est en cours d’exécution est disponible dans sys.float_info
. Les nombres complexes ont une partie réelle et une partie imaginaire, qui sont chacunes des nombres à virgule flottante. Pour extraire ces parties d’un nombre complexe z, utilisez z.real
et z.imag
. (La bibliothèque standard comprend d’autres types numériques, fractions
qui stocke des rationnels et decimal
qui stocke les nombres à virgule flottante avec une précision définissable par l’utilisateur.)
Les nombres sont créés par des littéraux numériques ou sont le résultat de fonctions natives ou d’opérateurs. Les entiers littéraux basiques (y compris leur forme hexadécimale, octale et binaire) donnent des entiers. Les nombres littéraux contenant un point décimal ou un exposant donnent des nombres à virgule flottante. Suffixer 'j'
ou 'J'
à un nombre littéral donne un nombre imaginaire (un nombre complexe avec une partie réelle nulle) que vous pouvez ajouter à un nombre entier ou un à virgule flottante pour obtenir un nombre complexe avec une partie réelle et une partie imaginaire.
Python gère pleinement l’arithmétique mixte : quand un opérateur arithmétique binaire a des opérandes de types numériques différents, l’opérande avec le type « le plus étroit » est élargie au type de l’autre, où l’entier est plus étroit que la virgule flottante, qui est plus étroite que les complexes. Les comparaisons entre des nombres de type mixte utilisent la même règle. [2] Les constructeurs int()
, float()
et complex()
peuvent être utilisé pour produire des nombres d’un type spécifique.
Tous les types numériques (sauf complexe) gèrent les opérations suivantes, classées par priorité ascendante (toutes les opérations numériques ont une priorité plus élevée que les opérations de comparaison) :
Opération | Résultat | Notes | Documentation complète |
---|---|---|---|
x + y |
somme de x et y | ||
x - y |
différence de x et y | ||
x * y |
produit de x et y | ||
x / y |
quotient de x et y | ||
x // y |
quotient entier de x et y | (1) | |
x % y |
reste de x / y |
(2) | |
-x |
négatif de x | ||
+x |
x inchangé | ||
abs(x) |
valeur absolue de x | abs() |
|
int(x) |
x converti en nombre entier | (3)(6) | int() |
float(x) |
x converti en nombre à virgule flottante | (4)(6) | float() |
complex(re, im) |
un nombre complexe avec re pour partie réelle et im pour partie imaginaire. im vaut zéro par défaut. | (6) | complex() |
c.conjugate() |
conjugué du nombre complexe c | ||
divmod(x, y) |
la paire (x // y, x % y) |
(2) | divmod() |
pow(x, y) |
x à la puissance y | (5) | pow() |
x ** y |
x à la puissance y | (5) |
Notes :
Également appelé division entière. La valeur résultante est un nombre entier, bien que le type du résultat ne soit pas nécessairement int. Le résultat est toujours arrondi vers moins l’infini :
1//2
vaut0
,(-1)//2
vaut-1
,1//(-2)
vaut-1
, et(-1)//(-2)
vaut0
.Pas pour les nombres complexes. Convertissez-les plutôt en nombres flottants à l’aide de
abs()
si c’est approprié.La conversion de virgule flottante en entier peut arrondir ou tronquer comme en C; voir les fonctions
math.floor()
etmath.ceil()
pour des conversions bien définies.float accepte aussi les chaînes « nan » et « inf » avec un préfixe optionnel « + » ou « - » pour Not a Number (NaN) et les infinis positif ou négatif.
Python définit
pow(0, 0)
et0 ** 0
valant1
, puisque c’est courant pour les langages de programmation, et logique.Les littéraux numériques acceptés comprennent les chiffres
0
à9
ou tout équivalent Unicode (caractères avec la propriétéNd
).See http://www.unicode.org/Public/7.0.0/ucd/extracted/DerivedNumericType.txt for a complete list of code points with the
Nd
property.
Tous types numbers.Real
(int
et float
) comprennent également les opérations suivantes :
Opération | Résultat | Notes |
---|---|---|
math.trunc(x) |
x truncated to Integral | |
round(x[, n]) |
x rounded to n digits, rounding half to even. If n is omitted, it defaults to 0. | |
math.floor(x) |
the greatest integral float <= x | |
math.ceil(x) |
the least integral float >= x |
Pour d’autres opérations numériques voir les modules math
et cmath
.
4.4.1. Opérations sur les bits des nombres entiers¶
Bitwise operations only make sense for integers. Negative numbers are treated as their 2’s complement value (this assumes a sufficiently large number of bits that no overflow occurs during the operation).
Les priorités de toutes les opération à deux opérandes sur des bits sont inférieures aux opérations numériques et plus élevées que les comparaisons; l’opération unaire ~
a la même priorité que les autres opérations numériques unaires (+
et -
).
Ce tableau répertorie les opérations binaires triées par priorité ascendante :
Opération | Résultat | Notes |
---|---|---|
x | y |
ou <or> binaire de x et y | |
x ^ y |
ou <or> exclusive binaire de x et y | |
x & y |
et binaire <and> de x et y | |
x << n |
x décalé vers la gauche de n bits | (1)(2) |
x >> n |
x décalé vers la droite de n bits | (1)(3) |
~x |
les bits de x, inversés |
Notes :
- Des valeurs de décalage négatives sont illégales et provoquent une exception
ValueError
. - Un décalage à gauche de n bits est équivalent à la multiplication par
pow(2, n)
sans vérification de débordement. - Un décalage à droite de n les bits est équivalent à la division par
pow(2, n)
sans vérification de débordement.
4.4.2. Méthodes supplémentaires sur les entiers¶
Le type int implémente la classe de base abstraite numbers.Integral
. Il fournit aussi quelques autres méthodes :
-
int.
bit_length
()¶ Renvoie le nombre de bits nécessaires pour représenter un nombre entier en binaire, à l’exclusion du signe et des zéros non significatifs :
>>> n = -37 >>> bin(n) '-0b100101' >>> n.bit_length() 6
Plus précisément, si
x
est différent de zéro,x.bit_length()
est le nombre entier positif unique,k
tel que2**(k-1) <= abs(x) < 2**k
. Équivalemment, quandabs(x)
est assez petit pour avoir un logarithme correctement arrondi,k = 1 + int(log(abs(x), 2))
. Six
est nul, alorsx.bit_length()
donne0
.Équivalent à :
def bit_length(self): s = bin(self) # binary representation: bin(-37) --> '-0b100101' s = s.lstrip('-0b') # remove leading zeros and minus sign return len(s) # len('100101') --> 6
Nouveau dans la version 3.1.
-
int.
to_bytes
(length, byteorder, *, signed=False)¶ Retourne un tableau d’octets représentant un nombre entier.
>>> (1024).to_bytes(2, byteorder='big') b'\x04\x00' >>> (1024).to_bytes(10, byteorder='big') b'\x00\x00\x00\x00\x00\x00\x00\x00\x04\x00' >>> (-1024).to_bytes(10, byteorder='big', signed=True) b'\xff\xff\xff\xff\xff\xff\xff\xff\xfc\x00' >>> x = 1000 >>> x.to_bytes((x.bit_length() // 8) + 1, byteorder='little') b'\xe8\x03'
L’entier est représenté par length octets. Une exception
OverflowError
est levée s’il n’est pas possible de représenter l’entier avec le nombre d’octets donnés.L’argument byteorder détermine l’ordre des octets utilisé pour représenter le nombre entier. Si byteorder est
"big"
, l’octet le plus significatif est au début du tableau d’octets. Si byteorder est"little"
, l’octet le plus significatif est à la fin du tableau d’octets. Pour demander l’ordre natif des octets du système hôte, donnezsys.byteorder
comme byteorder.L’argument signed détermine si le complément à deux est utilisé pour représenter le nombre entier. Si signed est
False
et qu’un entier négatif est donné, une exceptionOverflowError
est levée. La valeur par défaut pour signed estFalse
.Nouveau dans la version 3.2.
-
classmethod
int.
from_bytes
(bytes, byteorder, *, signed=False)¶ Done le nombre entier représenté par le tableau d’octets fourni.
>>> int.from_bytes(b'\x00\x10', byteorder='big') 16 >>> int.from_bytes(b'\x00\x10', byteorder='little') 4096 >>> int.from_bytes(b'\xfc\x00', byteorder='big', signed=True) -1024 >>> int.from_bytes(b'\xfc\x00', byteorder='big', signed=False) 64512 >>> int.from_bytes([255, 0, 0], byteorder='big') 16711680
L’argument bytes doit être soit un bytes-like object soit un itérable produisant des bytes.
L’argument byteorder détermine l’ordre des octets utilisé pour représenter le nombre entier. Si byteorder est
"big"
, l’octet le plus significatif est au début du tableau d’octets. Si byteorder est"little"
, l’octet le plus significatif est à la fin du tableau d’octets. Pour demander l’ordre natif des octets du système hôte, donnezsys.byteorder
comme byteorder.L’argument signed indique si le complément à deux est utilisé pour représenter le nombre entier.
Nouveau dans la version 3.2.
4.4.3. Méthodes supplémentaires sur les nombres à virgule flottante¶
Le type float implémente la classe de base abstraite numbers.Real
et a également les méthodes suivantes.
-
float.
as_integer_ratio
()¶ Renvoie une paire de nombres entiers dont le rapport est exactement égal au nombre d’origine et avec un dénominateur positif. Lève
OverflowError
avec un infini etValueError
avec un NaN.
-
float.
is_integer
()¶ Donne
True
si l’instance de float est finie avec une valeur entière, etFalse
autrement :>>> (-2.0).is_integer() True >>> (3.2).is_integer() False
Deux méthodes prennent en charge la conversion vers et à partir de chaînes hexadécimales. Étant donné que les float de Python sont stockés en interne sous forme de nombres binaires, la conversion d’un float depuis ou vers une chaine décimale implique généralement une petite erreur d’arrondi. En revanche, les chaînes hexadécimales permettent de représenter exactement les nombres à virgule flottante. Cela peut être utile lors du débogage, et dans un travail numérique.
-
float.
hex
()¶ Donne une représentation d’un nombre à virgule flottante sous forme de chaîne hexadécimale. Pour les nombres à virgule flottante finis, cette représentation comprendra toujours un préfixe
0x
, un suffixep
, et un exposant.
-
classmethod
float.
fromhex
(s)¶ Méthode de classe pour obtenir le float représenté par une chaîne de caractères hexadécimale s. La chaîne s peut contenir des espaces avant et après le chiffre.
Notez que float.hex()
est une méthode d’instance, alors que float.fromhex()
est une méthode de classe.
Une chaîne hexadécimale prend la forme :
[sign] ['0x'] integer ['.' fraction] ['p' exponent]
où sign
peut être soit +
soit -
, integer
et fraction
sont des chaînes de chiffres hexadécimales, et exponent
est un entier décimal facultativement signé. La casse n’est pas significative, et il doit y avoir au moins un chiffre hexadécimal soit dans le nombre entier soit dans la fraction. Cette syntaxe est similaire à la syntaxe spécifiée dans la section 6.4.4.2 de la norme C99, et est aussi la syntaxe utilisée à partir de Java 1.5. En particulier, la sortie de float.hex()
est utilisable comme valeur hexadécimale à virgule flottante littérale en C ou Java, et des chaînes hexadécimales produites en C via un format %a
ou Java via Double.toHexString
sont acceptées par float.fromhex()
.
Notez que l’exposant est écrit en décimal plutôt qu’en hexadécimal, et qu’il donne la puissance de 2 par lequel multiplier le coefficient. Par exemple, la chaîne hexadécimale 0x3.a7p10
représente le nombre à virgule flottante (3 + 10./16 + 7./16**2) *2.0**10
, ou 3740.0
>>> float.fromhex('0x3.a7p10')
3740.0
L’application de la conversion inverse à 3740.0
donne une chaîne hexadécimale différente représentant le même nombre
>>> float.hex(3740.0)
'0x1.d380000000000p+11'
4.4.4. Hachage des types numériques¶
Pour deux nombres égaux x
et y
(x == y
), pouvant être de différents types, il est une requis que hash(x) == hash(y)
(voir la documentation de __hash__()
). Pour faciliter la mise en œuvre et l’efficacité à travers une variété de types numériques (y compris int
, float
, decimal.Decimal
et fractions.Fraction
) le hachage en Python pour les types numérique est basé sur une fonction mathématique unique qui est définie pour tout nombre rationnel, et donc s’applique à toutes les instances de int
et fractions.Fraction
, et toutes les instances finies de float
et decimal.Decimal
. Essentiellement, cette fonction est donnée par la réduction modulo P
pour un nombre P
premier fixe. La valeur de P
est disponible comme attribut modulus
de sys.hash_info
.
Actuellement, le premier utilisé est P = 2 ** 31 - 1
sur des machines dont les longs en C sont de 32 bits P = 2 ** 61 - 1
sur des machines dont les longs en C font 64 bits.
Voici les règles en détail :
- Si
x = m / n
est un nombre rationnel non négatif etn
n’est pas divisible parP
, définirhash(x)
commem * invmod(n, P) % P
, oùinvmod(n, P)
donne l’inverse den
moduloP
. - Si
x = m / n
est un nombre rationnel non négatif etn
est divisible parP
(maism
ne l’est pas), alorsn
n’a pas de modulo inverseP
et la règle ci-dessus n’est pas applicable; dans ce cas définirhash(x)
comme étant la valeur de la constantesys.hash_info.inf
. - Si
x = m / n
est un nombre rationnel négatif définirhash(x)
comme-hash(-x)
. Si le résultat est-1
, le remplacer par-2
. - Les valeurs particulières
sys.hash_info.inf
,-sys.hash_info.inf
etsys.hash_info.nan
sont utilisées comme valeurs de hachage pour l’infini positif, l’infini négatif, ou nans (respectivement). (Tous les nans hachables ont la même valeur de hachage.) - Pour un nombre
complexe
z
, les valeurs de hachage des parties réelles et imaginaires sont combinées en calculanthash(z.real) + sys.hash_info.imag * hash(z.imag)
, réduit au modulo2**sys.hash_info.width
de sorte qu’il se trouve dansrange(-2**(sys.hash_info.width - 1), 2**(sys.hash_info.width - 1))
. Encore une fois, si le résultat est-1
, il est remplacé par-2
.
Afin de clarifier les règles ci-dessus, voici quelques exemples de code Python, équivalent à la fonction de hachage native, pour calculer le hachage d’un nombre rationnel, d’un float
, ou d’un complex
import sys, math
def hash_fraction(m, n):
"""Compute the hash of a rational number m / n.
Assumes m and n are integers, with n positive.
Equivalent to hash(fractions.Fraction(m, n)).
"""
P = sys.hash_info.modulus
# Remove common factors of P. (Unnecessary if m and n already coprime.)
while m % P == n % P == 0:
m, n = m // P, n // P
if n % P == 0:
hash_ = sys.hash_info.inf
else:
# Fermat's Little Theorem: pow(n, P-1, P) is 1, so
# pow(n, P-2, P) gives the inverse of n modulo P.
hash_ = (abs(m) % P) * pow(n, P - 2, P) % P
if m < 0:
hash_ = -hash_
if hash_ == -1:
hash_ = -2
return hash_
def hash_float(x):
"""Compute the hash of a float x."""
if math.isnan(x):
return sys.hash_info.nan
elif math.isinf(x):
return sys.hash_info.inf if x > 0 else -sys.hash_info.inf
else:
return hash_fraction(*x.as_integer_ratio())
def hash_complex(z):
"""Compute the hash of a complex number z."""
hash_ = hash_float(z.real) + sys.hash_info.imag * hash_float(z.imag)
# do a signed reduction modulo 2**sys.hash_info.width
M = 2**(sys.hash_info.width - 1)
hash_ = (hash_ & (M - 1)) - (hash & M)
if hash_ == -1:
hash_ == -2
return hash_
4.5. Les types Itérateurs¶
Python supporte un concept d’itération sur les conteneurs. C’est implémenté en utilisant deux méthodes distinctes qui permettent aux classes définies par l’utilisateur de devenir itérables. Les séquences, décrites plus bas en détail, supportent toujours les méthodes d’itération.
Une méthode doit être définie afin que les objets conteneurs supportent l’itération :
-
container.
__iter__
()¶ Donne un objet itérateur. L’objet doit implémenter le protocole d’itération décrit ci-dessous. Si un conteneur prend en charge différents types d’itération, d’autres méthodes peuvent être fournies pour obtenir spécifiquement les itérateurs pour ces types d’itération. (Exemple d’un objet supportant plusieurs formes d’itération : une structure d’arbre pouvant être parcourue en largeur ou en profondeur.) Cette méthode correspond à l’attribut
tp_iter
de la structure du type des objets Python dans l’API Python/C.
Les itérateurs eux-mêmes doivent implémenter les deux méthodes suivantes, qui forment ensemble le protocole d’itérateur <iterator protocol> :
-
iterator.
__iter__
()¶ Donne l’objet itérateur lui-même. Cela est nécessaire pour permettre à la fois à des conteneurs et des itérateurs d’être utilisés avec les instructions
for
etin
. Cette méthode correspond à l’attributtp_iter
de la structure des types des objets Python dans l’API Python/C.
-
iterator.
__next__
()¶ Donne l’élément suivant du conteneur. S’il n’y a pas d’autres éléments, une exception
StopIteration
est levée. Cette méthode correspond à l’attributPyTypeObject.tp_iternext
de la structure du type des objets Python dans l’API Python/C.
Python définit plusieurs objets itérateurs pour itérer sur les types standards ou spécifiques de séquence, de dictionnaires et d’autres formes plus spécialisées. Les types spécifiques ne sont pas importants au-delà de leur implémentation du protocole d’itération.
Dès que la méthode __next__()
lève une exception StopIteration
, elle doit continuer à le faire lors des appels ultérieurs.Implémentations qui ne respectent pas cette propriété sont considérées cassées.
4.5.1. Types Générateurs¶
Les generators offrent un moyen pratique d’implémenter le protocole d’itération. Si la méthode __iter__()
d’un objet conteneur est implémentée comme un générateur, elle renverra automatiquement un objet iterator (techniquement, un objet générateur) fournissant les méthodes __iter__()
et __next__()
. Plus d’informations sur les générateurs peuvent être trouvés dans la documentation de l’expression yield.
4.6. Types séquentiels — list
, tuple
, range
¶
Il existe trois types séquentiels basiques: les lists, tuples et les range. D’autres types séquentiels spécifiques au traitement de données binaires et chaînes de caractères sont décrits dans des sections dédiées.
4.6.1. Opérations communes sur les séquences¶
Les opérations dans le tableau ci-dessous sont pris en charge par la plupart des types séquentiels, variables et immuables. La classe de base abstraite collections.abc.Sequence
est fournie pour aider à implémenter correctement ces opérations sur les types séquentiels personnalisés.
Ce tableau répertorie les opérations sur les séquences triées par priorité ascendante. Dans le tableau, s, et t sont des séquences du même type, n, i, j et k sont des nombres entiers et x est un objet arbitraire qui répond à toutes les restrictions de type et de valeur imposée par s.
Les opérations in
et not in
ont les mêmes priorités que les opérations de comparaison. Les opérations +
(concaténation) et *
(répétition) ont la même priorité que les opérations numériques correspondantes.
Opération | Résultat | Notes |
---|---|---|
x in s |
True si un élément de s est égal à x, sinon False |
(1) |
x not in s |
False si un élément de s est égal à x, sinon True |
(1) |
s + t |
la concaténation de s et t | (6)(7) |
s * n or
n * s |
n shallow copies of s concatenated | (2)(7) |
s[i] |
ième élément de s en commençant par 0 | (3) |
s[i:j] |
tranche (slice) de s de i à j | (3)(4) |
s[i:j:k] |
tranche (slice) de s de i à j avec un pas de k | (3)(5) |
len(s) |
longueur de s | |
min(s) |
plus petit élément de s | |
max(s) |
plus grand élément de s | |
s.index(x[, i[, j]]) |
indice de la première occurrence de x dans s (à ou après l’indice i et avant indice j) | (8) |
s.count(x) |
nombre total d’occurrences de x dans s |
Les séquences du même type supportent également la comparaison. En particulier, les tuples et les listes sont comparées lexicographiquement en comparant les éléments correspondants. Cela signifie que pour être égales, chaques éléments doivent être égaux deux à deux et les deux séquences doivent être du même type et de la même longueur. (Pour plus de détails voir Comparaisons dans la référence du langage.)
Notes :
Bien que les opérations
in
etnot in
ne soient généralement utilisées que pour les tests d’appartenance simple, certaines séquences spécialisées (telles questr
,bytes
etbytearray
) les utilisent aussi pour tester l’existence de sous-séquences :>>> "gg" in "eggs" True
Values of n less than
0
are treated as0
(which yields an empty sequence of the same type as s). Note also that the copies are shallow; nested structures are not copied. This often haunts new Python programmers; consider:>>> lists = [[]] * 3 >>> lists [[], [], []] >>> lists[0].append(3) >>> lists [[3], [3], [3]]
What has happened is that
[[]]
is a one-element list containing an empty list, so all three elements of[[]] * 3
are (pointers to) this single empty list. Modifying any of the elements oflists
modifies this single list. You can create a list of different lists this way:>>> lists = [[] for i in range(3)] >>> lists[0].append(3) >>> lists[1].append(5) >>> lists[2].append(7) >>> lists [[3], [5], [7]]
If i or j is negative, the index is relative to the end of the string:
len(s) + i
orlen(s) + j
is substituted. But note that-0
is still0
.La tranche de s de i à j est définie comme la séquence d’éléments d’indice k tels que
i <= k < j
. Si i ou j est supérieur àlen(s)
,len(s)
est utilisé. Si i est omis ouNone
,0
est utilisé. Si j est omis ouNone
,len(s)
est utilisé. Si i est supérieure ou égale à j, la tranche est vide.The slice of s from i to j with step k is defined as the sequence of items with index
x = i + n*k
such that0 <= n < (j-i)/k
. In other words, the indices arei
,i+k
,i+2*k
,i+3*k
and so on, stopping when j is reached (but never including j). If i or j is greater thanlen(s)
, uselen(s)
. If i or j are omitted orNone
, they become « end » values (which end depends on the sign of k). Note, k cannot be zero. If k isNone
, it is treated like1
.Concaténer des séquences immuables donne toujours un nouvel objet. Cela signifie que la construction d’une séquence par concaténations répétées aura une durée d’exécution quadratique par rapport à la longueur de la séquence totale. Pour obtenir un temps d’exécution linéaire, vous devez utiliser l’une des alternatives suivantes :
- if concatenating
str
objects, you can build a list and usestr.join()
at the end or else write to aio.StringIO
instance and retrieve its value when complete - si vous concatennez des
bytes
, vous pouvez aussi utiliserbytes.join()
ouio.BytesIO
, ou vous pouvez faire les concaténation sur place avec un objetbytearray
. Les objetsbytearray
sont mutables et ont un mécanisme de sur-allocation efficace - si vous concatennez des
tuple
, utilisez plutôt extend sur unelist
- pour d’autres types, cherchez dans la documentation de la classe concernée
- if concatenating
Certains types séquenciels (tels que
range
) ne supportent que des séquences qui suivent des modèles spécifiques, et donc ne prennent pas en charge la concaténation ou la répétition.index
lève une exceptionValueError
quand x ne se trouve pas dans s. Lorsqu’ils sont supportés, les arguments supplémentaires de la méthodeindex
permettent une recherche efficace des sous-sequences dans la séquence. Donner ces arguments est plus ou moins équivalent às[i:j].index(x)
, sans copier les données, et dont l’indice retourné est relatif au début de la séquence plutôt qu’au début de la tranche.
4.6.2. Types de Séquences Immuables¶
La seule opération que les types de séquences immutables implémentent qui n’est pas implémentée par les types de séquences mutables est le support de la fonction native hash()
.
Cette implémentation permet d’utiliser des séquences immutables, comme les instances de tuple
, en tant que clés de dict
et stockées dans les instances de set
et frozenset
.
Essayer de hacher une séquence immuable qui contient des valeurs non-hachables lèvera une TypeError
.
4.6.3. Types de séquences mutables¶
Les opérations dans le tableau ci-dessous sont définies sur les types de séquences mutables. La classe de base abstraite collections.abc.MutableSequence
est prévue pour faciliter l’implémentation correcte de ces opérations sur les types de séquence personnalisées.
Dans le tableau s est une instance d’un type de séquence mutable, t est un objet itérable et x est un objet arbitraire qui répond à toutes les restrictions de type et de valeur imposées par s (par exemple, bytearray
accepte uniquement des nombres entiers qui répondent à la restriction de la valeur 0 <= x <= 255
).
Opération | Résultat | Notes |
---|---|---|
s[i] = x |
element i de s est remplacé par x | |
s[i:j] = t |
tranche de s de i à j est remplacée par le contenu de l’itérable t | |
del s[i:j] |
identique à s[i:j] = [] |
|
s[i:j:k] = t |
les éléments de s[i:j:k] sont remplacés par ceux de t |
(1) |
del s[i:j:k] |
supprime les éléments de s[i:j:k] de la liste |
|
s.append(x) |
ajoute x à la fin de la séquence (identique à s[len(s):len(s)] = [x] ) |
|
s.clear() |
supprime tous les éléments de s (identique à del s[:] ) |
(5) |
s.copy() |
crée une copie superficielle de s (identique à s[:] ) |
(5) |
s.extend(t) |
extends s with the
contents of t (same as
s[len(s):len(s)] = t ) |
|
s.insert(i, x) |
insère x dans s à l’index donné par i (identique à s[i:i] = [x] ) |
|
s.pop([i]) |
récupère l’élément à i et le supprime de s | (2) |
s.remove(x) |
supprime le premier élément de s pour qui s[i] == x |
(3) |
s.reverse() |
inverse sur place les éléments de s | (4) |
Notes :
t doit avoir la même longueur que la tranche qu’il remplace.
L’argument optionnel i vaut
-1
par défaut, afin que, par défaut, le dernier élément soit retiré et renvoyé.remove
lève une exceptionValueError
si x ne se trouve pas dans s.La méthode
reverse()
modifie les séquence sur place pour économiser de l’espace lors du traitement de grandes séquences. Pour rappeler aux utilisateurs qu’elle a un effet de bord, elle ne renvoie pas la séquence inversée.clear()
etcopy()
sont inclues pour la compatibilité avec les interfaces des conteneurs mutables qui ne supportent pas les opérations de découpage (commedict
etset
)Nouveau dans la version 3.3: méthodes
clear()
etcopy()
.
4.6.4. Les listes¶
Les listes sont des séquences mutables, généralement utilisées pour stocker des collections d’éléments homogènes (où le degré de similitude variera selon l’usage).
-
class
list
([iterable])¶ Les listes peuvent être construites de différentes manières :
- En utilisant une paire de crochets pour indiquer une liste vide :
[]
- Au moyen de crochets, séparant les éléments par des virgules :
[a]
,[a, b, c]
- En utilisant une liste en compréhension :
[x for x in iterable]
- En utilisant le constructeur du type :
list()
oulist(iterable)
Le constructeur crée une liste dont les éléments sont les mêmes et dans le même ordre que les éléments d”iterable. iterable peut être soit une séquence, un conteneur qui supporte l’itération, soit un itérateur. Si iterable est déjà une liste, une copie est faite et retournée, comme avec
iterable[:]
. Par exemple,list('abc')
retourne['a', 'b', 'c']
etlist( (1, 2, 3) )
retourne[1, 2, 3]
. Si aucun argument est donné, le constructeur crée une nouvelle liste vide,[]
.De nombreuses autres opérations produisent des listes, tel que la fonction native
sorted()
.Les listes supportent toutes les opérations des séquences communes et mutables. Les listes fournissent également la méthode supplémentaire suivante :
-
sort
(*, key=None, reverse=None)¶ Cette méthode trie la liste sur place, en utilisant uniquement des comparaisons
<
entre les éléments. Les exceptions ne sont pas supprimées - si n’importe quelle opération de comparaison échoue, le tri échouera (et la liste sera probablement laissée dans un état partiellement modifié).sort()
accepte deux arguments qui ne peuvent être fournis que par mot-clé (keyword-only arguments):key spécifie une fonction d’un argument utilisée pour extraire une clé de comparaison de chaque élément de la liste (par exemple,
key=str.lower
). La clé correspondant à chaque élément de la liste n’est calculée qu’une seule fois, puis utilisée durant tout le processus. La valeur par défaut,None
, signifie que les éléments sont triés directement sans en calculer une valeur « clé » séparée.La fonction utilitaire
functools.cmp_to_key()
est disponible pour convertir une fonction cmp du style 2.x à une fonction key.reverse, une valeur booléenne. Si elle est
True
, la liste d’éléments est triée comme si toutes les comparaisons étaient inversées.Cette méthode modifie la séquence sur place pour économiser de l’espace lors du tri de grandes séquences. Pour rappeler aux utilisateurs cet effet de bord, elle ne renvoie pas la séquence triée (utilisez
sorted()
pour demander explicitement une nouvelle instance de liste triée).La méthode
sort()
est garantie stable. Un tri est stable s’il garantit de ne pas changer l’ordre relatif des éléments égaux — cela est utile pour trier en plusieurs passes (par exemple, trier par département, puis par niveau de salaire).L’effet de tenter de modifier, ou même inspecter la liste pendant qu’elle se fait trier est indéfini. L’implémentation C de Python fait apparaître la liste comme vide pour la durée du traitement, et soulève
ValueError
si elle détecte que la liste a été modifiée au cours du tri.
- En utilisant une paire de crochets pour indiquer une liste vide :
4.6.5. Tuples¶
Les tuples (uplets en français) sont des séquences immuables, généralement utilisées pour stocker des collections de données hétérogènes (tels que les tuples de deux éléments produits par la fonction native enumerate()
). Les tuples sont également utilisés dans des cas où une séquence homogène et immuable de données est nécessaire (pour, par exemple, les stocker dans un set
ou un dict
).
-
class
tuple
([iterable])¶ Les tuples peuvent être construits de différentes façons :
- En utilisant une paire de parenthèses pour désigner le tuple vide :
()
- En utilisant une virgule, pour créer un tuple d’un élément :
a,
ou(a,)
- En séparant les éléments avec des virgules :
a, b, c
ou(a, b, c)
- En utilisant la fonction native
tuple()
:tuple()
outuple(iterable)
Le constructeur construit un tuple dont les éléments sont les mêmes et dans le même ordre que les éléments de iterable. iterable peut être soit une séquence, un conteneur qui supporte l’itération, soit un itérateur. Si iterable est déjà un tuple, il est renvoyé inchangé. Par exemple,
tuple('abc')
retourne('a', 'b', 'c')
ettuple( [1, 2, 3] )
retourne(1, 2, 3)
. Si aucun argument est donné, le constructeur crée un nouveau tuple vide,()
.Notez que c’est en fait la virgule qui fait un tuple, pas les parenthèses. Les parenthèses sont facultatives, sauf dans le cas du tuple vide, ou lorsqu’elles sont nécessaires pour éviter l’ambiguïté syntaxique. Par exemple,
f(a, b, c)
est un appel de fonction avec trois arguments, alors quef((a, b, c))
est un appel de fonction avec un tuple de trois éléments comme unique argument.Les tuples implémentent toutes les opérations communes des séquences.
- En utilisant une paire de parenthèses pour désigner le tuple vide :
Pour les collections hétérogènes de données où l’accès par nom est plus clair que l’accès par index, collections.namedtuple()
peut être un choix plus approprié qu’un simple tuple.
4.6.6. Ranges¶
Le type range
représente une séquence immuable de nombres et est couramment utilisé pour itérer un certain nombre de fois dans les boucles for
.
-
class
range
(stop)¶ -
class
range
(start, stop[, step]) Les arguments du constructeur de range doivent être des entiers (des
int
ou tout autre objet qui implémente la méthode spéciale__index__
). La valeur par défaut de l’argument step est1
. La valeur par défaut de l’argument start est0
. Si step est égal à zéro, une exceptionValueError
est levée.Pour un step positif, le contenu d’un range
r
est déterminé par la formuler[i] = start + step*i
oùi >= 0
etr[i] < stop
.Pour un step négatif, le contenu du range est toujours déterminé par la formule
r[i] = start + step*i
, mais les contraintes sonti >= 0
etr[i] > stop
.Un objet range sera vide si
r[0]
ne répond pas à la contrainte de valeur. Les range prennent en charge les indices négatifs, mais ceux-ci sont interprétées comme une indexation de la fin de la séquence déterminée par les indices positifs.Les range contenant des valeurs absolues plus grandes que
sys.maxsize
sont permises, mais certaines fonctionnalités (commelen()
) peuvent leverOverflowError
.Exemples avec range
>>> list(range(10)) [0, 1, 2, 3, 4, 5, 6, 7, 8, 9] >>> list(range(1, 11)) [1, 2, 3, 4, 5, 6, 7, 8, 9, 10] >>> list(range(0, 30, 5)) [0, 5, 10, 15, 20, 25] >>> list(range(0, 10, 3)) [0, 3, 6, 9] >>> list(range(0, -10, -1)) [0, -1, -2, -3, -4, -5, -6, -7, -8, -9] >>> list(range(0)) [] >>> list(range(1, 0)) []
range implémente toutes les opérations communes des séquences sauf la concaténation et la répétition (en raison du fait que les range ne peuvent représenter que des séquences qui respectent un motif strict et que la répétition et la concaténation les feraient dévier de ce motif).
L’avantage du type range
sur une list
classique ou tuple
est qu’un objet range
prendra toujours la même (petite) quantité de mémoire, peu importe la taille de la gamme qu’elle représente (car elle ne stocke que les valeurs start
, stop
et step
, le calcul des éléments individuels et les sous-range au besoin).
Les range implémentent la classe de base abstraite collections.abc.Sequence
, et offrent des fonctionnalités telles que les tests d’appartenance (avec in) , de recherche par index, le tranchage et ils gerent les indices négatifs (voir Types séquentiels — list, tuple, range):
>>> r = range(0, 20, 2)
>>> r
range(0, 20, 2)
>>> 11 in r
False
>>> 10 in r
True
>>> r.index(10)
5
>>> r[5]
10
>>> r[:5]
range(0, 10, 2)
>>> r[-1]
18
Comparer des range avec ==
et !=
les compare comme des séquences. Soit deux objets range sont considérées comme égaux si ils représentent la même séquence de valeurs. (Notez que deux objets range dits égaux pourraient avoir leurs attributs start
, stop
et step
différents, par exemple range(0) == range(2, 1, 3)
ou range(0, 3, 2) == range(0, 4, 2)
.)
Modifié dans la version 3.2: Implémente la classe de base abstraite Sequence. Supporte le slicing et les indices négatifs. Tester l’appartenance d’un int
en temps constant au lieu d’itérer tous les éléments.
Modifié dans la version 3.3: “==” et “!=” comparent des range en fonction de la séquence de valeurs qu’ils définissent (au lieu d’une comparaison fondée sur l’identité de l’objet).
Nouveau dans la version 3.3: Les attributs start
, stop
et step
.
4.7. Type Séquence de Texte — str
¶
Les données textuelles en Python est manipulé avec des objets str
ou strings. Les chaînes sont des séquences immuables depoints de code Unicode. Les chaînes littérales peuvent être écrites de différentes manières :
- Les guillemets simples :
'autorisent les "guillemets"'
- Les guillemets :
"autorisent les guillemets 'simples'"
. - Guillemets triples :
'''Trois guillemets simples'''
,"""Trois guillemets"""
Les chaînes entre triple guillemets peuvent couvrir plusieurs lignes - tous les espaces associés seront inclus dans la chaîne littérale.
Les chaînes littérales qui font partie d’une seule expression et ont seulement des espaces entre elles sont implicitement converties en une seule chaîne littérale. Autrement dit, ("spam " "eggs") == "spam eggs"
.
Voir String and Bytes literals pour plus d’informations sur les différentes formes de chaînes littérales, y compris des séquences d’échappement prises en charge, et le préfixe r
(raw (brut)) qui désactive la plupart des traitements de séquence d’échappement.
Les chaînes peuvent également être créés à partir d’autres objets à l’aide du constructeur str
.
Comme il n’y a pas de type « caractère » distinct, l’indexation d’une chaîne produit des chaînes de longueur 1. Autrement dit, pour une chaîne non vide s, s[0] == s[0:1]
.
Il n’y a aucun type de chaîne mutable, mais str.join()
ou io.StringIO
peuvent être utilisées pour construire efficacement des chaînes à partir de plusieurs fragments.
Modifié dans la version 3.3: Pour une compatibilité ascendante avec la série Python 2, le préfixe u
est à nouveau autorisé sur les chaînes littérales. Elle n’a aucun effet sur le sens des chaînes littérales et ne peut être combiné avec le préfixe r
.
-
class
str
(object= »)¶ -
class
str
(object=b », encoding=”utf-8”, errors=”strict”) Renvoie une représentation string de object. Si object n’est pas fourni, retourne une chaîne vide. Sinon, le comportement de
str()
dépend de si encoding ou errors sont donnés, voir l’exemple.Si ni encoding ni errors ne sont donnés,
str(object)
renvoieobject.__str__()
, qui est la représentation de chaîne « informelle » ou bien affichable de object. Pour les chaînes, c’est la chaîne elle-même. Si object n’a pas de méthode__str__()
,str()
utiliserepr(object)
.Si au moins un des deux arguments encoding ou errors est donné, object doit être un bytes-like object (par exemple
bytes
oubytearray
). Dans ce cas, si object est un objetbytes
(oubytearray
), alorsstr(bytes, encoding, errors)
est équivalent àbytes.decode(encoding, errors)
. Sinon, l’objet bytes du buffer est obtenu avant d’appelerbytes.decode()
. Voir Séquences Binaires — bytes, bytearray, memoryview et Buffer Protocol pour plus d’informations sur les buffers.Donner un objet
bytes
àstr()
sans ni l’argument encoding ni l’argument errors relève du premier cas retournant la représentation informelle de la chaîne (voir aussi l’option-b
de Python). Par exemple :>>> str(b'Zoot!') "b'Zoot!'"
For more information on the
str
class and its methods, see Type Séquence de Texte — str and the Méthodes de chaînes de caractères section below. To output formatted strings, see the String Formatting section. In addition, see the Text Processing Services section.
4.7.1. Méthodes de chaînes de caractères¶
Les chaînes implémentent toutes les opérations communes des séquences, ainsi que les autres méthodes décrites ci-dessous.
Les chaînes gèrent aussi deux styles de mise en forme, l’un fournissant une grande flexibilité et de personnalisation (voir str.format()
, Syntaxe de formatage de chaîne et String Formatting) et l’autre basée sur printf
du C qui gère une gamme plus étroite des types et est légèrement plus difficile à utiliser correctement, mais il est souvent plus rapide pour les cas, il peut gérer (Formattage de chaines à la printf).
La section Text Processing Services de la bibliothèque standard couvre un certain nombre d’autres modules qui fournissent différents services relatifs au texte (y compris les expressions régulières dans le module re
).
-
str.
capitalize
()¶ Renvoie une copie de la chaîne avec son premier caractère en majuscule et le reste en minuscule.
-
str.
casefold
()¶ Renvoie une copie casefolded de la chaîne. Les chaînes casefolded peuvent être utilisées dans des comparaison insensibles à la casse.
Le casefolding est une technique agressive de mise en minuscule, car il vise à éliminer toutes les distinctions de casse dans une chaîne. Par exemple, la lettre minuscule
'ß'
de l’allemand équivaut à"ss"
. Comme il est déjà minuscule,lower()
ferait rien à'ß'
;casefold()
le convertit en"ss"
.L’algorithme de casefolding est décrit dans la section 3.13 de la norme Unicode.
Nouveau dans la version 3.3.
-
str.
center
(width[, fillchar])¶ Donne la chaîne au centre d’une chaîne de longueur width. Le remplissage est fait enutilisant l’argument fillchar (qui par défaut est un espace ASCII). La chaîne d’origine est renvoyée si width est inférieur ou égale à
len(s)
.
-
str.
count
(sub[, start[, end]])¶ Donne le nombre d’occurrences de sub ne se chevauchant pas dans le range [start, end]. Les arguments facultatifs start et end sont interprétés comme pour des slices.
-
str.
encode
(encoding= »utf-8 », errors= »strict »)¶ Donne une version encodée de la chaîne sous la forme d’un objet bytes. L’encodage par défaut est
'utf-8'
. errors peut être donné pour choisir un autre système de gestion d’erreur. La valeur par défaut pour errors est'strict'
, ce qui signifie que les erreurs d’encodage soulèvent uneUnicodeError
. Les autres valeurs possibles sont'ignore'
,'replace'
,'xmlcharrefreplace'
,'backslashreplace'
et tout autre nom enregistré viacodecs.register_error()
, voir la section Error Handlers. Pour une liste des encodages possibles, voir la section Standard Encodings.Modifié dans la version 3.1: Gestion des arguments par mot clef.
-
str.
endswith
(suffix[, start[, end]])¶ Donne
True
si la chaîne se termine par suffix, sinonFalse
. suffix peut aussi être un tuple de suffixes à rechercher. Si l’argument optionnel start est donné, le test se fait à partir de cette position. Si l’argument optionnel end est fourni, la comparaison s’arrête à cette position.
-
str.
expandtabs
(tabsize=8)¶ Donne une copie de la chaîne où toutes les tabulations sont remplacées par un ou plusieurs espaces, en fonction de la colonne courante et de la taille de tabulation donnée. Les positions des tabulations se trouvent tous les tabsize caractères (8 par défaut, ce qui donne les positions de tabulations aux colonnes 0, 8, 16 et ainsi de suite). Pour travailler sur la chaîne, la colonne en cours est mise à zéro et la chaîne est examinée caractère par caractère. Si le caractère est une tabulation (
\t
), un ou plusieurs caractères d’espacement sont insérés dans le résultat jusqu’à ce que la colonne courante soit égale à la position de tabulation suivante. (Le caractère tabulation lui-même n’est pas copié.) Si le caractère est un saut de ligne (\n
) ou un retour chariot (\r
), il est copié et la colonne en cours est remise à zéro. Tout autre caractère est copié inchangé et la colonne en cours est incrémentée de un indépendamment de la façon dont le caractère est représenté lors de l’affichage.>>> '01\t012\t0123\t01234'.expandtabs() '01 012 0123 01234' >>> '01\t012\t0123\t01234'.expandtabs(4) '01 012 0123 01234'
-
str.
find
(sub[, start[, end]])¶ Return the lowest index in the string where substring sub is found, such that sub is contained in the slice
s[start:end]
. Optional arguments start and end are interpreted as in slice notation. Return-1
if sub is not found.
-
str.
format
(*args, **kwargs)¶ Formatte une chaîne. La chaîne sur laquelle cette méthode est appelée peut contenir du texte littéral ou des emplacements de remplacement délimités par des accolades
{}
. Chaque champ de remplacement contient soit l’indice numérique d’un argument positionnel, ou le nom d’un argument donné par mot-clé. Renvoie une copie de la chaîne où chaque champ de remplacement est remplacé par la valeur de chaîne de l’argument correspondant.>>> "The sum of 1 + 2 is {0}".format(1+2) 'The sum of 1 + 2 is 3'
Voir Syntaxe de formatage de chaîne pour une description des options de formatage qui peuvent être spécifiées dans les chaînes de format.
-
str.
format_map
(mapping)¶ Semblable à
str.format(**mapping)
, sauf quemapping
est utilisé directement et non copié dans undict
. C’est utile si, par exemplemapping
est une sous-classe de dict :>>> class Default(dict): ... def __missing__(self, key): ... return key ... >>> '{name} was born in {country}'.format_map(Default(name='Guido')) 'Guido was born in country'
Nouveau dans la version 3.2.
-
str.
index
(sub[, start[, end]])¶ Comme
find()
, mais lève uneValueError
lorsque la chaîne est introuvable.
-
str.
isalnum
()¶ Donne
True
si tous les caractères de la chaîne sont alphanumériques et qu’il y a au moins un caractère, sinonFalse
. Un caractèrec
est alphanumérique si l’un des tests suivants est vrais :c.isalpha()
,c.isdecimal()
,c.isdigit()
ouc.isnumeric()
.
-
str.
isalpha
()¶ Donne
True
si tous les caractères de la chaîne sont alphabétiques et qu’elle contient au moins un caractère, sinonFalse
. Les caractères alphabétiques sont les caractères définis dans la base de données de caractères Unicode comme Letter, à savoir, ceux qui ont « Lm », « Lt », « Lu », « Ll », ou « Lo » comme catégorie générale. Notez que ceci est différent de la propriété Alphabetic définie dans la norme Unicode.
-
str.
isdecimal
()¶ Return true if all characters in the string are decimal characters and there is at least one character, false otherwise. Decimal characters are those from general category « Nd ». This category includes digit characters, and all characters that can be used to form decimal-radix numbers, e.g. U+0660, ARABIC-INDIC DIGIT ZERO.
-
str.
isdigit
()¶ Return true if all characters in the string are digits and there is at least one character, false otherwise. Digits include decimal characters and digits that need special handling, such as the compatibility superscript digits. Formally, a digit is a character that has the property value Numeric_Type=Digit or Numeric_Type=Decimal.
-
str.
isidentifier
()¶ Donne
True
si la chaîne est un identifiant valide selon la définition du langage, section Identifiers and keywords.Utilisez
keyword.iskeyword()
pour savoir si un identifiant est réservé, tels quedef
etclass
.
-
str.
islower
()¶ Donne
True
si tous les caractères capitalisables [4] de la chaîne sont en minuscules et qu’elle contient au moins un caractère capitalisable. DonneFalse
dans le cas contraire.
-
str.
isnumeric
()¶ Donne
True
si tous les caractères de la chaîne sont des caractères numériques, et qu’elle contient au moins un caractère, sinonFalse
. Les caractères numériques comprennent les chiffres, et tous les caractères qui ont la propriété Unicode numeric value, par exemple U+2155, VULGAR FRACTION OF FIFTH. Formellement, les caractères numériques sont ceux avec les priorités Numeric_Type=Digit, Numeric_Type=Decimal, ou Numeric_Type=Numeric.
-
str.
isprintable
()¶ Donne
True
si tous les caractères de la chaîne sont affichables ou qu’elle est vide sinon,False
. Les caractères non affichables sont les caractères définis dans la base de données de caractères Unicode comme « Other » ou « Separator », à l’exception de l’espace ASCII (0x20) qui est considéré comme affichable. (Notez que les caractères imprimables dans ce contexte sont ceux qui ne devraient pas être protégés quandrepr()
est invoquée sur une chaîne. Ça n’a aucune incidence sur le traitement des chaînes écrites sursys.stdout
ousys.stderr
.)
-
str.
isspace
()¶ Donne
True
s’il n’y a que des caractères blancs dans la chaîne et il y a au moins un caractère, sinonFalse
. Les caractères blancs sont les caractères définis dans la base de données de caractères Unicode comme « Other » ou « Separator » ainsi que ceux ayant la propriété bidirectionnelle valant « WS », « B » ou « S ».
-
str.
istitle
()¶ Donne
True
si la chaîne est une chaîne titlecased et qu’elle contient au moins un caractère, par exemple les caractères majuscules ne peuvent suivre les caractères non capitalisables et les caractères minuscules ne peuvent suivre que des caractères capitalisables. DonneFalse
dans le cas contraire.
-
str.
isupper
()¶ Donne
True
si tous les caractères différentiables sur la casse [4] de la chaîne sont en majuscules et il y a au moins un caractère différentiable sur la casse, sinonFalse
.
-
str.
join
(iterable)¶ Donne une chaîne qui est la concaténation des chaînes de l”iterable iterable. Une
TypeError
sera levée si des valeurs d”iterable ne sont pas des chaînes, y compris pour les objetsbytes
. Le séparateur entre les éléments est la chaîne fournissant cette méthode.
-
str.
ljust
(width[, fillchar])¶ Renvoie la chaîne justifiée à gauche dans une chaîne de longueur width. Le rembourrage est fait en utilisant fillchar (qui par défaut est un espace ASCII). La chaîne d’origine est renvoyée si width est inférieur ou égale à
len(s)
.
-
str.
lower
()¶ Renvoie une copie de la chaîne avec tous les caractères capitalisables [4] convertis en minuscules.
L’algorithme de mise en minuscules utilisé est décrit dans la section 3.13 de la norme Unicode.
-
str.
lstrip
([chars])¶ Renvoie une copie de la chaîne des caractères supprimés au début. L’argument chars est une chaîne spécifiant le jeu de caractères à supprimer. En cas d’omission ou
None
, la valeur par défaut de chars permet de supprimer des espaces. L’argument chars n’est pas un préfixe, toutes les combinaisons de ses valeurs sont supprimées>>> ' spacious '.lstrip() 'spacious ' >>> 'www.example.com'.lstrip('cmowz.') 'example.com'
-
static
str.
maketrans
(x[, y[, z]])¶ Cette méthode statique renvoie une table de traduction utilisable pour
str.translate()
.If there is only one argument, it must be a dictionary mapping Unicode ordinals (integers) or characters (strings of length 1) to Unicode ordinals, strings (of arbitrary lengths) or None. Character keys will then be converted to ordinals.
If there are two arguments, they must be strings of equal length, and in the resulting dictionary, each character in x will be mapped to the character at the same position in y. If there is a third argument, it must be a string, whose characters will be mapped to None in the result.
-
str.
partition
(sep)¶ Divise la chaîne à la première occurrence de sep, et donne un tuple de trois éléments contenant la partie avant le séparateur, le séparateur lui-même, et la partie après le séparateur. Si le séparateur n’est pas trouvé, le tuple contiendra la chaîne elle-même, suivie de deux chaînes vides.
-
str.
replace
(old, new[, count])¶ Renvoie une copie de la chaîne dont toutes les occurrences de la sous-chaîne old sont remplacés par new. Si l’argument optionnel count est donné, seules les count premières occurrences sont remplacées.
-
str.
rfind
(sub[, start[, end]])¶ Donne l’indice le plus élevé dans la chaîne où la sous-chaîne sub se trouve, de telle sorte que sub soit contenue dans
s[start:end]
. Les arguments facultatifs start et end sont interprétés comme dans la notation des slices. Donne-1
en cas d’échec.
-
str.
rindex
(sub[, start[, end]])¶ Comme
rfind()
mais lève une exceptionValueError
lorsque la sous-chaîne sub est introuvable.
-
str.
rjust
(width[, fillchar])¶ Renvoie la chaîne justifié à droite dans une chaîne de longueur width. Le rembourrage est fait en utilisant le caractère spécifié par fillchar (par défaut est un espace ASCII). La chaîne d’origine est renvoyée si width est inférieure ou égale à
len(s)
.
-
str.
rpartition
(sep)¶ Divise la chaîne à la dernière occurrence de sep, et donne un tuple de trois éléments contenant la partie avant le séparateur, le séparateur lui-même, et la partie après le séparateur. Si le séparateur n’est pas trouvé, le tuple contindra deux chaînes vides, puis par la chaîne elle-même.
-
str.
rsplit
(sep=None, maxsplit=-1)¶ Renvoie une liste des mots de la chaîne, en utilisant sep comme séparateur. Si maxsplit est donné, c’est le nombre maximum de divisions qui pourront être faites, celles « à droite ». Si sep est pas spécifié ou est
None
, tout espace est un séparateur. En dehors du fait qu’il découpe par la droite,rsplit()
se comporte commesplit()
qui est décrit en détail ci-dessous.
-
str.
rstrip
([chars])¶ Renvoie une copie de la chaîne avec des caractères finaux supprimés. L’argument chars est une chaîne spécifiant le jeu de caractères à supprimer. En cas d’omission ou
None
, les espaces sont supprimés. L’argument chars n’est pas un suffixe : toutes les combinaisons de ses valeurs sont retirées :>>> ' spacious '.rstrip() ' spacious' >>> 'mississippi'.rstrip('ipz') 'mississ'
-
str.
split
(sep=None, maxsplit=-1)¶ Renvoie une liste des mots de la chaîne, en utilisant sep comme séparateur de mots. Si maxsplit est donné, c’est le nombre maximum de divisionsqui pourront être effectuées, (donnant ainsi une liste de longueur
maxsplit+1
). Si maxsplit n’est pas fourni, ou vaut-1
, le nombre de découpes n’est pas limité (Toutes les découpes possibles sont faites).Si sep est donné, les délimiteurs consécutifs ne sont pas regroupés et ainsi délimitent des chaînes vides (par exemple,
'1,,2'.split(',')
donne['1', '', '2']
). L’argument sep peut contenir plusieurs caractères (par exemple,'1<>2<>3'.split('<>')
retourne['1', '2', '3']
). Découper une chaîne vide en spécifiant sep donne['']
.Par exemple :
>>> '1,2,3'.split(',') ['1', '2', '3'] >>> '1,2,3'.split(',', maxsplit=1) ['1', '2,3'] >>> '1,2,,3,'.split(',') ['1', '2', '', '3', '']
Si sep n’est pas spécifié ou est
None
, un autre algorithme de découpage est appliqué : les espaces consécutifs sont considérés comme un seul séparateur, et le résultat ne contiendra pas les chaînes vides de début ou de la fin si la chaîne est préfixée ou suffixé d’espaces. Par conséquent, diviser une chaîne vide ou une chaîne composée d’espaces avec un séparateurNone
renvoie[]
.Par exemple :
>>> '1 2 3'.split() ['1', '2', '3'] >>> '1 2 3'.split(maxsplit=1) ['1', '2 3'] >>> ' 1 2 3 '.split() ['1', '2', '3']
-
str.
splitlines
([keepends])¶ Return a list of the lines in the string, breaking at line boundaries. This method uses the universal newlines approach to splitting lines. Line breaks are not included in the resulting list unless keepends is given and true.
Par exemple :
>>> 'ab c\n\nde fg\rkl\r\n'.splitlines() ['ab c', '', 'de fg', 'kl'] >>> 'ab c\n\nde fg\rkl\r\n'.splitlines(keepends=True) ['ab c\n', '\n', 'de fg\r', 'kl\r\n']
Contrairement à
split()
lorsque sep est fourni, cette méthode renvoie une liste vide pour la chaîne vide, et un saut de ligne à la fin ne se traduit pas par une ligne supplémentaire :>>> "".splitlines() [] >>> "One line\n".splitlines() ['One line']
À titre de comparaison,
split('\n')
donne :>>> ''.split('\n') [''] >>> 'Two lines\n'.split('\n') ['Two lines', '']
-
str.
startswith
(prefix[, start[, end]])¶ Donne
True
si la chaîne commence par prefix, sinonFalse
. prefix peut aussi être un tuple de préfixes à rechercher. Lorsque start est donné, la comparaison commence à cette position, et lorsque end est donné, la comparaison s’arrête à celle ci.
-
str.
strip
([chars])¶ Donne une copie de la chaîne dont des caractères initiaux et finaux sont supprimés. L’argument chars est une chaîne spécifiant le jeu de caractères à supprimer. En cas d’omission ou
None
, les espaces sont supprimés. L’argument chars est pas un préfixe ni un suffixe, toutes les combinaisons de ses valeurs sont supprimées :>>> ' spacious '.strip() 'spacious' >>> 'www.example.com'.strip('cmowz.') 'example'
-
str.
swapcase
()¶ Renvoie une copie de la chaîne dont les caractères majuscules sont convertis en minuscules et vice versa. Notez qu’il est pas nécessairement vrai que
s.swapcase().swapcase() == s
.
-
str.
title
()¶ Renvoie une version en initiales majuscules de la chaîne où les mots commencent par une capitale et les caractères restants sont en minuscules.
Par exemple :
>>> 'Hello world'.title() 'Hello World'
Pour l’algorithme, la notion de mot est définie simplement et indépendamment de la langue comme un groupe de lettres consécutives. La définition fonctionnedans de nombreux contextes, mais cela signifie que les apostrophes (typiquement dela forme possessive en Anglais) forment les limites de mot, ce qui n’est pas toujours le résultat souhaité :
>>> "they're bill's friends from the UK".title() "They'Re Bill'S Friends From The Uk"
Une solution pour contourner le problème des apostrophes peut être obtenue en utilisant des expressions rationnelles :
>>> import re >>> def titlecase(s): ... return re.sub(r"[A-Za-z]+('[A-Za-z]+)?", ... lambda mo: mo.group(0)[0].upper() + ... mo.group(0)[1:].lower(), ... s) ... >>> titlecase("they're bill's friends.") "They're Bill's Friends."
-
str.
translate
(map)¶ Return a copy of the s where all characters have been mapped through the map which must be a dictionary of Unicode ordinals (integers) to Unicode ordinals, strings or
None
. Unmapped characters are left untouched. Characters mapped toNone
are deleted.Vous pouvez utiliser
str.maketrans()
pour créer une table de correspondances de caractères dans différentsformats.Note
An even more flexible approach is to create a custom character mapping codec using the
codecs
module (seeencodings.cp1251
for an example).
-
str.
upper
()¶ Renvoie une copie de la chaîne dont tous les caractères capitalisables [4] sontconvertis en capitales. Notez que
str.upper().isupper()
pourrait êtreFalse
sis
contient des caractères non capitalisables ou si la catégorieUnicode d’un caractère du résultant est pas « Lu » (Lettre, majuscule), mais par exemple « Lt » (Lettre, titlecase).L’algorithme de capitalisation utilisé est décrit dans la section 3.13 de la norme Unicode.
-
str.
zfill
(width)¶ Return a copy of the string left filled with ASCII
'0'
digits to make a string of length width. A leading sign prefix ('+'
/'-'
is handled by inserting the padding after the sign character rather than before. The original string is returned if width is less than or equal tolen(s)
.Par exemple :
>>> "42".zfill(5) '00042' >>> "-42".zfill(5) '-0042'
4.7.2. Formattage de chaines à la printf
¶
Note
The formatting operations described here exhibit a variety of quirks that
lead to a number of common errors (such as failing to display tuples and
dictionaries correctly). Using the newer str.format()
interface
helps avoid these errors, and also provides a generally more powerful,
flexible and extensible approach to formatting text.
Les objets str n’exposent qu’une opération : L’opérateur %
(modulo). Aussi connu sous le nom d’opérateur de formatting ouopérateur d”interpolation. Étant donné format % values
(où format est une chaîne), les marqueurs %
de format sont remplacés par zéro ou plusieurs éléments de values. L’effet est similaire à la fonction sprintf()
du langage C.
Si format ne nécessite qu’un seul argument, values peut être un objet unique. [5] Si values est un tuple, il doit contenir exactement lenombre d’éléments spécifiés par la chaîne de format, ou un seul objet de correspondances ( mapping object, par exemple, un dictionnaire).
Un indicateur de conversion contient deux ou plusieurs caractères et comporte les éléments suivants, qui doivent apparaître dans cet ordre :
- Le caractère
'%'
, qui marque le début du marqueur. - La clé de correspondance (facultative), composée d’une suite de caractères entre parenthèse (par exemple,
(somename)
). - Des options de conversion, facultatives, qui affectent le résultat de certains types de conversion.
- Largeur minimum (facultative). Si elle vaut
'*'
(astérisque), la largeur est lue de l’élément suivant du tuple values, et l’objet à convertir vient après la largeur de champ minimale et la précision facultative. - Précision (facultatif), donnée sous la forme d’un “« ”.”« (point) suivi de la précision. Si la précision est
'*'
(un astérisque), la précision est lue à partir de l’élément suivant du tuple values et la valeur à convertir vient ensuite. - Modificateur de longueur (facultatif).
- Type de conversion.
Lorsque l’argument de droite est un dictionnaire (ou un autre type de mapping), les marqueurs dans la chaîne doivent inclure une clé présente dans le dictionnaire, écrite entre parenthèses, immédiatement après le caractère '%'
. La clé indique quelle valeur du dictionnaire doit être formatée. Par exemple :
>>> print('%(language)s has %(number)03d quote types.' %
... {'language': "Python", "number": 2})
Python has 002 quote types.
Dans ce cas, aucune *
ne peuvent se trouver dans le format (car ces *
nécessitent une liste (accès séquentiel) de paramètres).
Les caractères indicateurs de conversion sont :
Option | Signification |
---|---|
'#' |
La conversion utilisera la « forme alternative » (définie ci-dessous). |
'0' |
Les valeurs numériques converties seront complétée de zéros. |
'-' |
La valeur convertie est ajustée à gauche (remplace la conversion '0' si les deux sont données). |
' ' |
(un espace) Un espace doit être laissé avant un nombre positif (ou chaîne vide) produite par la conversion d’une valeur signée. |
'+' |
Un caractère de signe ('+' ou '-' ) précéde la valeur convertie (remplace le marqueur « espace »). |
Un modificateur de longueur (h
, l
ou L
) peut être présent, mais est ignoré car il est pas nécessaire pour Python - donc par exemple %ld
est identique à %d
.
Les types utilisables dans les conversion sont :
Conversion | Signification | Notes |
---|---|---|
'd' |
Entier décimal signé. | |
'i' |
Entier décimal signé. | |
'o' |
Valeur octale signée. | (1) |
'u' |
Type obsolète - identique à 'd' . |
(7) |
'x' |
Hexadécimal signé (en minuscules). | (2) |
'X' |
Hexadécimal signé (capitales). | (2) |
'e' |
Format exponentiel pour un float (minuscule). | (3) |
'E' |
Format exponentiel pour un float (en capitales). | (3) |
'f' |
Format décimal pour un float. | (3) |
'F' |
Format décimal pour un float. | (3) |
'g' |
Format float. Utilise le format exponentiel minuscules si l’exposant est inférieur à -4 ou pas plus petit que la précision, sinon le format décimal. | (4) |
'G' |
Format float. Utilise le format exponentiel en capitales si l’exposant est inférieur à -4 ou pas plus petit que la précision, sinon le format décimal. | (4) |
'c' |
Un seul caractère (accepte des entiers ou une chaîne d’un seul caractère). | |
'r' |
String (convertit n’importe quel objet Python avec repr() ). |
(5) |
's' |
String (convertit n’importe quel objet Python avec str() ). |
(5) |
'a' |
String (convertit n’importe quel objet Python en utilisant ascii() ). |
(5) |
'%' |
Aucun argument n’est converti, donne un caractère de '%' dans le résultat. |
Notes :
The alternate form causes a leading zero (
'0'
) to be inserted between left-hand padding and the formatting of the number if the leading character of the result is not already a zero.The alternate form causes a leading
'0x'
or'0X'
(depending on whether the'x'
or'X'
format was used) to be inserted between left-hand padding and the formatting of the number if the leading character of the result is not already a zero.La forme alternative implique la présence d’un point décimal, même si aucun chiffre ne le suit.
La précision détermine le nombre de chiffres après la virgule, 6 par défaut.
La forme alternative implique la présence d’un point décimal et les zéros non significatifs sont conservés (ils ne le seraient pas autrement).
La précision détermine le nombre de chiffres significatifs avant et après la virgule. 6 par défaut.
Si la précision est
N
, la sortie est tronquée àN
caractères.
- Voir la PEP 237.
Puisque les chaînes Python ont une longueur explicite, les conversions %s
ne considèrent pas '\0'
comme la fin de la chaîne.
Modifié dans la version 3.1: Les conversions %f
pour nombres dont la valeur absolue est supérieure à 1e50 ne sont plus remplacés par des conversions %g
.
4.8. Séquences Binaires — bytes
, bytearray
, memoryview
¶
Les principaux types natifs pour manipuler des données binaires sont bytes
et bytearray
. Ils sont supportés par memoryview
qui utilise le buffer protocol pour accéder à la mémoire d’autres objets binaires sans avoir besoin d’en faire une copie.
Le module array
permet le stockage efficace de types basiques comme les entiers de 32 bits et les float double precision IEEE754.
4.8.1. Bytes¶
Les Bytes sont des séquences immuables d’octets. Comme beaucoup de protocoles binaires utilisent l’ASCII, les objets Bytes offrent plusieurs méthodes qui ne sont valables que lors de la manipulation de données ASCII et sont étroitement liés aux objets str dans moulte autres aspects.
Tout d’abord, la syntaxe des bytes littéraux est en grande partie la même que pour les chaînes littérales, en dehors du préfixe b
:
- Les guillemets simples :
b'autorisent aussi les guillemets "doubles"'
- Les guillemets doubles :
b"permettent aussi les guillemets 'simples'"
. - Les guillemets triples :
b'''3 single quotes'''
,b"""3 double quotes"""
Seuls les caractères ASCII sont autorisés dans les littéraux de bytes (quel que soit l’encodage du code source déclaré). Toutes les valeurs au delà de 127 doivent être entrés dans littéraux de bytes en utilisant une séquence d’échappement appropriée.
Comme avec les chaînes littérales, les bytes littéraux peuvent également utiliser un préfixe r
pour désactiver le traitement des séquences d’échappement. Voir String and Bytes literals pour plus d’informations sur les différentes formes littérales de bytes, y compris les séquences d’échappement supportées.
Bien que les bytes littéraux, et leurs représentation, soient basés sur du texte ASCII, les bytes se comportent en fait comme des séquences immuables de nombres entiers, dont les valeurs sont restreintes dans 0 <= x < 256
(ne pas respecter cette restriction lève une ValueError
. Ceci est fait délibérément afin de souligner que, bien que de nombreux encodages binaires soient compatibles avec l’ASCII, et peuvent être manipulés avec des algorithmes orientés texte, ce n’est généralement pas le cas pour les données binaires arbitraires (appliquer aveuglément des algorithmes de texte sur des données binaires qui ne sont pas compatibles ASCII conduit généralement à leur corruption).
En plus des formes littérales, des objets bytes peuvent être créés par de nombreux moyens :
- Un objet bytes rempli de zéros d’une longueur spécifiée :
bytes(10)
- D’un itérable d’entiers :
bytes(range(20))
- Copier des données binaires existantes via le buffer protocol :
bytes(obj)
Voir aussi la fonction native bytes.
Puisque 2 chiffres hexadécimaux correspondent précisément à un seul octet, les nombres hexadécimaux sont un format couramment utilisé pour décrire les données binaires. Par conséquent, le type bytes a une méthode de classe pour lire des données dans ce format :
-
classmethod
bytes.
fromhex
(string)¶ Cette méthode de la classe
bytes
renvoie un objet bytes, décodant la chaîne donnée. La chaîne doit contenir deux chiffres hexadécimaux par octet, les espaces ASCII sont ignorés.>>> bytes.fromhex('2Ef0 F1f2 ') b'.\xf0\xf1\xf2'
Comme les objets bytes sont des séquences d’entiers (semblables à un tuple), pour une instance de bytes b, b[0]
sera un entier, tandis que« b[0:1]« sera un objet bytes de longueur 1. (Cela contraste avec les chaînes, où l’indexation et le slicing donne une chaîne de longueur 1)
La représentation des bytes utilise le format littéral (b'...'
) car il est souvent plus utile que par exemple bytes([46, 46, 46])
. Vous pouvez toujours convertir un bytes en liste d’entiers en utilisant list(b)
.
Note
Pour les utilisateurs de Python 2.x : Dans la série 2.x de Python, une variété de conversions implicites entre les chaînes 8-bit (la chose la plus proche d’un type natif de données binaires offert par Python 2) et des chaînes Unicode étaient permises. C’était solution de contournement, pour garder la rétro-compatibilité, par rapport au fait que Python ne prenait initialement en charge que le texte 8 bits, le texte Unicode est un ajout ultérieur. En Python 3.x, ces conversions implicites ont disparues - les conversions entre les données binaires et texte Unicode doivent être explicites, et les bytes sont toujours différents des chaînes.
4.8.2. Objets bytearray¶
La classe bytearray
est une contrepartie mutable à la classe bytes
. Il n’y a pas de syntaxe littérale dédiée aux bytearray, ils sont toujours créés en appelant le constructeur :
- Créer une instance vide:
bytearray()
- Créer une instance remplie de zéros d’une longueur donnée :
bytearray(10)
- À partir d’un itérable d’entiers :
bytearray(range(20))
- Copie des données binaires existantes via le buffer protocol :
bytearray(b'Hi!')
Comme les bytearray sont mutables, ils prennent en charge les opérations de séquence mutables en plus des opérations communes de bytes et bytearray décrites dans Opérations sur les bytes et bytearray.
Voir aussi la fonction native bytearray.
Puisque 2 chiffres hexadécimaux correspondent précisément à un octet, les nombres hexadécimaux sont un format couramment utilisé pour décrire les données binaires. Par conséquent, le type bytearray a une méthode de classe pour lire les données dans ce format :
-
classmethod
bytearray.
fromhex
(string)¶ Cette méthode de la classe
bytearray
renvoie un objet bytearray, décodant la chaîne donnée. La chaîne doit contenir deux chiffres hexadécimaux par octet, les espaces ASCII sont ignorés.>>> bytearray.fromhex('2Ef0 F1f2 ') bytearray(b'.\xf0\xf1\xf2')
Comme les bytearray sont des séquences d’entiers (semblables à une liste), pour un objet bytearray b, b[0]
sera un entier, tandis que b[0:1]
sera un objet bytearray de longueur 1. (Ceci contraste avec les chaînes de texte, où l’indexation et le slicing produit une chaîne de longueur 1)
La représentation des objets bytearray utilise le format littéral des bytes (bytearray(b'...')
) car il est souvent plus utile que par exemple bytearray([46, 46, 46])
. Vous pouvez toujours convertir un objet bytearray en une liste de nombres entiers en utilisant list(b)
.
4.8.3. Opérations sur les bytes et bytearray¶
bytes et bytearray prennent en charge les opérations communes des séquences. Ils interagissent non seulement avec des opérandes de même type, mais aussi avec les bytes-like object. En raison de cette flexibilité, ils peuvent être mélangés librement dans des opérations sans provoquer d’erreurs. Cependant, le type du résultat peut dépendre de l’ordre des opérandes.
Note
Les méthodes sur les bytes et les bytearray n’acceptent pas les chaînes comme arguments, tout comme les méthodes sur les chaînes n’acceptent pas les bytes comme arguments. Par exemple, vous devez écrire
a = "abc"
b = a.replace("a", "f")
et :
a = b"abc"
b = a.replace(b"a", b"f")
Quelques opérations de bytes et bytesarray supposent l’utilisation de formats binaires compatibles ASCII, et donc doivent être évités lorsque vous travaillez avec des données binaires arbitraires. Ces restrictions sont couvertes ci-dessous.
Note
Utiliser ces opérations basées sur l’ASCII pour manipuler des données binaires qui ne sont pas au format ASCII peut les corrompre.
Les méthodes suivantes sur les bytes et bytearray peuvent être utilisées avec des données binaires arbitraires.
-
bytes.
count
(sub[, start[, end]])¶ -
bytearray.
count
(sub[, start[, end]])¶ Renvoie le nombre d’occurrences qui ne se chevauchent pas de la sous-séquence sub dans l’intervalle [start, end]. Les arguments facultatifs start et end sont interprétés comme pour un slice.
La sous-séquence à rechercher peut être un quelconque bytes-like object ou un nombre entier compris entre 0 et 255.
Modifié dans la version 3.3: Accepte aussi un nombre entier compris entre 0 et 255 comme sous-séquence.
-
bytes.
decode
(encoding= »utf-8 », errors= »strict »)¶ -
bytearray.
decode
(encoding= »utf-8 », errors= »strict »)¶ Décode les octets donnés, et le renvoie sous forme d’une chaîne de caractères. L’encodage par défaut est
'utf-8'
. errors peut être donné pour changer de système de gestion des erreurs. Sa valeur par défaut est'strict'
, ce qui signifie que les erreurs d’encodage lèvent uneUnicodeError
. Les autres valeurs possibles sont'ignore'
,'replace'
et tout autre nom enregistré viacodecs.register_error()
, voir la section Error Handlers. Pour une liste des encodages possibles, voir la section Standard Encodings.Note
Passer l’argument encoding à
str
permet de décoder tout bytes-like object directement, sans avoir besoin d’utiliser un bytes ou bytearray temporaire.Modifié dans la version 3.1: Gère les arguments nommés.
-
bytes.
endswith
(suffix[, start[, end]])¶ -
bytearray.
endswith
(suffix[, start[, end]])¶ Donne
True
si les octets se terminent par suffix, sinonFalse
. suffix peut aussi être un tuple de suffixes à rechercher. Avec l’argument optionnel start, la recherche se fait à partir de cette position. Avec l’argument optionnel end, la comparaison s’arrête à cette position.Les suffixes à rechercher peuvent être n’importe quel bytes-like object.
-
bytes.
find
(sub[, start[, end]])¶ -
bytearray.
find
(sub[, start[, end]])¶ Donne la première position où le sub se trouve dans les données, de telle sorte que sub soit contenue dans
s[start:end]
. Les arguments facultatifs start et end sont interprétés comme dans la notation des slices. Donne-1
si sub n’est pas trouvé.La sous-séquence à rechercher peut être un quelconque bytes-like object ou un nombre entier compris entre 0 et 255.
Note
La méthode
find()
ne doit être utilisée que si vous avez besoin de connaître la position de sub. Pour vérifier si sub est présent ou non, utilisez l’opérateurin
>>> b'Py' in b'Python' True
Modifié dans la version 3.3: Accepte aussi un nombre entier compris entre 0 et 255 comme sous-séquence.
-
bytes.
index
(sub[, start[, end]])¶ -
bytearray.
index
(sub[, start[, end]])¶ Comme
find()
, mais lève uneValueError
lorsque la séquence est introuvable.La sous-séquence à rechercher peut être un quelconque bytes-like object ou un nombre entier compris entre 0 et 255.
Modifié dans la version 3.3: Accepte aussi un nombre entier compris entre 0 et 255 comme sous-séquence.
-
bytes.
join
(iterable)¶ -
bytearray.
join
(iterable)¶ Return a bytes or bytearray object which is the concatenation of the binary data sequences in the iterable iterable. A
TypeError
will be raised if there are any values in iterable that are note bytes-like objects, includingstr
objects. The separator between elements is the contents of the bytes or bytearray object providing this method.
-
static
bytes.
maketrans
(from, to)¶ -
static
bytearray.
maketrans
(from, to)¶ Cette méthode statique renvoie une table de traduction utilisable par
bytes.translate()
qui permettra de changer chaque caractère de from par un caractère à la même position dans to; from et to doivent tous deux être des bytes-like objects et avoir la même longueur.Nouveau dans la version 3.1.
-
bytes.
partition
(sep)¶ -
bytearray.
partition
(sep)¶ Divise la séquence à la première occurrence de sep, et renvoie un 3-tuple contenant la partie précédant le séparateur, le séparateur, et la partie suivant le séparateur. Si le séparateur est pas trouvé, le 3-tuple renvoyé contiendra une copie de la séquence d’origine, suivi de deux bytes ou bytearray vides.
Le séparateur à rechercher peut être tout bytes-like object.
-
bytes.
replace
(old, new[, count])¶ -
bytearray.
replace
(old, new[, count])¶ Renvoie une copie de la séquence dont toutes les occurrences de la sous-séquence old sont remplacées par new. Si l’argument optionnel count est donné, seules les count premières occurrences de sont remplacés.
La sous-séquence à rechercher et son remplacement peuvent être n’importe quel bytes-like object.
Note
La version bytearray de cette méthode ne modifie pas les octets, elle produit toujours un nouvel objet, même si aucune modification n’a été effectuée.
-
bytes.
rfind
(sub[, start[, end]])¶ -
bytearray.
rfind
(sub[, start[, end]])¶ Donne la plus grande position de sub dans la séquence, de telle sorte que sub soit dans
s[start:end]
. Les arguments facultatifs start et end sont interprétés comme dans lanotation des slices. Donne-1
si sub n’est pas trouvable.La sous-séquence à rechercher peut être un quelconque bytes-like object ou un nombre entier compris entre 0 et 255.
Modifié dans la version 3.3: Accepte aussi un nombre entier compris entre 0 et 255 comme sous-séquence.
-
bytes.
rindex
(sub[, start[, end]])¶ -
bytearray.
rindex
(sub[, start[, end]])¶ Semblable à
rfind()
mais lève uneValueError
lorsque sub est introuvable.La sous-séquence à rechercher peut être un quelconque bytes-like object ou un nombre entier compris entre 0 et 255.
Modifié dans la version 3.3: Accepte aussi un nombre entier compris entre 0 et 255 comme sous-séquence.
-
bytes.
rpartition
(sep)¶ -
bytearray.
rpartition
(sep)¶ Coupe la séquence à la dernière occurrence de sep, et renvoie un tuple de trois elements contenant la partie précédent le séparateur, le séparateur, et la partie suivant le séparateur. Si le séparateur n’est pas trouvé, le tuple contiendra une copie de la séquence d’origine, suivi de deux bytes ou bytesarray vides.
Le séparateur à rechercher peut être tout bytes-like object.
-
bytes.
startswith
(prefix[, start[, end]])¶ -
bytearray.
startswith
(prefix[, start[, end]])¶ Donne
True
si les données binaires commencent par le prefix spécifié, sinonFalse
. prefix peut aussi être un tuple de préfixes à rechercher. Avec l’argument start la recherche commence à cette position. Avec l’argument end option, la recherche s’arrête à cette position.Le préfixe(s) à rechercher peuvent être n’importe quel bytes-like object.
-
bytes.
translate
(table[, delete])¶ -
bytearray.
translate
(table[, delete])¶ Renvoie une copie du bytes ou bytearray dont tous les octets de delete sont supprimés, et les octets restants changés par la table de correspondance donnée, qui doit être un objet bytes d’une longueur de 256.
Vous pouvez utiliser la méthode
bytes.maketrans()
pour créer une table de correspondance.Donnez
None
comme table pour seulement supprimer des caractères :>>> b'read this short text'.translate(None, b'aeiou') b'rd ths shrt txt'
Les méthodes suivantes sur les bytes et bytearray supposent par défaut que les données traitées sont compatible ASCII, mais peuvent toujours être utilisées avec des données binaires, arbitraires, en passant des arguments appropriés. Notez que toutes les méthodes de bytearray de cette section ne travaillent jamais sur l’objet lui même, mais renvoient un nouvel objet.
-
bytes.
center
(width[, fillbyte])¶ -
bytearray.
center
(width[, fillbyte])¶ Renvoie une copie de l’objet centrée dans une séquence de longueur width. Le remplissage est fait en utilisant fillbyte (qui par défaut est un espace ASCII). Pour les objets
bytes
, la séquence initiale est renvoyée si width est inférieur ou égal àlen(s)
.Note
La version bytearray de cette méthode ne modifie pas les octets, elle produit toujours un nouvel objet, même si aucune modification n’a été effectuée.
-
bytes.
ljust
(width[, fillbyte])¶ -
bytearray.
ljust
(width[, fillbyte])¶ Renvoie une copie de l’objet aligné à gauche dans une séquence de longueur width. Le remplissage est fait en utilisant fillbyte (par défaut un espace ASCII). Pour les objets
bytes
, la séquence initiale est renvoyée si width est inférieure ou égale àlen(s)
.Note
La version bytearray de cette méthode ne modifie pas les octets, elle produit toujours un nouvel objet, même si aucune modification n’a été effectuée.
-
bytes.
lstrip
([chars])¶ -
bytearray.
lstrip
([chars])¶ Renvoie une copie de la séquence dont certains préfixes ont été supprimés. L’argument chars est une séquence binaire spécifiant le jeu d’octets à supprimer. Ce nom se réfère au fait de cette méthode est généralement utilisée avec des caractères ASCII. En cas d’omission ou
None
, la valeur par défaut de chars permet de supprimer des espaces ASCII. L’argument chars n’est pas un préfixe, toutes les combinaisons de ses valeurs sont supprimées>>> b' spacious '.lstrip() b'spacious ' >>> b'www.example.com'.lstrip(b'cmowz.') b'example.com'
La séquence de valeurs à supprimer peut être tout bytes-like object.
Note
La version bytearray de cette méthode ne modifie pas les octets, elle produit toujours un nouvel objet, même si aucune modification n’a été effectuée.
-
bytes.
rjust
(width[, fillbyte])¶ -
bytearray.
rjust
(width[, fillbyte])¶ Renvoie une copie de l’objet justifié à droite dans une séquence de longueur width. Le remplissage est fait en utilisant le caractère fillbyte (par défaut est un espace ASCII). Pour les objets
bytes
, la séquence d’origine est renvoyée si width est inférieure ou égale àlen(s)
.Note
La version bytearray de cette méthode ne modifie pas les octets, elle produit toujours un nouvel objet, même si aucune modification n’a été effectuée.
-
bytes.
rsplit
(sep=None, maxsplit=-1)¶ -
bytearray.
rsplit
(sep=None, maxsplit=-1)¶ Divise la séquence d’octets en sous-séquences du même type, en utilisant sep comme séparateur. Si maxsplit est donné, c’est le nombre maximum de divisions qui pourront être faites, celles « à droite ». Si sep est pas spécifié ou est
None
, toute sous-séquence composée uniquement d’espaces ASCII est un séparateur. En dehors du fait qu’il découpe par la droite,rsplit()
se comporte commesplit()
qui est décrit en détail ci-dessous.
-
bytes.
rstrip
([chars])¶ -
bytearray.
rstrip
([chars])¶ Renvoie une copie de la séquence dont des octets finaux sont supprimés. L’argument chars est une séquence d’octets spécifiant le jeu de caractères à supprimer - . En cas d’omission ou
None
, les espaces ASCII sont supprimés. L’argument chars n’est pas un suffixe : toutes les combinaisons de ses valeurs sont retirées :>>> b' spacious '.rstrip() b' spacious' >>> b'mississippi'.rstrip(b'ipz') b'mississ'
La séquence de valeurs à supprimer peut être tout bytes-like object.
Note
La version bytearray de cette méthode ne modifie pas les octets, elle produit toujours un nouvel objet, même si aucune modification n’a été effectuée.
-
bytes.
split
(sep=None, maxsplit=-1)¶ -
bytearray.
split
(sep=None, maxsplit=-1)¶ Divise la séquence en sous-séquences du même type, en utilisant sep comme séparateur. Si maxsplit est donné, c’est le nombre maximum de divisions qui pourront être faites (la liste aura donc au plus
maxsplit+1
éléments), Si maxsplit n’est pas spécifié ou faut-1
, il n’y a aucune limite au nombre de découpes (elles sont toutes effectuées).Si sep est donné, les délimiteurs consécutifs ne sont pas regroupés et ainsi délimitent ainsi des chaînes vides (par exemple,
b'1,,2'.split(b',')
donne[b'1', b'', b'2']
). L’argument sep peut contenir plusieurs sous séquences (par exemple,b'1<>2<>3'.split(b'<>')
renvoie[b'1', b'2', b'3']
). Découper une chaîne vide en spécifiant sep donne[b'']
ou[bytearray(b'')]
en fonction du type de l’objet découpé. L’argument sep peut être n’importe quel bytes-like object.Par exemple :
>>> b'1,2,3'.split(b',') [b'1', b'2', b'3'] >>> b'1,2,3'.split(b',', maxsplit=1) [b'1', b'2,3'] >>> b'1,2,,3,'.split(b',') [b'1', b'2', b'', b'3', b'']
Si sep n’est pas spécifié ou est
None
, un autre algorithme de découpe est appliqué : les espaces ASCII consécutifs sont considérés comme un seul séparateur, et le résultat ne contiendra pas les chaînes vides de début ou de la fin si la chaîne est préfixée ou suffixé d’espaces. Par conséquent, diviser une séquence vide ou une séquence composée d’espaces ASCII avec un séparateurNone
renvoie[]
.Par exemple :
>>> b'1 2 3'.split() [b'1', b'2', b'3'] >>> b'1 2 3'.split(maxsplit=1) [b'1', b'2 3'] >>> b' 1 2 3 '.split() [b'1', b'2', b'3']
-
bytes.
strip
([chars])¶ -
bytearray.
strip
([chars])¶ Renvoie une copie de la séquence dont des caractères initiaux et finaux sont supprimés. L’argument chars est une séquence spécifiant le jeu d’octets à supprimer - le nom se réfère au fait de cette méthode est généralement utilisée avec des caractères ASCII. En cas d’omission ou
None
, les espaces ASCII sont supprimés. L’argument chars n’est ni un préfixe ni un suffixe, toutes les combinaisons de ses valeurs sont supprimées :>>> b' spacious '.strip() b'spacious' >>> b'www.example.com'.strip(b'cmowz.') b'example'
La séquence de valeurs à supprimer peut être tout bytes-like object.
Note
La version bytearray de cette méthode ne modifie pas les octets, elle produit toujours un nouvel objet, même si aucune modification n’a été effectuée.
Les méthodes suivantes sur les bytes et bytearray supposent l’utilisation d’un format binaire compatible ASCII, et donc doivent être évités lorsque vous travaillez avec des données binaires arbitraires. Notez que toutes les méthodes de bytearray de cette section ne modifient pas les octets, ils produisent de nouveaux objets.
-
bytes.
capitalize
()¶ -
bytearray.
capitalize
()¶ Renvoie une copie de la séquence dont chaque octet est interprété comme un caractère ASCII, le premier octet en capitale et le reste en minuscules. Les octets non-ASCII ne sont pas modifiés.
Note
La version bytearray de cette méthode ne modifie pas les octets, elle produit toujours un nouvel objet, même si aucune modification n’a été effectuée.
-
bytes.
expandtabs
(tabsize=8)¶ -
bytearray.
expandtabs
(tabsize=8)¶ Renvoie une copie de la séquence où toutes les tabulations ASCII sont remplacées par un ou plusieurs espaces ASCII, en fonction de la colonne courante et de la taille de tabulation donnée. Les positions des tabulations se trouvent tous les tabsize caractères (8 par défaut, ce qui donne les positions de tabulations aux colonnes 0, 8, 16 et ainsi de suite). Pour travailler sur la séquence, la colonne en cours est mise à zéro et la séquence est examinée octets par octets. Si l’octet est une tabulation ASCII (
b' '
), un ou plusieurs espaces sont insérés au résultat jusqu’à ce que la colonne courante soit égale à la position de tabulation suivante. (Le caractère tabulation lui-même n’est pas copié.) Si l’octet courant est un saut de ligne ASCII (b' '
) ou un retour chariot (b'\r'
), il est copié et la colonne en cours est remise à zéro. Tout autre octet est copié inchangé et la colonne en cours est incrémentée de un indépendamment de la façon dont l’octet est représenté lors de l’affichage :>>> b'01\t012\t0123\t01234'.expandtabs() b'01 012 0123 01234' >>> b'01\t012\t0123\t01234'.expandtabs(4) b'01 012 0123 01234'
Note
La version bytearray de cette méthode ne modifie pas les octets, elle produit toujours un nouvel objet, même si aucune modification n’a été effectuée.
-
bytes.
isalnum
()¶ -
bytearray.
isalnum
()¶ Donne
True`` si tous les caractères de la chaîne sont des caractères ASCII alphabetiques ou chiffres. et que la séquence n'est pas vide, sinon ``False
. Les caractères ASCII alphabétiques sont les suivantsb'abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ'
et les chiffres :b'0123456789'
.Par exemple :
>>> b'ABCabc1'.isalnum() True >>> b'ABC abc1'.isalnum() False
-
bytes.
isalpha
()¶ -
bytearray.
isalpha
()¶ Donne
True
si tous les octets dans la séquence sont des caractères alphabétiques ASCII et la que la séquence n’est pas vide, sinonFalse
. Les caractères ASCIIalphabétiques sont :b'abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ'
.Par exemple :
>>> b'ABCabc'.isalpha() True >>> b'ABCabc1'.isalpha() False
-
bytes.
isdigit
()¶ -
bytearray.
isdigit
()¶ Donne
True
si tous les octets de la séquence sont des chiffres ASCII et que la séquence n’est pas vide, sinonFalse
. Les chiffres ASCII sontb'0123456789'
.Par exemple :
>>> b'1234'.isdigit() True >>> b'1.23'.isdigit() False
-
bytes.
islower
()¶ -
bytearray.
islower
()¶ Donne
True
s’il y a au moins un caractère ASCII minuscule dans la séquence et aucune capitale, sinonFalse
.Par exemple :
>>> b'hello world'.islower() True >>> b'Hello world'.islower() False
Lea caractères ASCII minuscules sont
b'abcdefghijklmnopqrstuvwxyz'
. Les capitales ASCII sontb'ABCDEFGHIJKLMNOPQRSTUVWXYZ'
.
-
bytes.
isspace
()¶ -
bytearray.
isspace
()¶ Return true if all bytes in the sequence are ASCII whitespace and the sequence is not empty, false otherwise. ASCII whitespace characters are those byte values in the sequence b” tnrx0bf” (space, tab, newline, carriage return, vertical tab, form feed).
-
bytes.
istitle
()¶ -
bytearray.
istitle
()¶ Donne
True
si la séquence ASCII est titlecased, et qu’elle ne soit pas vide, sinonFalse
. Voirbytes.title()
pour plus de détails sur ladéfinition de titlecase.Par exemple :
>>> b'Hello World'.istitle() True >>> b'Hello world'.istitle() False
-
bytes.
isupper
()¶ -
bytearray.
isupper
()¶ Donne
True
s’il y a au moins un caractère alphabétique majuscule ASCII dans la séquence et aucun caractères ASCII minuscules, sinonFalse
.Par exemple :
>>> b'HELLO WORLD'.isupper() True >>> b'Hello world'.isupper() False
Lea caractères ASCII minuscules sont
b'abcdefghijklmnopqrstuvwxyz'
. Les capitales ASCII sontb'ABCDEFGHIJKLMNOPQRSTUVWXYZ'
.
-
bytes.
lower
()¶ -
bytearray.
lower
()¶ Renvoie une copie de la séquence dont tous les caractères ASCII en majuscules sont convertis en leur équivalent en minuscules.
Par exemple :
>>> b'Hello World'.lower() b'hello world'
Lea caractères ASCII minuscules sont
b'abcdefghijklmnopqrstuvwxyz'
. Les capitales ASCII sontb'ABCDEFGHIJKLMNOPQRSTUVWXYZ'
.Note
La version bytearray de cette méthode ne modifie pas les octets, elle produit toujours un nouvel objet, même si aucune modification n’a été effectuée.
-
bytes.
splitlines
(keepends=False)¶ -
bytearray.
splitlines
(keepends=False)¶ Renvoie une liste des lignes de la séquence d’octets, découpant au niveau des fin de lignes ASCII. Cette méthode utilise l’approche universal newlines pour découper les lignes. Les fins de ligne ne sont pas inclus dans la liste des résultats, sauf si keepends est donné et vrai.
Par exemple :
>>> b'ab c\n\nde fg\rkl\r\n'.splitlines() [b'ab c', b'', b'de fg', b'kl'] >>> b'ab c\n\nde fg\rkl\r\n'.splitlines(keepends=True) [b'ab c\n', b'\n', b'de fg\r', b'kl\r\n']
Contrairement à
split()
lorsque le délimiteur sep est fourni, cette méthode renvoie une liste vide pour la chaîne vide, et un saut de ligne à la fin ne se traduit pas par une ligne supplémentaire :>>> b"".split(b'\n'), b"Two lines\n".split(b'\n') ([b''], [b'Two lines', b'']) >>> b"".splitlines(), b"One line\n".splitlines() ([], [b'One line'])
-
bytes.
swapcase
()¶ -
bytearray.
swapcase
()¶ Renvoie une copie de la séquence dont tous les caractères ASCII minuscules sont convertis en majuscules et vice-versa.
Par exemple :
>>> b'Hello World'.swapcase() b'hELLO wORLD'
Lea caractères ASCII minuscules sont
b'abcdefghijklmnopqrstuvwxyz'
. Les capitales ASCII sontb'ABCDEFGHIJKLMNOPQRSTUVWXYZ'
.Contrairement à
str.swapcase()
,bin.swapcase().swapcase() == bin
est toujours vrai. Les conversions majuscule/minuscule en ASCII étant toujours symétrique, ce qui n’est pas toujours vrai avec Unicode.Note
La version bytearray de cette méthode ne modifie pas les octets, elle produit toujours un nouvel objet, même si aucune modification n’a été effectuée.
-
bytes.
title
()¶ -
bytearray.
title
()¶ Renvoie une version titlecased de la séquence d’octets où les mots commencent par un caractère ASCII majuscule et les caractères restants sont en minuscules. Les octets non capitalisables ne sont pas modifiés.
Par exemple :
>>> b'Hello world'.title() b'Hello World'
Les caractères ASCII minuscules sont
b'abcdefghijklmnopqrstuvwxyz'
. Les caractères ASCII majuscules sontb'ABCDEFGHIJKLMNOPQRSTUVWXYZ'
. Aucun autre octet n’est capitalisable.Pour l’algorithme, la notion de mot est définie simplement et indépendamment de la langue comme un groupe de lettres consécutives. La définition fonctionnedans de nombreux contextes, mais cela signifie que les apostrophes (typiquement dela forme possessive en Anglais) forment les limites de mot, ce qui n’est pas toujours le résultat souhaité :
>>> b"they're bill's friends from the UK".title() b"They'Re Bill'S Friends From The Uk"
Une solution pour contourner le problème des apostrophes peut être obtenue en utilisant des expressions rationnelles :
>>> import re >>> def titlecase(s): ... return re.sub(rb"[A-Za-z]+('[A-Za-z]+)?", ... lambda mo: mo.group(0)[0:1].upper() + ... mo.group(0)[1:].lower(), ... s) ... >>> titlecase(b"they're bill's friends.") b"They're Bill's Friends."
Note
La version bytearray de cette méthode ne modifie pas les octets, elle produit toujours un nouvel objet, même si aucune modification n’a été effectuée.
-
bytes.
upper
()¶ -
bytearray.
upper
()¶ Renvoie une copie de la séquence dont tous les caractères ASCII minuscules sont convertis en leur équivalent majuscule.
Par exemple :
>>> b'Hello World'.upper() b'HELLO WORLD'
Lea caractères ASCII minuscules sont
b'abcdefghijklmnopqrstuvwxyz'
. Les capitales ASCII sontb'ABCDEFGHIJKLMNOPQRSTUVWXYZ'
.Note
La version bytearray de cette méthode ne modifie pas les octets, elle produit toujours un nouvel objet, même si aucune modification n’a été effectuée.
-
bytes.
zfill
(width)¶ -
bytearray.
zfill
(width)¶ Renvoie une copie de la séquence remplie par la gauche du chiffre
b'0'
pour en faire une séquence de longueur width. Un préfixe (b'+'
/b'-'
) est permis par l’insertion du caractère de remplissage après le caractère de signe plutôt qu’avant. Pour les objetsbytes
la séquence d’origine est renvoyée si width est inférieur ou égale àlen(seq)
.Par exemple :
>>> b"42".zfill(5) b'00042' >>> b"-42".zfill(5) b'-0042'
Note
La version bytearray de cette méthode ne modifie pas les octets, elle produit toujours un nouvel objet, même si aucune modification n’a été effectuée.
4.8.4. Formatage de bytes a la printf
¶
Note
Les opérations de formatage décrites ici présentent une variété de bizarreries qui conduisent à un certain nombre d’erreurs classiques (typiquement, échouer à afficher des tuples ou des dictionnaires correctement). Si la valeur à afficher peut être un tuple ou un dictionnaire, mettez le a l’intérieur d’un autre tuple.
Les objets bytes (bytes
et bytearray
) ont un unique opérateur : l’opérateur %
(modulo). Il est aussi connu sous le nom d’opérateur de mise en forme. Avec format % values
(où format est un objet bytes), les marqueurs de conversion %
dans format sont remplacés par zéro ou plus de values. L’effet est similaire à la fonction sprintf()
du langage C.
Si format ne nécessite qu’un seul argument, values peut être un objet unique. [5] Si values est un tuple, il doit contenir exactement le nombre d’éléments spécifiés dans le format en bytes, ou un seul objet de correspondances ( mapping object, par exemple, un dictionnaire).
Un indicateur de conversion contient deux ou plusieurs caractères et comporte les éléments suivants, qui doivent apparaître dans cet ordre :
- Le caractère
'%'
, qui marque le début du marqueur. - La clé de correspondance (facultative), composée d’une suite de caractères entre parenthèse (par exemple,
(somename)
). - Des options de conversion, facultatives, qui affectent le résultat de certains types de conversion.
- Largeur minimum (facultative). Si elle vaut
'*'
(astérisque), la largeur est lue de l’élément suivant du tuple values, et l’objet à convertir vient après la largeur de champ minimale et la précision facultative. - Précision (facultatif), donnée sous la forme d’un “« ”.”« (point) suivi de la précision. Si la précision est
'*'
(un astérisque), la précision est lue à partir de l’élément suivant du tuple values et la valeur à convertir vient ensuite. - Modificateur de longueur (facultatif).
- Type de conversion.
Lorsque l’argument de droite est un dictionnaire (ou un autre type de mapping), les marqueurs dans le bytes doivent inclure une clé présente dans le dictionnaire, écrite entre parenthèses, immédiatement après le caractère '%'
. La clé indique quelle valeur du dictionnaire doit être formatée. Par exemple :
>>> print(b'%(language)s has %(number)03d quote types.' %
... {b'language': b"Python", b"number": 2})
b'Python has 002 quote types.'
Dans ce cas, aucune *
ne peuvent se trouver dans le format (car ces *
nécessitent une liste (accès séquentiel) de paramètres).
Les caractères indicateurs de conversion sont :
Option | Signification |
---|---|
'#' |
La conversion utilisera la « forme alternative » (définie ci-dessous). |
'0' |
Les valeurs numériques converties seront complétée de zéros. |
'-' |
La valeur convertie est ajustée à gauche (remplace la conversion '0' si les deux sont données). |
' ' |
(un espace) Un espace doit être laissé avant un nombre positif (ou chaîne vide) produite par la conversion d’une valeur signée. |
'+' |
Un caractère de signe ('+' ou '-' ) précéde la valeur convertie (remplace le marqueur « espace »). |
Un modificateur de longueur (h
, l
ou L
) peut être présent, mais est ignoré car il est pas nécessaire pour Python - donc par exemple %ld
est identique à %d
.
Les types utilisables dans les conversion sont :
Conversion | Signification | Notes |
---|---|---|
'd' |
Entier décimal signé. | |
'i' |
Entier décimal signé. | |
'o' |
Valeur octale signée. | (1) |
'u' |
Type obsolète - identique à 'd' . |
(8) |
'x' |
Hexadécimal signé (en minuscules). | (2) |
'X' |
Hexadécimal signé (capitales). | (2) |
'e' |
Format exponentiel pour un float (minuscule). | (3) |
'E' |
Format exponentiel pour un float (en capitales). | (3) |
'f' |
Format décimal pour un float. | (3) |
'F' |
Format décimal pour un float. | (3) |
'g' |
Format float. Utilise le format exponentiel minuscules si l’exposant est inférieur à -4 ou pas plus petit que la précision, sinon le format décimal. | (4) |
'G' |
Format float. Utilise le format exponentiel en capitales si l’exposant est inférieur à -4 ou pas plus petit que la précision, sinon le format décimal. | (4) |
'c' |
Octet simple (Accepte un nombre entier ou un seul objet byte). | |
'b' |
Bytes (tout objet respectant le buffer protocol ou ayant la méthode __bytes__() ). |
(5) |
's' |
's' est un alias de 'b' et ne devrait être utilisé que pour du code Python2/3. |
(6) |
'a' |
Bytes (convertis n’importe quel objet Python en utilisant repr(obj).encode('ascii', 'backslashreplace) ). |
(5) |
'r' |
'r' est un alias de 'a' et ne devrait être utilise que dans du code Python2/3. |
(7) |
'%' |
Aucun argument n’est converti, donne un caractère de '%' dans le résultat. |
Notes :
The alternate form causes a leading zero (
'0'
) to be inserted between left-hand padding and the formatting of the number if the leading character of the result is not already a zero.The alternate form causes a leading
'0x'
or'0X'
(depending on whether the'x'
or'X'
format was used) to be inserted between left-hand padding and the formatting of the number if the leading character of the result is not already a zero.La forme alternative implique la présence d’un point décimal, même si aucun chiffre ne le suit.
La précision détermine le nombre de chiffres après la virgule, 6 par défaut.
La forme alternative implique la présence d’un point décimal et les zéros non significatifs sont conservés (ils ne le seraient pas autrement).
La précision détermine le nombre de chiffres significatifs avant et après la virgule. 6 par défaut.
Si la précision est
N
, la sortie est tronquée àN
caractères.b'%s'
est déprécié, mais ne sera pas retiré des version 3.x.b'%r'
est déprécié mais ne sera pas retiré dans Python 3.x.Voir la PEP 237.
Note
La version bytearray de cette méthode ne modifie pas les octets, elle produit toujours un nouvel objet, même si aucune modification n’a été effectuée.
Voir aussi
Nouveau dans la version 3.5.
4.8.5. Memory Views¶
Les memoryview
permettent a du code Python d’accéder sans copie aux données internes d’un objet pendant en charge le buffer protocol.
-
class
memoryview
(obj)¶ Crée une
memoryview
faisant référence à obj. obj doit supporter le buffer protocol. Les objets natifs pendant en charge le buffer protocol sontbytes
etbytearray
.Une
memoryview
a la notion d”element, qui est l’unité de mémoire atomique géré par l’objet obj d’origine. Pour de nombreux types simples commebytes
etbytearray
, l’élément est l’octet, mais pour d’autres types tels quearray.array
les éléments peuvent être plus grands.len(view)
est égal à la grandeur detolist
. Siview.ndim = 0
, la longueur vaut 1. Siview.ndim = 1
, la longueur est égale au nombre d’éléments de la vue. Pour les dimensions plus grandes, la longueur est égale à la longueur de la sous-liste représentée par la vue. L’attributitemsize
vous donnera la taille en octets d’un élément.Une
memoryview
autorise le découpage et l’indicage de ses données. Découper sur une dimension donnera une sous-vue:>>> v = memoryview(b'abcefg') >>> v[1] 98 >>> v[-1] 103 >>> v[1:4] <memory at 0x7f3ddc9f4350> >>> bytes(v[1:4]) b'bce'
Si le
format
est un des formats natif du modulestruct
, indexer avec un nombre entier ou un tuple de nombres entiers est aussi autorisé et renvoie un seul element du bon type. Les memoryview à une dimension peuvent être indexées avec un nombre entier ou un tuple d’un entier. Les memoryview multi-dimensionnelles peuvent être indexées avec des tuples d’exactement ndim entiers où ndim est le nombre de dimensions. Les memoryviews à zéro dimension peuvent être indexées avec un tuple vide.Voici un exemple avec un autre format que byte:
>>> import array >>> a = array.array('l', [-11111111, 22222222, -33333333, 44444444]) >>> m = memoryview(a) >>> m[0] -11111111 >>> m[-1] 44444444 >>> m[::2].tolist() [-11111111, -33333333]
Si l’objet sous-jacent est accessible en écriture, la memoryview autorisera les assignations de tranches à une dimension. Redimensionner n’est cependant pas autorisé:
>>> data = bytearray(b'abcefg') >>> v = memoryview(data) >>> v.readonly False >>> v[0] = ord(b'z') >>> data bytearray(b'zbcefg') >>> v[1:4] = b'123' >>> data bytearray(b'z123fg') >>> v[2:3] = b'spam' Traceback (most recent call last): File "<stdin>", line 1, in <module> ValueError: memoryview assignment: lvalue and rvalue have different structures >>> v[2:6] = b'spam' >>> data bytearray(b'z1spam')
Les memoryviews à une dimension de types hachables (lecture seule) avec les formats “B”, “b”, ou “c” sont aussi hachables. La fonction de hachage est définie tel que
hash(m) == hash(m.tobytes())
:>>> v = memoryview(b'abcefg') >>> hash(v) == hash(b'abcefg') True >>> hash(v[2:4]) == hash(b'ce') True >>> hash(v[::-2]) == hash(b'abcefg'[::-2]) True
Modifié dans la version 3.3: Les memoryviews à une dimension peuvent aussi être découpées. Les memoryviews à une dimension avec les formats “B”, “b”, ou “c” sont mainteannt hachables.
Modifié dans la version 3.4: memoryview est maintenant enregistrée automatiquement avec
collections.abc.Sequence
Modifié dans la version 3.5: Les memoryviews peut maintenant être indexées par un tuple d’entiers.
La
memoryview
dispose de plusieurs méthodes :-
__eq__
(exporter)¶ Une memoryview et un exporter de la PEP 3118 sont égaux si leurs formes sont équivalentes et si toutes les valeurs correspondantes sont égales, le format respectifs des opérandes étant interprétés en utilisant la syntaxe de
struct
.Pour le sous-ensemble des formats de
struct
supportés partolist()
,v
etw
sont égaux siv.tolist() ==w.tolist()
>>> import array >>> a = array.array('I', [1, 2, 3, 4, 5]) >>> b = array.array('d', [1.0, 2.0, 3.0, 4.0, 5.0]) >>> c = array.array('b', [5, 3, 1]) >>> x = memoryview(a) >>> y = memoryview(b) >>> x == a == y == b True >>> x.tolist() == a.tolist() == y.tolist() == b.tolist() True >>> z = y[::-2] >>> z == c True >>> z.tolist() == c.tolist() True
Si l’un des format n’est pas supporté par le module de
struct
, les objets seront toujours considérés différents (même si les formats et les valeurs contenues sont identiques) :>>> from ctypes import BigEndianStructure, c_long >>> class BEPoint(BigEndianStructure): ... _fields_ = [("x", c_long), ("y", c_long)] ... >>> point = BEPoint(100, 200) >>> a = memoryview(point) >>> b = memoryview(point) >>> a == point False >>> a == b False
Notez que pour les memoryview, comme pour les nombres à virgule flottante,
v is w
n’implique pasv == w
.Modifié dans la version 3.3: Les versions précédentes comparaient la mémoire brute sans tenir compte du format de l’objet ni de sa structure logique.
-
tobytes
()¶ Renvoie les données du buffer sous forme de bytes. Cela équivaut à appeler le constructeur
bytes
sur le memoryview.>>> m = memoryview(b"abc") >>> m.tobytes() b'abc' >>> bytes(m) b'abc'
Pour les arrays non contigus le résultat est égal à la représentation en liste aplatie dont tous les éléments sont convertis en octets.
tobytes()
supporte toutes les chaînes de format, y compris celles qui ne sont pas connues du modulestruct
.
-
tolist
()¶ Renvoie les données du buffer suus la forme d’une liste d’éléments. :::
>>> memoryview(b'abc').tolist() [97, 98, 99] >>> import array >>> a = array.array('d', [1.1, 2.2, 3.3]) >>> m = memoryview(a) >>> m.tolist() [1.1, 2.2, 3.3]
-
release
()¶ Libère le tampon sous-jacent exposé par l’objet memoryview. Beaucoup d’objets prennent des initiatives particulières lorsqu’ils sont liés à une vue (par exemple, un
bytearray
refusera temporairement de se faire redimensionner). Par conséquent, appeler release() peut être pratique pour lever ces restrictions (et en libérer les resources liées) aussi tôt que possible.Après le premier appel de cette méthode, toute nouvelle opération sur la view léve une
ValueError
(saufrelease()
elle-même qui peut être appelée plusieurs fois) :>>> m = memoryview(b'abc') >>> m.release() >>> m[0] Traceback (most recent call last): File "<stdin>", line 1, in <module> ValueError: operation forbidden on released memoryview object
Le protocole de gestion de contexte peut être utilisé pour obtenir un effet similaire, via l’instruction
with
:>>> with memoryview(b'abc') as m: ... m[0] ... 97 >>> m[0] Traceback (most recent call last): File "<stdin>", line 1, in <module> ValueError: operation forbidden on released memoryview object
Nouveau dans la version 3.2.
-
cast
(format[, shape])¶ Cast a memoryview to a new format or shape. shape defaults to
[byte_length//new_itemsize]
, which means that the result view will be one-dimensional. The return value is a new memoryview, but the buffer itself is not copied. Supported casts are 1D -> C-contiguous and C-contiguous -> 1D.Both formats are restricted to single element native formats in
struct
syntax. One of the formats must be a byte format (“B”, “b” or “c”). The byte length of the result must be the same as the original length.Transforme 1D/long en 1D/unsigned bytes :
>>> import array >>> a = array.array('l', [1,2,3]) >>> x = memoryview(a) >>> x.format 'l' >>> x.itemsize 8 >>> len(x) 3 >>> x.nbytes 24 >>> y = x.cast('B') >>> y.format 'B' >>> y.itemsize 1 >>> len(y) 24 >>> y.nbytes 24
Transforme 1D/unsigned bytes en 1D/char :
>>> b = bytearray(b'zyz') >>> x = memoryview(b) >>> x[0] = b'a' Traceback (most recent call last): File "<stdin>", line 1, in <module> ValueError: memoryview: invalid value for format "B" >>> y = x.cast('c') >>> y[0] = b'a' >>> b bytearray(b'ayz')
Transforme 1D/bytes en 3D/ints en 1D/signed char :
>>> import struct >>> buf = struct.pack("i"*12, *list(range(12))) >>> x = memoryview(buf) >>> y = x.cast('i', shape=[2,2,3]) >>> y.tolist() [[[0, 1, 2], [3, 4, 5]], [[6, 7, 8], [9, 10, 11]]] >>> y.format 'i' >>> y.itemsize 4 >>> len(y) 2 >>> y.nbytes 48 >>> z = y.cast('b') >>> z.format 'b' >>> z.itemsize 1 >>> len(z) 48 >>> z.nbytes 48
Transforme 1D/unsigned char en 2D/unsigned long :
>>> buf = struct.pack("L"*6, *list(range(6))) >>> x = memoryview(buf) >>> y = x.cast('L', shape=[2,3]) >>> len(y) 2 >>> y.nbytes 48 >>> y.tolist() [[0, 1, 2], [3, 4, 5]]
Nouveau dans la version 3.3.
Plusieurs attributs en lecture seule sont également disponibles :
-
obj
¶ L’objet sous-jacent de la memoryview :
>>> b = bytearray(b'xyz') >>> m = memoryview(b) >>> m.obj is b True
Nouveau dans la version 3.3.
-
nbytes
¶ nbytes == product(shape) * itemsize == len(m.tobytes())
. Ceci est l’espace que l’array utiliserait en octets, dans unereprésentation contiguë. Ce n’est pas nécessairement égale àlen(m)
:>>> import array >>> a = array.array('i', [1,2,3,4,5]) >>> m = memoryview(a) >>> len(m) 5 >>> m.nbytes 20 >>> y = m[::2] >>> len(y) 3 >>> y.nbytes 12 >>> len(y.tobytes()) 12
Tableaux multidimensionnels :
>>> import struct >>> buf = struct.pack("d"*12, *[1.5*x for x in range(12)]) >>> x = memoryview(buf) >>> y = x.cast('d', shape=[3,4]) >>> y.tolist() [[0.0, 1.5, 3.0, 4.5], [6.0, 7.5, 9.0, 10.5], [12.0, 13.5, 15.0, 16.5]] >>> len(y) 3 >>> y.nbytes 96
Nouveau dans la version 3.3.
-
readonly
¶ Un booléen indiquant si la mémoire est en lecture seule.
-
format
¶ Une chaîne contenant le format (dans le style de
struct
) pour chaque élément de la vue. Une memoryview peut être crée depuis des exportateurs de formats arbitraires, mais certaines méthodes (commetolist()
) sont limitées aux formats natifs à un seul élément.Modifié dans la version 3.3: Le format
'B'
est maintenant traité selon la syntaxe du module struct. Cela signifie quememoryview(b'abc')[0] == b'abc'[0] == 97
.
-
itemsize
¶ La taille en octets de chaque élément d’une memoryview:
>>> import array, struct >>> m = memoryview(array.array('H', [32000, 32001, 32002])) >>> m.itemsize 2 >>> m[0] 32000 >>> struct.calcsize('H') == m.itemsize True
-
ndim
¶ Un nombre entier indiquant le nombre de dimensions d’un tableau multi-dimensionnel représenté par la memoryview.
-
shape
¶ Un tuple d’entiers de longueur
ndim
donnant la forme de la memoryview sous forme d’un tableau à N dimensions.Modifié dans la version 3.3: An empty tuple instead of None when ndim = 0.
-
strides
¶ Un tuple d’entiers de longueur
ndim
donnant la taille en octets permettant d’accéder à chaque dimensions du tableau.Modifié dans la version 3.3: An empty tuple instead of None when ndim = 0.
-
suboffsets
¶ Détail de l’implémentation des PIL-style arrays. La valeur n’est donné qu’a titre d’information.
-
c_contiguous
¶ A bool indicating whether the memory is C-contiguous.
Nouveau dans la version 3.3.
-
f_contiguous
¶ A bool indicating whether the memory is Fortran contiguous.
Nouveau dans la version 3.3.
-
contiguous
¶ A bool indicating whether the memory is contiguous.
Nouveau dans la version 3.3.
-
4.9. Types d’ensembles — set
, frozenset
¶
Un objet set est une collection non-triée d’objets hashable distincts. Les utilisations classiques sont le test d’appartenance, la déduplication d’une séquence, ou le calcul d’opérations mathématiques telles que l’intersection, l’union, la différence, ou la différence symétrique. (Pour les autres conteneurs, voir les classes natives dict
, list
, et tuple
, ainsi que le module collections
.)
Comme pour les autres collections, les ensembles supportent x in set
, len(set)
, et for x in set
. En temps que collection non-triée, les ensembles n’enregistrent pas la position des éléments ou leur ordre d’insertion. En conséquence, les sets n’autorisent ni l’indexation, ni le découpage, ou tout autre comportement de séquence.
Il existe actuellement deux types natifs pour les ensembles, set
et fronzenset
. Le type set
est mutable — son contenu peut changer en utilisant des méthodes comme add()
et remove()
. Puisqu’il est mutable, il n’a pas de valeur de hachage et ne peut donc pas être utilisé ni comme clef de dictionnaire ni comme élément d’un autre ensemble. Le type frozenset
est immuable et hashable — son contenu ne peut être modifié après sa création, il peut ainsi être utilisé comme clef de dictionnaire ou élément d’un autre set.
Des sets (mais pas des frozensets) peuvent être crées par une liste d’éléments séparés par des virgules et entre accolades, par exemple : {'jack', 'sjoerd'}
, en plus du constructeur de la classe set
.
Les constructeurs des deux classes fonctionnent pareil :
-
class
set
([iterable])¶ -
class
frozenset
([iterable])¶ Renvoie un nouveau set ou frozenset dont les éléments viennent d”iterable. Les éléments d’un set doivent être hashable. Pour représenter des sets de sets les sets intérieurs doivent être des
frozenset
. Si iterable n’est pas spécifié, un nouveau set vide est renvoyé.Les instances de
set
etfrozenset
fournissent les opérations suivantes :-
len(s)
Return the cardinality of set s.
-
x in s
Test d’appartenance de x dans s.
-
x not in s
Test de non-appartenance de x dans s.
-
isdisjoint
(other)¶ Renvoie
True
si l’ensemble n’a aucun élément en commun avec other. Les ensembles sont disjoints si et seulement si leurs intersection est un ensemble vide.
-
issubset
(other)¶ -
set <= other
Teste si tous les éléments du set sont dans other.
-
set < other
Teste si l’ensemble est un sous-ensemble de other, c’est-à-dire,
set <= other and set != other
.
-
issuperset
(other)¶ -
set >= other
Teste si tous les éléments de other sont dans l’ensemble.
-
set > other
Teste si l’ensemble est un sur-ensemble de other, c’est-à-dire,
set >= other and set != other
.
-
union
(other, …)¶ -
set | other | …
Renvoie un nouvel ensemble dont les éléments viennent de l’ensemble et de tous les autres.
-
intersection
(other, …)¶ -
set & other & …
Renvoie un nouvel ensemble dont les éléments sont commun à l’ensemble et à tous les autres.
-
difference
(other, …)¶ -
set - other - …
Renvoie un nouvel ensemble dont les éléments sont dans l’ensemble mais ne sont dans aucun des autres.
-
symmetric_difference
(other)¶ -
set ^ other
Renvoie un nouvel ensemble dont les éléments sont soit dans l’ensemble, soit dans les autres, mais pas dans les deux.
-
copy
()¶ Renvoie un nouvel ensemble, copie de surface de s.
Note, the non-operator versions of
union()
,intersection()
,difference()
, andsymmetric_difference()
,issubset()
, andissuperset()
methods will accept any iterable as an argument. In contrast, their operator based counterparts require their arguments to be sets. This precludes error-prone constructions likeset('abc') & 'cbs'
in favor of the more readableset('abc').intersection('cbs')
.Both
set
andfrozenset
support set to set comparisons. Two sets are equal if and only if every element of each set is contained in the other (each is a subset of the other). A set is less than another set if and only if the first set is a proper subset of the second set (is a subset, but is not equal). A set is greater than another set if and only if the first set is a proper superset of the second set (is a superset, but is not equal).Instances of
set
are compared to instances offrozenset
based on their members. For example,set('abc') == frozenset('abc')
returnsTrue
and so doesset('abc') in set([frozenset('abc')])
.The subset and equality comparisons do not generalize to a total ordering function. For example, any two nonempty disjoint sets are not equal and are not subsets of each other, so all of the following return
False
:a<b
,a==b
, ora>b
.Since sets only define partial ordering (subset relationships), the output of the
list.sort()
method is undefined for lists of sets.Set elements, like dictionary keys, must be hashable.
Binary operations that mix
set
instances withfrozenset
return the type of the first operand. For example:frozenset('ab') | set('bc')
returns an instance offrozenset
.The following table lists operations available for
set
that do not apply to immutable instances offrozenset
:-
update
(other, …)¶ -
set |= other | …
Update the set, adding elements from all others.
-
intersection_update
(other, …)¶ -
set &= other & …
Update the set, keeping only elements found in it and all others.
-
difference_update
(other, …)¶ -
set -= other | …
Update the set, removing elements found in others.
-
symmetric_difference_update
(other)¶ -
set ^= other
Update the set, keeping only elements found in either set, but not in both.
-
add
(elem)¶ Add element elem to the set.
-
remove
(elem)¶ Remove element elem from the set. Raises
KeyError
if elem is not contained in the set.
-
discard
(elem)¶ Remove element elem from the set if it is present.
-
clear
()¶ Remove all elements from the set.
Note, the non-operator versions of the
update()
,intersection_update()
,difference_update()
, andsymmetric_difference_update()
methods will accept any iterable as an argument.Note, the elem argument to the
__contains__()
,remove()
, anddiscard()
methods may be a set. To support searching for an equivalent frozenset, the elem set is temporarily mutated during the search and then restored. During the search, the elem set should not be read or mutated since it does not have a meaningful value.-
4.10. Mapping Types — dict
¶
A mapping object maps hashable values to arbitrary objects.
Mappings are mutable objects. There is currently only one standard mapping
type, the dictionary. (For other containers see the built-in
list
, set
, and tuple
classes, and the
collections
module.)
A dictionary’s keys are almost arbitrary values. Values that are not
hashable, that is, values containing lists, dictionaries or other
mutable types (that are compared by value rather than by object identity) may
not be used as keys. Numeric types used for keys obey the normal rules for
numeric comparison: if two numbers compare equal (such as 1
and 1.0
)
then they can be used interchangeably to index the same dictionary entry. (Note
however, that since computers store floating-point numbers as approximations it
is usually unwise to use them as dictionary keys.)
Dictionaries can be created by placing a comma-separated list of key: value
pairs within braces, for example: {'jack': 4098, 'sjoerd': 4127}
or {4098:
'jack', 4127: 'sjoerd'}
, or by the dict
constructor.
-
class
dict
(**kwarg)¶ -
class
dict
(mapping, **kwarg) -
class
dict
(iterable, **kwarg) Return a new dictionary initialized from an optional positional argument and a possibly empty set of keyword arguments.
If no positional argument is given, an empty dictionary is created. If a positional argument is given and it is a mapping object, a dictionary is created with the same key-value pairs as the mapping object. Otherwise, the positional argument must be an iterable object. Each item in the iterable must itself be an iterable with exactly two objects. The first object of each item becomes a key in the new dictionary, and the second object the corresponding value. If a key occurs more than once, the last value for that key becomes the corresponding value in the new dictionary.
If keyword arguments are given, the keyword arguments and their values are added to the dictionary created from the positional argument. If a key being added is already present, the value from the keyword argument replaces the value from the positional argument.
To illustrate, the following examples all return a dictionary equal to
{"one": 1, "two": 2, "three": 3}
:>>> a = dict(one=1, two=2, three=3) >>> b = {'one': 1, 'two': 2, 'three': 3} >>> c = dict(zip(['one', 'two', 'three'], [1, 2, 3])) >>> d = dict([('two', 2), ('one', 1), ('three', 3)]) >>> e = dict({'three': 3, 'one': 1, 'two': 2}) >>> a == b == c == d == e True
Providing keyword arguments as in the first example only works for keys that are valid Python identifiers. Otherwise, any valid keys can be used.
These are the operations that dictionaries support (and therefore, custom mapping types should support too):
-
len(d)
Return the number of items in the dictionary d.
-
d[key]
Return the item of d with key key. Raises a
KeyError
if key is not in the map.If a subclass of dict defines a method
__missing__()
and key is not present, thed[key]
operation calls that method with the key key as argument. Thed[key]
operation then returns or raises whatever is returned or raised by the__missing__(key)
call. No other operations or methods invoke__missing__()
. If__missing__()
is not defined,KeyError
is raised.__missing__()
must be a method; it cannot be an instance variable:>>> class Counter(dict): ... def __missing__(self, key): ... return 0 >>> c = Counter() >>> c['red'] 0 >>> c['red'] += 1 >>> c['red'] 1
The example above shows part of the implementation of
collections.Counter
. A different__missing__
method is used bycollections.defaultdict
.
-
d[key] = value
Set
d[key]
to value.
-
del d[key]
Remove
d[key]
from d. Raises aKeyError
if key is not in the map.
-
key in d
Return
True
if d has a key key, elseFalse
.
-
key not in d
Equivalent to
not key in d
.
-
iter(d)
Return an iterator over the keys of the dictionary. This is a shortcut for
iter(d.keys())
.
-
clear
()¶ Remove all items from the dictionary.
-
copy
()¶ Return a shallow copy of the dictionary.
-
classmethod
fromkeys
(seq[, value])¶ Create a new dictionary with keys from seq and values set to value.
fromkeys()
is a class method that returns a new dictionary. value defaults toNone
.
-
get
(key[, default])¶ Return the value for key if key is in the dictionary, else default. If default is not given, it defaults to
None
, so that this method never raises aKeyError
.
-
items
()¶ Return a new view of the dictionary’s items (
(key, value)
pairs). See the documentation of view objects.
-
keys
()¶ Return a new view of the dictionary’s keys. See the documentation of view objects.
-
pop
(key[, default])¶ If key is in the dictionary, remove it and return its value, else return default. If default is not given and key is not in the dictionary, a
KeyError
is raised.
-
popitem
()¶ Remove and return an arbitrary
(key, value)
pair from the dictionary.popitem()
is useful to destructively iterate over a dictionary, as often used in set algorithms. If the dictionary is empty, callingpopitem()
raises aKeyError
.
-
setdefault
(key[, default])¶ If key is in the dictionary, return its value. If not, insert key with a value of default and return default. default defaults to
None
.
-
update
([other])¶ Update the dictionary with the key/value pairs from other, overwriting existing keys. Return
None
.update()
accepts either another dictionary object or an iterable of key/value pairs (as tuples or other iterables of length two). If keyword arguments are specified, the dictionary is then updated with those key/value pairs:d.update(red=1, blue=2)
.
-
values
()¶ Return a new view of the dictionary’s values. See the documentation of view objects.
-
Voir aussi
types.MappingProxyType
can be used to create a read-only view
of a dict
.
4.10.1. Dictionary view objects¶
The objects returned by dict.keys()
, dict.values()
and
dict.items()
are view objects. They provide a dynamic view on the
dictionary’s entries, which means that when the dictionary changes, the view
reflects these changes.
Dictionary views can be iterated over to yield their respective data, and support membership tests:
-
len(dictview)
Return the number of entries in the dictionary.
-
iter(dictview)
Return an iterator over the keys, values or items (represented as tuples of
(key, value)
) in the dictionary.Keys and values are iterated over in an arbitrary order which is non-random, varies across Python implementations, and depends on the dictionary’s history of insertions and deletions. If keys, values and items views are iterated over with no intervening modifications to the dictionary, the order of items will directly correspond. This allows the creation of
(value, key)
pairs usingzip()
:pairs = zip(d.values(), d.keys())
. Another way to create the same list ispairs = [(v, k) for (k, v) in d.items()]
.Iterating views while adding or deleting entries in the dictionary may raise a
RuntimeError
or fail to iterate over all entries.
-
x in dictview
Return
True
if x is in the underlying dictionary’s keys, values or items (in the latter case, x should be a(key, value)
tuple).
Keys views are set-like since their entries are unique and hashable. If all
values are hashable, so that (key, value)
pairs are unique and hashable,
then the items view is also set-like. (Values views are not treated as set-like
since the entries are generally not unique.) For set-like views, all of the
operations defined for the abstract base class collections.abc.Set
are
available (for example, ==
, <
, or ^
).
An example of dictionary view usage:
>>> dishes = {'eggs': 2, 'sausage': 1, 'bacon': 1, 'spam': 500}
>>> keys = dishes.keys()
>>> values = dishes.values()
>>> # iteration
>>> n = 0
>>> for val in values:
... n += val
>>> print(n)
504
>>> # keys and values are iterated over in the same order
>>> list(keys)
['eggs', 'bacon', 'sausage', 'spam']
>>> list(values)
[2, 1, 1, 500]
>>> # view objects are dynamic and reflect dict changes
>>> del dishes['eggs']
>>> del dishes['sausage']
>>> list(keys)
['spam', 'bacon']
>>> # set operations
>>> keys & {'eggs', 'bacon', 'salad'}
{'bacon'}
>>> keys ^ {'sausage', 'juice'}
{'juice', 'sausage', 'bacon', 'spam'}
4.11. Context Manager Types¶
Python’s with
statement supports the concept of a runtime context
defined by a context manager. This is implemented using a pair of methods
that allow user-defined classes to define a runtime context that is entered
before the statement body is executed and exited when the statement ends:
-
contextmanager.
__enter__
()¶ Enter the runtime context and return either this object or another object related to the runtime context. The value returned by this method is bound to the identifier in the
as
clause ofwith
statements using this context manager.An example of a context manager that returns itself is a file object. File objects return themselves from __enter__() to allow
open()
to be used as the context expression in awith
statement.An example of a context manager that returns a related object is the one returned by
decimal.localcontext()
. These managers set the active decimal context to a copy of the original decimal context and then return the copy. This allows changes to be made to the current decimal context in the body of thewith
statement without affecting code outside thewith
statement.
-
contextmanager.
__exit__
(exc_type, exc_val, exc_tb)¶ Exit the runtime context and return a Boolean flag indicating if any exception that occurred should be suppressed. If an exception occurred while executing the body of the
with
statement, the arguments contain the exception type, value and traceback information. Otherwise, all three arguments areNone
.Returning a true value from this method will cause the
with
statement to suppress the exception and continue execution with the statement immediately following thewith
statement. Otherwise the exception continues propagating after this method has finished executing. Exceptions that occur during execution of this method will replace any exception that occurred in the body of thewith
statement.The exception passed in should never be reraised explicitly - instead, this method should return a false value to indicate that the method completed successfully and does not want to suppress the raised exception. This allows context management code to easily detect whether or not an
__exit__()
method has actually failed.
Python defines several context managers to support easy thread synchronisation,
prompt closure of files or other objects, and simpler manipulation of the active
decimal arithmetic context. The specific types are not treated specially beyond
their implementation of the context management protocol. See the
contextlib
module for some examples.
Python’s generators and the contextlib.contextmanager
decorator
provide a convenient way to implement these protocols. If a generator function is
decorated with the contextlib.contextmanager
decorator, it will return a
context manager implementing the necessary __enter__()
and
__exit__()
methods, rather than the iterator produced by an undecorated
generator function.
Note that there is no specific slot for any of these methods in the type structure for Python objects in the Python/C API. Extension types wanting to define these methods must provide them as a normal Python accessible method. Compared to the overhead of setting up the runtime context, the overhead of a single class dictionary lookup is negligible.
4.12. Other Built-in Types¶
The interpreter supports several other kinds of objects. Most of these support only one or two operations.
4.12.1. Modules¶
The only special operation on a module is attribute access: m.name
, where
m is a module and name accesses a name defined in m’s symbol table.
Module attributes can be assigned to. (Note that the import
statement is not, strictly speaking, an operation on a module object; import
foo
does not require a module object named foo to exist, rather it requires
an (external) definition for a module named foo somewhere.)
A special attribute of every module is __dict__
. This is the
dictionary containing the module’s symbol table. Modifying this dictionary will
actually change the module’s symbol table, but direct assignment to the
__dict__
attribute is not possible (you can write
m.__dict__['a'] = 1
, which defines m.a
to be 1
, but you can’t write
m.__dict__ = {}
). Modifying __dict__
directly is not recommended.
Modules built into the interpreter are written like this: <module 'sys'
(built-in)>
. If loaded from a file, they are written as <module 'os' from
'/usr/local/lib/pythonX.Y/os.pyc'>
.
4.12.2. Classes and Class Instances¶
4.12.3. Fonctions¶
Function objects are created by function definitions. The only operation on a
function object is to call it: func(argument-list)
.
There are really two flavors of function objects: built-in functions and user-defined functions. Both support the same operation (to call the function), but the implementation is different, hence the different object types.
See Function definitions for more information.
4.12.4. Méthodes¶
Methods are functions that are called using the attribute notation. There are
two flavors: built-in methods (such as append()
on lists) and class
instance methods. Built-in methods are described with the types that support
them.
If you access a method (a function defined in a class namespace) through an
instance, you get a special object: a bound method (also called
instance method) object. When called, it will add the self
argument
to the argument list. Bound methods have two special read-only attributes:
m.__self__
is the object on which the method operates, and m.__func__
is
the function implementing the method. Calling m(arg-1, arg-2, ..., arg-n)
is completely equivalent to calling m.__func__(m.__self__, arg-1, arg-2, ...,
arg-n)
.
Like function objects, bound method objects support getting arbitrary
attributes. However, since method attributes are actually stored on the
underlying function object (meth.__func__
), setting method attributes on
bound methods is disallowed. Attempting to set an attribute on a method
results in an AttributeError
being raised. In order to set a method
attribute, you need to explicitly set it on the underlying function object:
>>> class C:
... def method(self):
... pass
...
>>> c = C()
>>> c.method.whoami = 'my name is method' # can't set on the method
Traceback (most recent call last):
File "<stdin>", line 1, in <module>
AttributeError: 'method' object has no attribute 'whoami'
>>> c.method.__func__.whoami = 'my name is method'
>>> c.method.whoami
'my name is method'
See The standard type hierarchy for more information.
4.12.5. Objets Code¶
Code objects are used by the implementation to represent « pseudo-compiled »
executable Python code such as a function body. They differ from function
objects because they don’t contain a reference to their global execution
environment. Code objects are returned by the built-in compile()
function
and can be extracted from function objects through their __code__
attribute. See also the code
module.
A code object can be executed or evaluated by passing it (instead of a source
string) to the exec()
or eval()
built-in functions.
See The standard type hierarchy for more information.
4.12.6. Type Objects¶
Type objects represent the various object types. An object’s type is accessed
by the built-in function type()
. There are no special operations on
types. The standard module types
defines names for all standard built-in
types.
Types are written like this: <class 'int'>
.
4.12.7. The Null Object¶
This object is returned by functions that don’t explicitly return a value. It
supports no special operations. There is exactly one null object, named
None
(a built-in name). type(None)()
produces the same singleton.
It is written as None
.
4.12.8. The Ellipsis Object¶
This object is commonly used by slicing (see Slicings). It supports no
special operations. There is exactly one ellipsis object, named
Ellipsis
(a built-in name). type(Ellipsis)()
produces the
Ellipsis
singleton.
It is written as Ellipsis
or ...
.
4.12.9. The NotImplemented Object¶
This object is returned from comparisons and binary operations when they are
asked to operate on types they don’t support. See Comparaisons for more
information. There is exactly one NotImplemented
object.
type(NotImplemented)()
produces the singleton instance.
It is written as NotImplemented
.
4.12.10. Boolean Values¶
Boolean values are the two constant objects False
and True
. They are
used to represent truth values (although other values can also be considered
false or true). In numeric contexts (for example when used as the argument to
an arithmetic operator), they behave like the integers 0 and 1, respectively.
The built-in function bool()
can be used to convert any value to a
Boolean, if the value can be interpreted as a truth value (see section
Valeurs booléennes above).
They are written as False
and True
, respectively.
4.12.11. Internal Objects¶
See The standard type hierarchy for this information. It describes stack frame objects, traceback objects, and slice objects.
4.13. Special Attributes¶
The implementation adds a few special read-only attributes to several object
types, where they are relevant. Some of these are not reported by the
dir()
built-in function.
-
object.
__dict__
¶ A dictionary or other mapping object used to store an object’s (writable) attributes.
-
instance.
__class__
¶ The class to which a class instance belongs.
-
class.
__bases__
¶ The tuple of base classes of a class object.
-
class.
__name__
¶ The name of the class or type.
-
class.
__qualname__
¶ The qualified name of the class or type.
Nouveau dans la version 3.3.
-
class.
__mro__
¶ This attribute is a tuple of classes that are considered when looking for base classes during method resolution.
-
class.
mro
()¶ This method can be overridden by a metaclass to customize the method resolution order for its instances. It is called at class instantiation, and its result is stored in
__mro__
.
-
class.
__subclasses__
()¶ Each class keeps a list of weak references to its immediate subclasses. This method returns a list of all those references still alive. Example:
>>> int.__subclasses__() [<class 'bool'>]
Notes
[1] | Additional information on these special methods may be found in the Python Reference Manual (Basic customization). |
[2] | As a consequence, the list [1, 2] is considered equal to [1.0, 2.0] , and
similarly for tuples. |
[3] | They must have since the parser can’t tell the type of the operands. |
[4] | (1, 2, 3, 4) Cased characters are those with general category property being one of « Lu » (Letter, uppercase), « Ll » (Letter, lowercase), or « Lt » (Letter, titlecase). |
[5] | (1, 2) To format only a tuple you should therefore provide a singleton tuple whose only element is the tuple to be formatted. |