Tipi incorporati

Le sezioni seguenti descrivono i tipi standard incorporati nell’interprete.

I principali tipi incorporati sono numerici, sequenze, mappature, classi, istanze ed eccezioni.

Alcune classi di collezioni sono mutabili. I metodi che aggiungono, sottraggono o riorganizzano i loro membri in loco, e non restituiscono un elemento specifico, non restituiscono mai l’istanza della collezione stessa ma None.

Alcune operazioni sono supportate da diversi tipi di oggetti; in particolare, praticamente tutti gli oggetti possono essere confrontati per uguaglianza, testati per valore di verità e convertiti in una stringa (con la funzione repr() o la funzione leggermente diversa str()). Quest’ultima funzione viene utilizzata implicitamente quando un oggetto è scritto dalla funzione print().

Test del Valore di Verità

Qualsiasi oggetto può essere testato per valore di verità, per essere usato in una condizione if o while o come operando delle operazioni booleane sotto.

Per impostazione predefinita, un oggetto è considerato vero a meno che la sua classe non definisca un metodo __bool__() che restituisce False o un metodo __len__() che restituisce zero, quando chiamato con l’oggetto. [1] Ecco la maggior parte degli oggetti incorporati considerati falsi:

• costanti definite come false: None e False

• zero di qualsiasi tipo numerico: 0, 0.0, 0j, Decimal(0), Fraction(0, 1)

• sequenze e collezioni vuote: '', (), [], {}, set(), range(0)

Le operazioni e le funzioni incorporate che hanno un risultato booleano restituiscono sempre 0 o False per false e 1 o True per true, salvo diversa indicazione. (Eccezione importante: le operazioni booleane or e and restituiscono sempre uno dei loro operandi.)

Operazioni Booleane — and, or, not

Queste sono le operazioni booleane, ordinate per priorità crescente:

Operazione	Risultato	Note
x or y	se x è vero, allora x, altrimenti y	(1)
x and y	se x è falso, allora x, altrimenti y	(2)
not x	se x è falso, allora True, altrimenti False	(3)

Note:

1. Questo è un operatore a cortocircuito, quindi valuta il secondo argomento solo se il primo è falso.

2. Questo è un operatore a cortocircuito, quindi valuta il secondo argomento solo se il primo è vero.

3. not ha una priorità inferiore rispetto agli operatori non booleani, quindi not a == b è interpretato come not (a == b), e a == not b è un errore di sintassi.

Confronti

Ci sono otto operazioni di confronto in Python. Hanno tutte la stessa priorità (che è superiore a quella delle operazioni booleane). I confronti possono essere concatenati arbitrariamente; per esempio, x < y <= z è equivalente a x < y and y <= z, tranne che y è valutato solo una volta (ma in entrambi i casi z non è valutato affatto quando x < y risulta falso).

Questa tabella riassume le operazioni di confronto:

Operazione	Significato
<	strettamente minore di
<=	minore o uguale
>	strettamente maggiore di
>=	maggiore o uguale
==	uguale
!=	diverso
is	identità dell’oggetto
is not	identità dell’oggetto negata

Oggetti di tipi diversi, eccetto diversi tipi numerici, non vengono mai considerati uguali. L’operatore == è sempre definito ma per alcuni tipi di oggetti (ad esempio, oggetti di classe) è equivalente a is. Gli operatori <, <=, > e >= sono definiti solo dove hanno senso; ad esempio, essi sollevano un’eccezione TypeError quando uno degli argomenti è un numero complesso.

Le istanze non identiche di una classe normalmente vengono considerate come non uguali a meno che la classe definisca il metodo __eq__().

Le istanze di una classe non possono essere ordinate rispetto ad altre istanze della stessa classe, o di altri tipi di oggetti, a meno che la classe non definisca abbastanza metodi __lt__(), __le__(), __gt__(), e __ge__() (in generale, __lt__() e __eq__() sono sufficienti, se si vogliono i significati convenzionali degli operatori di confronto).

Il comportamento degli operatori is e is not non può essere personalizzato; inoltre possono essere applicati a qualsiasi due oggetti e non sollevano mai un’eccezione.

Due operazioni con la stessa priorità sintattica, in e not in, sono supportate da tipi che sono iterable o implementano il metodo __contains__().

Tipi Numerici — int, float, complex

There are three distinct numeric types: integers, floating-point numbers, and complex numbers. In addition, Booleans are a subtype of integers. Integers have unlimited precision. Floating-point numbers are usually implemented using double in C; information about the precision and internal representation of floating-point numbers for the machine on which your program is running is available in sys.float_info. Complex numbers have a real and imaginary part, which are each a floating-point number. To extract these parts from a complex number z, use z.real and z.imag. (The standard library includes the additional numeric types fractions.Fraction, for rationals, and decimal.Decimal, for floating-point numbers with user-definable precision.)

Numbers are created by numeric literals or as the result of built-in functions and operators. Unadorned integer literals (including hex, octal and binary numbers) yield integers. Numeric literals containing a decimal point or an exponent sign yield floating-point numbers. Appending 'j' or 'J' to a numeric literal yields an imaginary number (a complex number with a zero real part) which you can add to an integer or float to get a complex number with real and imaginary parts.

Python supporta completamente l’aritmetica mista: quando un operatore aritmetico binario ha operandi di diversi tipi numerici, l’operando con il tipo «più ristretto» viene ampliato a quello dell’altro, dove intero è più ristretto di virgola mobile, che è più ristretto di complesso. Un confronto tra numeri di tipi diversi si comporta come se fossero confrontati i valori esatti di quei numeri. [2]

I costruttori int(), float() e complex() possono essere usati per produrre numeri di un tipo specifico.

Tutti i tipi numerici (eccetto i complessi) supportano le seguenti operazioni (per le priorità delle operazioni, vedi Operator precedence):

Operazione	Risultato	Note	Documentazione completa
x + y	somma di x e y
x - y	differenza tra x e y
x * y	prodotto di x e y
x / y	quoziente di x e y
x // y	quoziente di x e y arrotondato per difetto	(1)(2)
x % y	resto della divisione x / y	(2)
-x	x negato
+x	x invariato
abs(x)	valore assoluto o magnitudine di x		abs()
int(x)	x convertito in intero	(3)(6)	int()
float(x)	x convertito in numero in virgola mobile	(4)(6)	float()
complex(re, im)	un numero complesso con parte reale re e parte immaginaria im. im predefinito a zero.	(6)	complex()
c.conjugate()	coniugato del numero complesso c
divmod(x, y)	la coppia (x // y, x % y)	(2)	divmod()
pow(x, y)	x elevato alla potenza y	(5)	pow()
x ** y	x elevato alla potenza y	(5)

Note:

1. Anche chiamato divisione intera. Per operandi di tipo int, il risultato ha tipo int. Per operandi di tipo float, il risultato ha tipo float. In generale, il risultato è un numero intero, anche se il tipo del risultato non è necessariamente int. Il risultato è sempre arrotondato verso meno infinito: 1//2 è 0, (-1)//2 è -1, 1//(-2) è -1, e (-1)//(-2) è 0.

2. Non per numeri complessi. Convertire invece a float usando abs() se appropriato.

3. La conversione da float a int tronca, scartando la parte frazionaria. Vedere le funzioni math.floor() e math.ceil() per conversioni alternative.

4. float accetta anche le stringhe «nan» e «inf» con un prefisso opzionale «+» o «-» per Not a Number (NaN) e infinito positivo o negativo.

5. Python definisce pow(0, 0) e 0 ** 0 come 1, come è comune nei linguaggi di programmazione.

6. I letterali numerici accettati includono le cifre 0 a 9 o qualsiasi equivalente Unicode (punti di codice con la proprietà Nd).

   Vedere the Unicode Standard per un elenco completo dei punti di codice con la proprietà Nd.

Tutti i tipi numbers.Real (int e float) includono anche le seguenti operazioni:

Operazione	Risultato
math.trunc(x)	x troncato a Integral
round(x[, n])	x arrotondato a n cifre, arrotondando per eccesso in caso di mezza unità. Se n è omesso, il valore predefinito è 0.
math.floor(x)	il più grande Integral <= x
math.ceil(x)	il più piccolo Integral >= x

Per ulteriori operazioni numeriche vedere i moduli math e cmath.

Operazioni Bitwise sui Tipi Integer

Le operazioni bitwise hanno senso solo per gli interi. Il risultato delle operazioni bitwise è calcolato come se eseguito in complemento a due con un numero infinito di bit di segno.

Le priorità delle operazioni binarie bitwise sono tutte inferiori alle operazioni numeriche e superiori alle comparazioni; l’operazione unaria ~ ha la stessa priorità delle altre operazioni numeriche unarie (+ e -).

Questa tabella elenca le operazioni bitwise ordinate per priorità crescente:

Operazione	Risultato	Note
x | y	bitwise or di x e y	(4)
x ^ y	bitwise or esclusivo di x e y	(4)
x & y	bitwise and di x e y	(4)
x << n	x spostato a sinistra di n bit	(1)(2)
x >> n	x spostato a destra di n bit	(1)(3)
~x	i bit di x invertiti

Note:

1. I conteggi di shift negativi sono illegali e causano un’eccezione ValueError.

2. Uno shift a sinistra di n bit è equivalente alla moltiplicazione per pow(2, n).

3. Uno shift a destra di n bit è equivalente alla divisione intera per pow(2, n).

4. Eseguire questi calcoli con almeno un bit di estensione del segno in più in una rappresentazione a complemento a due finita (una larghezza di bit lavorativa di 1 + max(x.bit_length(), y.bit_length()) o più) è sufficiente per ottenere lo stesso risultato come se ci fossero un numero infinito di bit di segno.

Metodi Aggiuntivi sui Tipi Integer

Il tipo int implementa la numbers.Integral abstract base class. Inoltre, fornisce qualche metodo in più:

int.bit_length()

Restituisce il numero di bit necessari a rappresentare un intero in binario, escludendo il segno e gli zeri iniziali:

>>> n = -37
>>> bin(n)
'-0b100101'
>>> n.bit_length()
6

Più precisamente, se x è diverso da zero, allora x.bit_length() è l’unico intero positivo k tale che 2**(k-1) <= abs(x) < 2**k. Equivalentemente, quando abs(x) è sufficientemente piccolo da avere un logaritmo correttamente arrotondato, allora k = 1 + int(log(abs(x), 2)). Se x è zero, allora x.bit_length() restituisce 0.

Equivalente a:

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

Added in version 3.1.

int.bit_count()

Restituisce il numero di uno nella rappresentazione binaria del valore assoluto dell’intero. Questo è anche conosciuto come il conteggio della popolazione. Esempio:

>>> n = 19
>>> bin(n)
'0b10011'
>>> n.bit_count()
3
>>> (-n).bit_count()
3

Equivalente a:

def bit_count(self):
    return bin(self).count("1")

Added in version 3.10.

int.to_bytes(length=1, byteorder='big', *, signed=False)

Restituisce un array di byte che rappresenta un intero.

>>> (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() + 7) // 8, byteorder='little')
b'\xe8\x03'

L’intero è rappresentato utilizzando length byte, e il valore predefinito è 1. Viene sollevata un’eccezione OverflowError se l’intero non è rappresentabile con il numero di byte fornito.

L’argomento byteorder determina l’ordine dei byte utilizzato per rappresentare l’intero, e il valore predefinito è "big". Se byteorder è "big", il byte più significativo è all’inizio dell’array di byte. Se byteorder è "little", il byte più significativo è alla fine dell’array di byte.

L’argomento signed determina se viene utilizzato il complemento a due per rappresentare l’intero. Se signed è False e viene fornito un intero negativo, viene sollevata un’eccezione OverflowError. Il valore predefinito di signed è False.

I valori predefiniti possono essere utilizzati per convertire comodamente un intero in un singolo oggetto byte:

>>> (65).to_bytes()
b'A'

Tuttavia, quando si utilizzano gli argomenti predefiniti, non tentare di convertire un valore maggiore di 255 o si otterrà un’eccezione OverflowError.

Equivalente a:

def to_bytes(n, length=1, byteorder='big', signed=False):
    if byteorder == 'little':
        order = range(length)
    elif byteorder == 'big':
        order = reversed(range(length))
    else:
        raise ValueError("byteorder must be either 'little' or 'big'")

    return bytes((n >> i*8) & 0xff for i in order)

Added in version 3.2.

Cambiato nella versione 3.11: Aggiunti i valori predefiniti degli argomenti per length e byteorder.

classmethod int.from_bytes(bytes, byteorder='big', *, signed=False)

Restituisce l’intero rappresentato dall’array di byte fornito.

>>> 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’argomento bytes deve essere un bytes-like object o un iterabile che produce byte.

L’argomento byteorder determina l’ordine dei byte utilizzato per rappresentare l’intero, e il valore predefinito è "big". Se byteorder è "big", il byte più significativo è all’inizio dell’array di byte. Se byteorder è "little", il byte più significativo è alla fine dell’array di byte. Per richiedere l’ordine dei byte nativo del sistema host, utilizzare sys.byteorder come valore dell’ordine dei byte.

L’argomento signed indica se viene utilizzato il complemento a due per rappresentare l’intero.

Equivalente a:

def from_bytes(bytes, byteorder='big', signed=False):
    if byteorder == 'little':
        little_ordered = list(bytes)
    elif byteorder == 'big':
        little_ordered = list(reversed(bytes))
    else:
        raise ValueError("byteorder must be either 'little' or 'big'")

    n = sum(b << i*8 for i, b in enumerate(little_ordered))
    if signed and little_ordered and (little_ordered[-1] & 0x80):
        n -= 1 << 8*len(little_ordered)

    return n

Added in version 3.2.

Cambiato nella versione 3.11: Aggiunto valore predefinito per l’argomento byteorder.

int.as_integer_ratio()

Restituisce una coppia di interi il cui rapporto è uguale all’intero originale e ha un denominatore positivo. Il rapporto di numeri interi (numeri interi) è sempre l’intero come numeratore e 1 come denominatore.

Added in version 3.8.

int.is_integer()

Restituisce True. Esiste per compatibilità con il tipo anatropomorfico con float.is_integer().

Added in version 3.12.

Metodi aggiuntivi su Float

Il tipo float implementa la classe numbers.Real abstract base class. float ha anche i seguenti metodi aggiuntivi.

float.as_integer_ratio()

Restituisce una coppia di interi il cui rapporto è esattamente uguale al float originale. Il rapporto è in termini minimi e ha un denominatore positivo. Solleva OverflowError su infiniti e una ValueError su NaN.

float.is_integer()

Restituisce True se l’istanza float è finita con valore intero, e False altrimenti:

>>> (-2.0).is_integer()
True
>>> (3.2).is_integer()
False

Due metodi supportano la conversione da e verso stringhe esadecimali. Poiché i float di Python sono memorizzati internamente come numeri binari, la conversione di un float da o verso una stringa decimale di solito comporta un piccolo errore di arrotondamento. Al contrario, le stringhe esadecimali consentono una rappresentazione e specifica esatta dei numeri in virgola mobile. Questo può essere utile durante il debugging e nel lavoro numerico.

float.hex()

Restituisce una rappresentazione di un numero in virgola mobile come una stringa esadecimale. Per i numeri in virgola mobile finiti, questa rappresentazione includerà sempre un 0x iniziale e un p finale con l’esponente.

classmethod float.fromhex(s)

Metodo di classe per restituire il float rappresentato da una stringa esadecimale s. La stringa s può avere spazi bianchi iniziali e finali.

Nota che float.hex() è un metodo di istanza, mentre float.fromhex() è un metodo di classe.

Una stringa esadecimale prende la forma:

[sign] ['0x'] integer ['.' fraction] ['p' exponent]

dove il segno opzionale può essere + o -, intero e frazione sono stringhe di cifre esadecimali, e l”esponente è un intero decimale con un segno iniziale opzionale. Il caso non è significativo, e ci deve essere almeno una cifra esadecimale nell’intero o nella frazione. Questa sintassi è simile a quella specificata nella sezione 6.4.4.2 dello standard C99, e anche a quella utilizzata in Java 1.5 in poi. In particolare, l’output di float.hex() può essere utilizzato come letterale a virgola mobile esadecimale nel codice C o Java, e le stringhe esadecimali prodotte dal carattere di formato %a di C o da Double.toHexString di Java sono accettate da float.fromhex().

Nota che l’esponente è scritto in decimale piuttosto che in esadecimale, e che fornisce la potenza di 2 con cui moltiplicare il coefficiente. Ad esempio, la stringa esadecimale 0x3.a7p10 rappresenta il numero in virgola mobile (3 + 10./16 + 7./16**2) * 2.0**10, o 3740.0:

>>> float.fromhex('0x3.a7p10')
3740.0

Applicando la conversione inversa a 3740.0 si ottiene una stringa esadecimale diversa che rappresenta lo stesso numero:

>>> float.hex(3740.0)
'0x1.d380000000000p+11'

Hashing dei tipi numerici

Per i numeri x e y, possibilmente di tipi diversi, è un requisito che hash(x) == hash(y) ogni volta che x == y (vedi la documentazione del metodo __hash__() per ulteriori dettagli). Per facilità di implementazione e efficienza in una varietà di tipi numerici (inclusi int, float, decimal.Decimal e fractions.Fraction) l’hash di Python per i tipi numerici si basa su una singola funzione matematica definita per qualsiasi numero razionale, e quindi si applica a tutte le istanze di int e fractions.Fraction, e tutte le istanze finite di float e decimal.Decimal. Essenzialmente, questa funzione è data dalla riduzione modulo P per un primo fisso P. Il valore di P è reso disponibile a Python come l’attributo modulus di sys.hash_info.

Dettaglio dell’implementazione di CPython: Attualmente, il primo utilizzato è P = 2**31 - 1 su macchine con long C a 32 bit e P = 2**61 - 1 su macchine con long C a 64 bit.

Ecco le regole in dettaglio:

• Se x = m / n è un numero razionale non negativo e n non è divisibile per P, definire hash(x) come m * invmod(n, P) % P, dove invmod(n, P) fornisce l’inverso di n modulo P.

• Se x = m / n è un numero razionale non negativo e n è divisibile per P (ma m non lo è), allora n non ha inverso modulo P e la regola sopra non si applica; in questo caso, definire hash(x) come il valore costante sys.hash_info.inf.

• Se x = m / n è un numero razionale negativo, definire hash(x) come -hash(-x). Se l’hash risultante è -1, sostituirlo con -2.

• I valori particolari sys.hash_info.inf e -sys.hash_info.inf sono utilizzati come valori hash per l’infinito positivo o negativo (rispettivamente).

• Per un numero complex z, i valori hash delle parti reale e immaginaria sono combinati calcolando hash(z.real) + sys.hash_info.imag * hash(z.imag), ridotto modulo 2**sys.hash_info.width in modo che rientri in range(-2**(sys.hash_info.width - 1), 2**(sys.hash_info.width - 1)). Ancora una volta, se il risultato è -1, viene sostituito con -2.

Per chiarire le regole sopra, ecco un esempio di codice Python, equivalente all’hash integrato, per calcolare l’hash di un numero razionale, float o 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_value = 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_value = (abs(m) % P) * pow(n, P - 2, P) % P
    if m < 0:
        hash_value = -hash_value
    if hash_value == -1:
        hash_value = -2
    return hash_value

def hash_float(x):
    """Compute the hash of a float x."""

    if math.isnan(x):
        return object.__hash__(x)
    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_value = 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_value = (hash_value & (M - 1)) - (hash_value & M)
    if hash_value == -1:
        hash_value = -2
    return hash_value

Tipo Booleano - bool

I booleani rappresentano valori di verità. Il tipo bool ha esattamente due istanze costanti: True e False.

La funzione integrata bool() converte qualsiasi valore in un booleano, se il valore può essere interpretato come un valore di verità (vedi la sezione Test del Valore di Verità sopra).

Per le operazioni logiche, utilizzare gli operatori booleani and, or e not. Quando si applicano gli operatori bitwise &, |, ^ a due booleani, restituiscono un booleano equivalente alle operazioni logiche «and», «or», «xor». Tuttavia, gli operatori logici and, or e != dovrebbero essere preferiti a &, | e ^.

Deprecato dalla versione 3.12: The use of the bitwise inversion operator ~ is deprecated and will raise an error in Python 3.16.

bool è una sottoclasse di int (vedi Tipi Numerici — int, float, complex). In molti contesti numerici, False e True si comportano come gli interi 0 e 1, rispettivamente. Tuttavia, affidarsi a ciò è sconsigliato; convertire esplicitamente utilizzando int().

Tipi di Iteratore

Python supporta un concetto di iterazione sui contenitori. Questo è implementato utilizzando due metodi distinti; questi sono utilizzati per consentire alle classi definite dall’utente di supportare l’iterazione. Le sequenze, descritte più dettagliatamente di seguito, supportano sempre i metodi di iterazione.

Un metodo deve essere definito per gli oggetti contenitore per fornire il supporto iterable:

container.__iter__()

Restituisce un oggetto iterator. È richiesto che l’oggetto supporti il protocollo dell’iteratore descritto di seguito. Se un contenitore supporta diversi tipi di iterazione, possono essere forniti ulteriori metodi per richiedere specificamente iteratori per quei tipi di iterazione. (Un esempio di oggetto che supporta più forme di iterazione potrebbe essere una struttura ad albero che supporta sia l’attraversamento in ampiezza sia quello in profondità.) Questo metodo corrisponde allo slot tp_iter della struttura dei tipi per oggetti Python nell’API Python/C.

Gli oggetti iteratore stessi devono supportare i seguenti due metodi, che insieme formano il protocollo dell’iteratore:

iterator.__iter__()

Restituisce l’oggetto iterator stesso. Questo è richiesto per consentire sia ai contenitori che agli iteratori di essere utilizzati con le dichiarazioni for e in. Questo metodo corrisponde allo slot tp_iter della struttura dei tipi per oggetti Python nell’API Python/C.

iterator.__next__()

Restituisce il prossimo elemento dall”iterator. Se non ci sono ulteriori elementi, solleva l’eccezione StopIteration. Questo metodo corrisponde allo slot tp_iternext della struttura dei tipi per oggetti Python nell’API Python/C.

Python definisce diversi oggetti iteratore per supportare l’iterazione su tipi di sequenze generali e specifici, dizionari e altre forme più specializzate. I tipi specifici non sono importanti oltre la loro implementazione del protocollo dell’iteratore.

Una volta che il metodo __next__() di un iteratore solleva StopIteration, deve continuare a farlo nelle chiamate successive. Implementazioni che non rispettano questa proprietà sono considerate difettose.

Tipi di Generatore

I generatori di Python forniscono un modo conveniente per implementare il protocollo iterator. Se il metodo __iter__() di un oggetto contenitore è implementato come un generatore, restituirà automaticamente un oggetto iteratore (tecnicamente, un oggetto generatore) che fornisce i metodi __iter__() e __next__(). Maggiori informazioni sui generatori si possono trovare nella documentazione sull’espressione yield.

Tipi di Sequenza — list, tuple, range

Esistono tre tipi di sequenza fondamentali: liste, tuple e oggetti range. Ulteriori tipi di sequenza adatti per l’elaborazione di dati binari e stringhe di testo sono descritti in sezioni dedicate.

Operazioni Comuni sulle Sequenze

Le operazioni nella tabella seguente sono supportate dalla maggior parte dei tipi di sequenza, sia mutabili che immutabili. La ABC collections.abc.Sequence è fornita per facilitare l’implementazione corretta di queste operazioni su tipi di sequenza personalizzati.

Questa tabella elenca le operazioni di sequenza ordinate in ordine crescente di priorità. Nella tabella, s e t sono sequenze dello stesso tipo, n, i, j e k sono interi e x è un oggetto arbitrario che soddisfa eventuali restrizioni di tipo e valore imposte da s.

Le operazioni in e not in hanno le stesse priorità delle operazioni di confronto. Le operazioni + (concatenazione) e * (ripetizione) hanno la stessa priorità delle corrispondenti operazioni numeriche. [3]

Operazione	Risultato	Note
x in s	True se un elemento di s è uguale a x, altrimenti False	(1)
x not in s	False se un elemento di s è uguale a x, altrimenti True	(1)
s + t	la concatenazione di s e t	(6)(7)
s * n o n * s	equivalente ad aggiungere s a se stesso n volte	(2)(7)
s[i]	i-esimo elemento di s, origine 0	(3)
s[i:j]	fetta di s da i a j	(3)(4)
s[i:j:k]	fetta di s da i a j con passo k	(3)(5)
len(s)	lunghezza di s
min(s)	l’elemento più piccolo di s
max(s)	l’elemento più grande di s
s.index(x[, i[, j]])	indice della prima occorrenza di x in s (a partire dall’indice i e prima dell’indice j)	(8)
s.count(x)	numero totale delle occorrenze di x in s

Sequenze dello stesso tipo supportano anche confronti. In particolare, tuple e liste sono confrontate lessicograficamente confrontando gli elementi corrispondenti. Questo significa che per risultare uguali, ogni elemento deve risultare uguale e le due sequenze devono essere dello stesso tipo e avere la stessa lunghezza. (Per i dettagli completi, vedere Comparisons nella documentazione del linguaggio.)

Gli iteratori avanti e indietro su sequenze mutabili accedono ai valori usando un indice. Questo indice continuerà ad avanzare (o retrocedere) anche se la sequenza sottostante viene mutata. L’iteratore termina solo quando viene trovata un’eccezione IndexError o StopIteration (o quando l’indice scende sotto zero).

Note:

1. Anche se le operazioni in e not in sono usate solo per testare la semplice appartenenza nel caso generale, alcune sequenze specializzate (come str, bytes e bytearray) le usano anche per il test di sotto-sequenza:

   >>> "gg" in "eggs"
   True
   

2. I valori di n inferiori a 0 sono trattati come 0 (il che produce una sequenza vuota dello stesso tipo di s). Nota che gli elementi nella sequenza s non vengono copiati; sono referenziati più volte. Questo spesso confonde i nuovi programmatori Python; considera:

   >>> lists = [[]] * 3
   >>> lists
   [[], [], []]
   >>> lists[0].append(3)
   >>> lists
   [[3], [3], [3]]
   

   Quello che è successo è che [[]] è una lista a un solo elemento contenente una lista vuota, quindi tutti e tre gli elementi di [[]] * 3 sono riferimenti a questa singola lista vuota. Modificare uno qualsiasi degli elementi di lists modifica questa singola lista. Puoi creare una lista di liste diverse in questo modo:

   >>> lists = [[] for i in range(3)]
   >>> lists[0].append(3)
   >>> lists[1].append(5)
   >>> lists[2].append(7)
   >>> lists
   [[3], [5], [7]]
   

   Ulteriori spiegazioni sono disponibili nella voce delle FAQ How do I create a multidimensional list?.

3. Se i o j è negativo, l’indice è relativo alla fine della sequenza s: viene sostituito da len(s) + i o len(s) + j. Ma nota che -0 è ancora 0.

4. La fetta di s da i a j è definita come la sequenza degli elementi con indice k tale che i <= k < j. Se i o j è maggiore di len(s), viene usato len(s). Se i è omesso o None, viene usato 0. Se j è omesso o None, viene usato len(s). Se i è maggiore o uguale a j, la fetta è vuota.

5. La fetta di s da i a j con passo k è definita come la sequenza degli elementi con indice x = i + n*k tale che 0 <= n < (j-i)/k. In altre parole, gli indici sono i, i+k, i+2*k, i+3*k e così via, fermandosi quando si raggiunge j (ma senza includere j). Quando k è positivo, i e j sono ridotti a len(s) se sono maggiori. Quando k è negativo, i e j sono ridotti a len(s) - 1 se sono maggiori. Se i o j sono omessi o None, diventano valori «finali» (quale finale dipende dal segno di k). Nota, k non può essere zero. Se k è None, viene trattato come 1.

6. La concatenazione di sequenze immutabili produce sempre un nuovo oggetto. Questo significa che costruire una sequenza concatenando ripetutamente avrà un costo di runtime quadratico in relazione alla lunghezza totale della sequenza. Per ottenere un costo di runtime lineare, è necessario passare a una delle alternative seguenti:

   • se stai concatenando oggetti str, puoi costruire una lista e usare str.join() alla fine oppure scrivere a un’istanza di io.StringIO e recuperare il suo valore al termine

   • se stai concatenando oggetti bytes, puoi allo stesso modo usare bytes.join() o io.BytesIO, oppure puoi fare una concatenazione in loco con un oggetto bytearray. Gli oggetti bytearray sono mutabili e hanno un meccanismo di sovra-allocazione efficiente

   • se concatenare oggetti tuple, estendere una list invece

   • per altri tipi, consultare la documentazione della classe pertinente

7. Alcuni tipi di sequenze (come range) supportano solo sequenze di elementi che seguono schemi specifici, e quindi non supportano la concatenazione o la ripetizione della sequenza.

8. index solleva ValueError quando x non è trovato in s. Non tutte le implementazioni supportano il passaggio degli argomenti aggiuntivi i e j. Questi argomenti permettono una ricerca efficiente di sottosezioni della sequenza. Passare gli argomenti extra è grosso modo equivalente a usare s[i:j].index(x), solo senza copiare alcun dato e con l’indice restituito relativo all’inizio della sequenza piuttosto che all’inizio del sottoinsieme.

Tipi di Sequenza Immutabili

L’unica operazione che i tipi di sequenza immutabili generalmente implementano che non è implementata anche dai tipi di sequenza mutabili è il supporto per la funzione built-in hash().

Questo supporto consente alle sequenze immutabili, come le istanze di tuple, di essere utilizzate come chiavi di dict e memorizzate in istanze di set e frozenset.

Tentare di fare l’hash di una sequenza immutabile che contiene valori non hashabili risulterà in un TypeError.

Tipi di Sequenza Mutabili

Le operazioni nella tabella seguente sono definite sui tipi di sequenza mutabili. L’ABC collections.abc.MutableSequence è fornito per rendere più facile implementare correttamente queste operazioni su tipi di sequenza personalizzati.

Nella tabella, s è un’istanza di un tipo di sequenza mutabile, t è un qualsiasi oggetto iterabile e x è un oggetto arbitrario che soddisfa qualsiasi restrizione di tipo e valore imposta da s (ad esempio, bytearray accetta solo interi che soddisfano la restrizione di valore 0 <= x <= 255).

Operazione	Risultato	Note
s[i] = x	l’elemento i di s è sostituito da x
s[i:j] = t	il sottoinsieme di s da i a j è sostituito dal contenuto dell’iterabile t
del s[i:j]	come s[i:j] = []
s[i:j:k] = t	gli elementi di s[i:j:k] sono sostituiti da quelli di t	(1)
del s[i:j:k]	rimuove gli elementi di s[i:j:k] dalla lista
s.append(x)	aggiunge x alla fine della sequenza (come s[len(s):len(s)] = [x])
s.clear()	rimuove tutti gli elementi da s (come del s[:])	(5)
s.copy()	crea una copia superficiale di s (come s[:])	(5)
s.extend(t) o s += t	estende s con il contenuto di t (per lo più come s[len(s):len(s)] = t)
s *= n	aggiorna s con il suo contenuto ripetuto n volte	(6)
s.insert(i, x)	inserisce x in s all’indice dato da i (come s[i:i] = [x])
s.pop() o s.pop(i)	recupera l’elemento a i e lo rimuove anche da s	(2)
s.remove(x)	removes the first item from s where s[i] is equal to x	(3)
s.reverse()	inverte gli elementi di s in loco	(4)

Note:

1. If k is not equal to 1, t must have the same length as the slice it is replacing.

2. L’argomento opzionale i di default è -1, in modo che per default l’ultimo elemento sia rimosso e restituito.

3. remove() solleva ValueError quando x non è trovato in s.

4. Il metodo reverse() modifica la sequenza in loco per economia di spazio quando si inverte una grande sequenza. Per ricordare agli utenti che opera tramite effetti collaterali, non restituisce la sequenza invertita.

5. clear() e copy() sono inclusi per coerenza con le interfacce dei contenitori mutabili che non supportano le operazioni di slicing (come dict e set). copy() non fa parte dell’ABC collections.abc.MutableSequence, ma la maggior parte delle classi di sequenze mutabili concrete lo forniscono.

   Added in version 3.3: Metodi clear() e copy().

6. Il valore n è un intero, o un oggetto che implementa __index__(). Valori zero e negativi di n svuotano la sequenza. Gli elementi nella sequenza non sono copiati; sono referenziati più volte, come spiegato per s * n sotto Operazioni Comuni sulle Sequenze.

Liste

Le liste sono sequenze mutabili, tipicamente utilizzate per memorizzare collezioni di elementi omogenei (dove il grado di somiglianza preciso varia in base all’applicazione).

class list([iterable])

Le liste possono essere costruite in diversi modi:

• Usare una coppia di parentesi quadre per denotare la lista vuota: []

• Utilizzo delle parentesi quadre, separando gli elementi con virgole: [a], [a, b, c]

• Utilizzo di una lista comprensiva: [x for x in iterable]

• Utilizzo del costruttore del tipo: list() o list(iterable)

Il costruttore costruisce una lista i cui elementi sono gli stessi e nello stesso ordine degli elementi di iterable. iterable può essere una sequenza, un contenitore che supporta l’iterazione, o un oggetto iteratore. Se iterable è già una lista, viene fatta una copia e restituita, simile a iterable[:]. Ad esempio, list('abc') restituisce ['a', 'b', 'c'] e list( (1, 2, 3) ) restituisce [1, 2, 3]. Se non viene fornito alcun argomento, il costruttore crea una nuova lista vuota, [].

Molte altre operazioni producono anche liste, includendo la funzione built-in sorted().

Le liste implementano tutte le operazioni comuni di sequenza: common e modificabili: mutable. Le liste forniscono anche il seguente metodo aggiuntivo:

sort(*, key=None, reverse=False)

Questo metodo ordina la lista sul posto, utilizzando solo i confronti < tra gli elementi. Le eccezioni non vengono soppresse - se una qualsiasi operazione di confronto fallisce, l’intera operazione di ordinamento fallirà (e la lista sarà probabilmente lasciata in uno stato parzialmente modificato).

sort() accetta due argomenti che possono essere passati solo tramite parola chiave (keyword-only arguments):

key specifica una funzione di un argomento che viene utilizzata per estrarre una chiave di confronto da ciascun elemento della lista (ad esempio, key=str.lower). La chiave corrispondente a ciascun elemento nella lista viene calcolata una volta e poi utilizzata per l’intero processo di ordinamento. Il valore predefinito di None significa che gli elementi della lista vengono ordinati direttamente senza calcolare un valore di chiave separato.

L’utilità functools.cmp_to_key() è disponibile per convertire una funzione cmp in stile 2.x in una funzione key.

reverse è un valore booleano. Se impostato su True, gli elementi della lista vengono ordinati come se ogni confronto fosse invertito.

Questo metodo modifica la sequenza in loco per risparmiare spazio quando si ordina una grande sequenza. Per ricordare agli utenti che funziona con effetti collaterali, non restituisce la sequenza ordinata (utilizzare sorted() per richiedere esplicitamente una nuova istanza di lista ordinata).

Il metodo sort() è garantito per essere stabile. Un ordinamento è stabile se garantisce di non cambiare l’ordine relativo degli elementi che risultano uguali — questo è utile per l’ordinamento in più passate (ad esempio, ordinare per reparto, poi per grado salariale).

Per esempi di ordinamento e un breve tutorial sull’ordinamento, vedere Sorting Techniques.

Dettaglio dell’implementazione di CPython: Mentre una lista viene ordinata, l’effetto di tentare di modificarla o anche solo ispezionarla è indefinito. L’implementazione C di Python fa apparire la lista vuota per la durata, e solleva ValueError se riesce a rilevare che la lista è stata modificata durante un ordinamento.

Tuple

Le tuple sono sequenze immutabili, tipicamente utilizzate per memorizzare collezioni di dati eterogenei (come le 2-tuple prodotte dalla funzione built-in enumerate()). Le tuple sono utilizzate anche nei casi in cui è necessaria una sequenza immutabile di dati omogenei (come permettere la memorizzazione in un’istanza di set o dict).

class tuple([iterable])

Le tuple possono essere costruite in diversi modi:

• Utilizzando una coppia di parentesi per denotare la tupla vuota: ()

• Utilizzando una virgola finale per una tupla singleton: a, o (a,)

• Separando gli elementi con virgole: a, b, c o (a, b, c)

• Utilizzando la funzione built-in tuple(): tuple() o tuple(iterable)

Il costruttore costruisce una tupla i cui elementi sono gli stessi e nello stesso ordine degli elementi di iterable. iterable può essere una sequenza, un contenitore che supporta l’iterazione, o un oggetto iteratore. Se iterable è già una tupla, viene restituita invariata. Ad esempio, tuple('abc') restituisce ('a', 'b', 'c') e tuple( [1, 2, 3] ) restituisce (1, 2, 3). Se non viene fornito alcun argomento, il costruttore crea una nuova tupla vuota, ().

Nota che in realtà è la virgola che crea una tupla, non le parentesi. Le parentesi sono facoltative, tranne nel caso della tupla vuota, o quando sono necessarie per evitare ambiguità sintattiche. Ad esempio, f(a, b, c) è una chiamata a funzione con tre argomenti, mentre f((a, b, c)) è una chiamata a funzione con una 3-tuple come unico argomento.

Le tuple implementano tutte le operazioni di sequenza comuni: common.

Per collezioni eterogenee di dati dove l’accesso per nome è più chiaro che l’accesso per indice, collections.namedtuple() può essere una scelta più appropriata di un semplice oggetto tupla.

Intervalli

Il tipo range rappresenta una sequenza immutabile di numeri ed è comunemente utilizzato per iterare un numero specifico di volte nei cicli for.

class range(stop)

class range(start, stop[, step])

Gli argomenti al costruttore di range devono essere interi (sia la classe built-in int o qualsiasi oggetto che implementa il metodo speciale __index__()). Se l’argomento step è omesso, il valore predefinito è 1. Se l’argomento start è omesso, il valore predefinito è 0. Se step è zero, viene sollevata l’eccezione ValueError.

Per un step positivo, il contenuto di un intervallo r è determinato dalla formula r[i] = start + step*i dove i >= 0 e r[i] < stop.

Per un step negativo, il contenuto dell’intervallo è ancora determinato dalla formula r[i] = start + step*i, ma i vincoli sono i >= 0 e r[i] > stop.

Un oggetto range sarà vuoto se r[0] non soddisfa il vincolo di valore. Gli intervalli supportano indici negativi, ma questi sono interpretati come indice dalla fine della sequenza determinata dagli indici positivi.

Gli intervalli contenenti valori assoluti maggiori di sys.maxsize sono permessi, ma alcune funzionalità (come len()) potrebbero sollevare l’eccezione OverflowError.

Esempi di intervalli:

>>> 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))
[]

Gli intervalli implementano tutte le operazioni di sequenza comuni: common, eccezion fatta per la concatenazione e la ripetizione (a causa del fatto che gli oggetti range possono rappresentare solo sequenze che seguono un modello rigoroso e la ripetizione e la concatenazione violerebbero di solito tale modello).

start

Il valore del parametro start (o 0 se il parametro non è stato fornito)

stop

Il valore del parametro stop

step

Il valore del parametro step (o 1 se il parametro non è stato fornito)

Il vantaggio del tipo range rispetto a una lista regolare list o una tupla tuple è che un oggetto range utilizzerà sempre la stessa (piccola) quantità di memoria, indipendentemente dalla dimensione dell’intervallo che rappresenta (poiché memorizza solo i valori start, stop e step, calcolando gli elementi individuali e i sottointervalli secondo necessità).

Gli oggetti range implementano l’ABC collections.abc.Sequence, e forniscono funzionalità come test di inclusione, ricerca dell’indice degli elementi, slicing e supporto per indici negativi (vedi Tipi di Sequenza — 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

Testare gli oggetti range per uguaglianza con == e != li confronta come sequenze. Cioè, due oggetti range sono considerati uguali se rappresentano la stessa sequenza di valori. (Nota che due oggetti range che risultano uguali potrebbero avere attributi start, stop e step diversi, ad esempio range(0) == range(2, 1, 3) oppure range(0, 3, 2) == range(0, 4, 2).)

Cambiato nella versione 3.2: Implementare l’ABC Sequence. Supporto per slicing e indici negativi. Testare gli oggetti int per la membership in tempo costante invece di iterare attraverso tutti gli elementi.

Cambiato nella versione 3.3: Definire “==” e “!=” per confrontare gli oggetti range basandosi sulla sequenza di valori che definiscono (invece di confrontare basandosi sull’identità degli oggetti).

Aggiunti gli attributi start, stop e step.

Vedi anche

• The linspace recipe shows how to implement a lazy version of range suitable for floating-point applications.

Tipo Sequenza di Testo — str

I dati testuali in Python sono gestiti con oggetti str, o string. Le stringhe sono sequenze immutabili di punti di codice Unicode. I letterali stringa possono essere scritti in vari modi:

• Apici singoli: 'allows embedded "double" quotes'

• Apici doppi: "allows embedded 'single' quotes"

• Apici tripli: '''Three single quotes''', """Three double quotes"""

Le stringhe con tripla virgoletta possono estendersi su più righe - tutti gli spazi bianchi associati saranno inclusi nel letterale della stringa.

I letterali di stringa che fanno parte di una singola espressione e contengono solo spazi bianchi tra di loro saranno convertiti implicitamente in un singolo letterale di stringa. Cioè, ("spam " "eggs") == "spam eggs".

Vedi String and Bytes literals per ulteriori dettagli sulle varie forme di letterali di stringa, comprese le sequenze di escape supportate, e il prefisso r («raw») che disabilita la maggior parte delle elaborazioni delle sequenze di escape.

Le stringhe possono anche essere create da altri oggetti utilizzando il costruttore str.

Poiché non esiste un tipo «carattere» separato, l’indicizzazione di una stringa produce stringhe di lunghezza 1. Cioè, per una stringa non vuota s, s[0] == s[0:1].

Inoltre, non esiste un tipo di stringa mutabile, ma str.join() o io.StringIO possono essere usati per costruire efficientemente stringhe da più frammenti.

Cambiato nella versione 3.3: Per retrocompatibilità con la serie Python 2, il prefisso u è nuovamente permesso sui letterali di stringa. Non ha effetto sul significato dei letterali di stringa e non può essere combinato con il prefisso r.

class str(object='')

class str(object=b'', encoding='utf-8', errors='strict')

Restituisce una versione stringa di object. Se object non viene fornito, restituisce la stringa vuota. Altrimenti, il comportamento di str() dipende dalla presenza di encoding o errors, come segue.

Se né encoding né errors vengono forniti, str(object) restituisce type(object).__str__(object) che è la rappresentazione «informale» o ben stampabile di object. Per gli oggetti stringa, questa è la stringa stessa. Se object non ha un metodo __str__(), allora str() ricorre alla restituzione di repr(object).

Se viene fornito almeno uno tra encoding o errors, object dovrebbe essere un bytes-like object (ad es. bytes o bytearray). In questo caso, se object è un oggetto bytes (o bytearray), allora str(bytes, encoding, errors) è equivalente a bytes.decode(encoding, errors). Altrimenti, l’oggetto bytes sottostante l’oggetto buffer viene ottenuto prima di chiamare bytes.decode(). Vedi Tipi di sequenze binarie — bytes, bytearray, memoryview e Buffer Protocol per informazioni sugli oggetti buffer.

Passare un oggetto bytes a str() senza argomenti encoding o errors rientra nel primo caso che restituisce la rappresentazione informale della stringa (vedi anche l’opzione della riga di comando -b di Python). Per esempio:

>>> str(b'Zoot!')
"b'Zoot!'"

Per maggiori informazioni sulla classe str e i suoi metodi, vedere Tipo Sequenza di Testo — str e la sezione Metodi per le Stringhe qui sotto. Per generare stringhe formattate, vedere le sezioni f-strings e Format String Syntax. Inoltre, vedere la sezione Text Processing Services.

Metodi per le Stringhe

Le stringhe implementano tutte le operazioni delle sequenze comuni, insieme ai metodi aggiuntivi descritti di seguito.

Le stringhe supportano anche due stili di formattazione delle stringhe, uno che fornisce un alto grado di flessibilità e personalizzazione (vedi str.format(), Format String Syntax e Custom String Formatting) e l’altro basato sulla formattazione in stile C printf che gestisce una gamma più ristretta di tipi ed è leggermente più difficile da usare correttamente, ma è spesso più veloce nei casi che può gestire (Formattazione delle stringhe in stile printf).

La sezione Text Processing Services della libreria standard copre un certo numero di altri moduli che forniscono vari utilità relative al testo (incluso il supporto per le espressioni regolari nel modulo re).

str.capitalize()

Restituisce una copia della stringa con il primo carattere in maiuscolo e il resto in minuscolo.

Cambiato nella versione 3.8: Il primo carattere è ora convertito in titlecase piuttosto che in maiuscolo. Questo significa che caratteri come i digrammi avranno solo la prima lettera maiuscola, invece del carattere completo.

str.casefold()

Restituisce una copia della stringa normalizzata in minuscolo. Le stringhe normalizzate in minuscolo possono essere utilizzate per confronti senza distinzione tra maiuscole e minuscole.

La normalizzazione in minuscolo è simile alla conversione in minuscolo ma più aggressiva perché è pensata per rimuovere tutte le differenze di maiuscolo e minuscolo in una stringa. Ad esempio, la lettera tedesca minuscola 'ß' è equivalente a "ss". Poiché è già minuscola, lower() non farebbe nulla per 'ß'; casefold() la converte in "ss".

L’algoritmo di casefolding è descritto nella sezione 3.13 “Default Case Folding” dello Standard Unicode.

Added in version 3.3.

str.center(width[, fillchar])

Restituisce la stringa centrata in una lunghezza di width. L’imbottitura è fatta usando il fillchar specificato (il default è uno spazio ASCII). La stringa originale viene restituita se width è minore o uguale a len(s).

str.count(sub[, start[, end]])

Restituisce il numero di occorrenze non sovrapposte della sottostringa sub nell’intervallo [start, end]. Gli argomenti opzionali start e end sono interpretati come nella notazione delle slice.

Se sub è vuoto, restituisce il numero di stringhe vuote tra i caratteri, che è la lunghezza della stringa più uno.

str.encode(encoding='utf-8', errors='strict')

Restituisce la stringa codificata in bytes.

encoding di default è 'utf-8'; vedere Standard Encodings per i valori possibili.

errors controlla come vengono gestiti gli errori di codifica. Se 'strict' (il default), viene sollevata un’eccezione UnicodeError. Altri valori possibili sono 'ignore', 'replace', 'xmlcharrefreplace', 'backslashreplace' e qualsiasi altro nome registrato tramite codecs.register_error(). Vedi Error Handlers per dettagli.

Per motivi di prestazioni, il valore di errors non viene controllato per validità a meno che non si verifichi effettivamente un errore di codifica, Python Development Mode è abilitato o viene utilizzata una build di debug.

Cambiato nella versione 3.1: Aggiunto supporto per argomenti di tipo keyword.

Cambiato nella versione 3.9: Il valore dell’argomento errors ora viene controllato in Python Development Mode e in modalità di debug.

str.endswith(suffix[, start[, end]])

Restituisce True se la stringa termina con il suffix specificato, altrimenti restituisce False. suffix può anche essere una tupla di suffixes da cercare. Con start opzionale, il test inizia dalla posizione specificata. Con end opzionale, si interrompe il confronto in quella posizione.

str.expandtabs(tabsize=8)

Restituisce una copia della stringa in cui tutti i caratteri di tabulazione sono sostituiti da uno o più spazi, a seconda della colonna corrente e della dimensione della tabulazione specificata. Le posizioni delle tabulazioni si verificano ogni tabsize caratteri (il default è 8, dando posizioni delle tabulazioni alle colonne 0, 8, 16 e così via). Per espandere la stringa, la colonna corrente viene impostata a zero e la stringa viene esaminata carattere per carattere. Se il carattere è una tabulazione (\t), uno o più caratteri di spazio vengono inseriti nel risultato fino a quando la colonna corrente è uguale alla successiva posizione di tabulazione. (Il carattere di tabulazione stesso non viene copiato.) Se il carattere è una nuova linea (\n) o ritorno a capo (\r), viene copiato e la colonna corrente viene reimpostata a zero. Qualsiasi altro carattere viene copiato senza modifiche e la colonna corrente viene incrementata di uno indipendentemente da come viene rappresentato il carattere quando stampato.

>>> '01\t012\t0123\t01234'.expandtabs()
'01      012     0123    01234'
>>> '01\t012\t0123\t01234'.expandtabs(4)
'01  012 0123    01234'

str.find(sub[, start[, end]])

Restituisce l’indice più basso nella stringa in cui la sottostringa sub è trovata all’interno dell’intervallo s[start:end]. Gli argomenti opzionali start e end sono interpretati come nella notazione delle slice. Restituisce -1 se sub non viene trovata.

Nota

Il metodo find() dovrebbe essere utilizzato solo se si ha bisogno di conoscere la posizione di sub. Per verificare se sub è una sottostringa o meno, usa l’operatore in:

>>> 'Py' in 'Python'
True

str.format(*args, **kwargs)

Esegui un’operazione di formattazione della stringa. La stringa su cui viene chiamato questo metodo può contenere testo letterale o campi di sostituzione delimitati da parentesi graffe {}. Ogni campo di sostituzione contiene l’indice numerico di un argomento posizionale o il nome di un argomento keyword. Restituisce una copia della stringa dove ogni campo di sostituzione è sostituito con il valore della stringa dell’argomento corrispondente.

>>> "The sum of 1 + 2 is {0}".format(1+2)
'The sum of 1 + 2 is 3'

Vedi Format String Syntax per una descrizione delle varie opzioni di formattazione che possono essere specificate nelle stringhe di formattazione.

Nota

Quando si formatta un numero (int, float, complex, decimal.Decimal e sottoclassi) con il tipo n (es: '{:n}'.format(1234)), la funzione imposta temporaneamente il locale LC_CTYPE sul locale LC_NUMERIC per decodificare i campi decimal_point e thousands_sep di localeconv() se sono non-ASCII o più lunghi di 1 byte, e il locale LC_NUMERIC è diverso dal locale LC_CTYPE. Questo cambiamento temporaneo influisce su altri thread.

Cambiato nella versione 3.7: Quando si formatta un numero con il tipo n, la funzione imposta temporaneamente il locale LC_CTYPE sul locale LC_NUMERIC in alcuni casi.

str.format_map(mapping)

Simile a str.format(**mapping), tranne che mapping viene utilizzato direttamente e non copiato in un dict. Questo è utile se, per esempio, mapping è una sottoclasse di 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'

Added in version 3.2.

str.index(sub[, start[, end]])

Come find(), ma solleva ValueError quando la sottostringa non viene trovata.

str.isalnum()

Restituisce True se tutti i caratteri della stringa sono alfanumerici e c’è almeno un carattere, False altrimenti. Un carattere c è alfanumerico se uno dei seguenti restituisce True: c.isalpha(), c.isdecimal(), c.isdigit(), o c.isnumeric().

str.isalpha()

Restituisce True se tutti i caratteri nella stringa sono alfabetici e c’è almeno un carattere, False altrimenti. I caratteri alfabetici sono quelli definiti nel database dei caratteri Unicode come «Letter», cioè quelli con proprietà di categoria generale essendo una di «Lm», «Lt», «Lu», «Ll», o «Lo». Nota che questo è diverso dalla proprietà Alfabetica definita nella sezione 4.10 “Letters, Alphabetic, and Ideographic” dello Standard Unicode.

str.isascii()

Restituisce True se la stringa è vuota o tutti i caratteri della stringa sono ASCII, False altrimenti. I caratteri ASCII hanno punti di codice nell’intervallo U+0000-U+007F.

Added in version 3.7.

str.isdecimal()

Restituisce True se tutti i caratteri della stringa sono caratteri decimali e c’è almeno un carattere, False altrimenti. I caratteri decimali sono quelli che possono essere usati per formare numeri in base 10, ad es. U+0660, NUMERO ZERO ARABICO-INDICO. Formalmente, un carattere decimale è un carattere nella categoria generale Unicode «Nd».

str.isdigit()

Restituisce True se tutti i caratteri della stringa sono cifre e c’è almeno un carattere, False altrimenti. Le cifre includono i caratteri decimali e le cifre che necessitano di una gestione speciale, come le cifre in apice di compatibilità. Questo copre le cifre che non possono essere usate per formare numeri in base 10, come i numeri Kharosthi. Formalmente, una cifra è un carattere che ha la proprietà Numeric_Type=Digit o Numeric_Type=Decimal.

str.isidentifier()

Restituisce True se la stringa è un identificatore valido secondo la definizione del linguaggio, sezione Identifiers and keywords.

keyword.iskeyword() può essere utilizzata per testare se la stringa s è un identificatore riservato, come def e class.

Esempio:

>>> from keyword import iskeyword

>>> 'hello'.isidentifier(), iskeyword('hello')
(True, False)
>>> 'def'.isidentifier(), iskeyword('def')
(True, True)

str.islower()

Restituisce True se tutti i caratteri con distinzione di maiuscole e minuscole [4] della stringa sono minuscoli e c’è almeno un carattere con distinzione di maiuscole e minuscole, False altrimenti.

str.isnumeric()

Restituisce True se tutti i caratteri della stringa sono caratteri numerici, e c’è almeno un carattere, False altrimenti. I caratteri numerici includono i caratteri delle cifre, e tutti i caratteri che hanno la proprietà valore numerico Unicode, ad es. U+2155, FRAZIONE VOLGARE UN QUINTO. Formalmente, i caratteri numerici sono quelli con la proprietà valore Numeric_Type=Digit, Numeric_Type=Decimal o Numeric_Type=Numeric.

str.isprintable()

Restituisce True se tutti i caratteri nella stringa sono stampabili o se la stringa è vuota, altrimenti False. I caratteri non stampabili sono quelli definiti nel database dei caratteri Unicode come «Other» o «Separator», eccetto lo spazio ASCII (0x20) che è considerato stampabile. (Si noti che i caratteri stampabili in questo contesto sono quelli che non devono essere escape quando la funzione repr() viene invocata su una stringa. Non influisce sulla gestione delle stringhe scritte su sys.stdout o sys.stderr).

str.isspace()

Restituisce True se ci sono solo caratteri di spazio nella stringa e c’è almeno un carattere, altrimenti False.

Un carattere è spazio se nel database dei caratteri Unicode (vedi unicodedata) la sua categoria generale è Zs («Separator, space»), o se la sua classe bidirezionale è una delle seguenti WS, B, o S.

str.istitle()

Restituisce True se la stringa è una stringa con iniziale maiuscola e c’è almeno un carattere; ad esempio, i caratteri maiuscoli possono seguire solo caratteri senza distinzione maiuscola o minuscola e i caratteri minuscoli solo quelli con distinzione. Restituisce False altrimenti.

str.isupper()

Restituisce True se tutti i caratteri con distinzione [4] nella stringa sono maiuscoli e c’è almeno un carattere con distinzione, altrimenti False.

>>> 'BANANA'.isupper()
True
>>> 'banana'.isupper()
False
>>> 'baNana'.isupper()
False
>>> ' '.isupper()
False

str.join(iterable)

Restituisce una stringa che è la concatenazione delle stringhe in iterable. Verrà sollevato un TypeError se ci sono valori non stringa in iterable, inclusi gli oggetti di tipo bytes. Il separatore tra gli elementi è la stringa che fornisce questo metodo.

str.ljust(width[, fillchar])

Restituisce la stringa allineata a sinistra in una stringa di lunghezza width. La spaziatura viene eseguita utilizzando il fillchar specificato (il valore predefinito è uno spazio ASCII). La stringa originale viene restituita se width è minore o uguale alla lunghezza di len(s).

str.lower()

Restituisce una copia della stringa con tutti i caratteri con distinzione [4] convertiti in minuscolo.

L’algoritmo di conversione in minuscolo usato è descritto nella sezione 3.13 “Default Case Folding” dello Standard Unicode.

str.lstrip([chars])

Restituisce una copia della stringa con i caratteri iniziali rimossi. L’argomento chars è una stringa che specifica l’insieme di caratteri da rimuovere. Se omesso o None, l’argomento chars predefinito rimuove gli spazi bianchi. L’argomento chars non è un prefisso; piuttosto, tutte le combinazioni dei suoi valori vengono rimosse:

>>> '   spacious   '.lstrip()
'spacious   '
>>> 'www.example.com'.lstrip('cmowz.')
'example.com'

Vedi str.removeprefix() per un metodo che rimuova un singolo prefisso stringa piuttosto che tutti i caratteri di un insieme. Ad esempio:

>>> 'Arthur: three!'.lstrip('Arthur: ')
'ee!'
>>> 'Arthur: three!'.removeprefix('Arthur: ')
'three!'

static str.maketrans(x[, y[, z]])

Questo metodo statico restituisce una tabella di traduzione utilizzabile per str.translate().

Se c’è solo un argomento, deve essere un dizionario che mappa gli ordinali Unicode (interi) o caratteri (stringhe di lunghezza 1) a ordinali Unicode, stringhe (di lunghezza arbitraria) o None. Le chiavi dei caratteri verranno quindi convertite in ordinali.

Se ci sono due argomenti, devono essere stringhe della stessa lunghezza, e nel dizionario risultante, ciascun carattere in x sarà mappato al carattere nella stessa posizione in y. Se c’è un terzo argomento, deve essere una stringa, i cui caratteri verranno mappati a None nel risultato.

str.partition(sep)

Divide la stringa alla prima occorrenza di sep, e restituisce una tuple a 3 elementi contenente la parte prima del separatore, il separatore stesso, e la parte dopo il separatore. Se il separatore non viene trovato, restituisce una tuple a 3 elementi contenente la stringa stessa, seguita da due stringhe vuote.

str.removeprefix(prefix, /)

Se la stringa inizia con la stringa prefix, restituisce string[len(prefix):]. Altrimenti, restituisce una copia della stringa originale:

>>> 'TestHook'.removeprefix('Test')
'Hook'
>>> 'BaseTestCase'.removeprefix('Test')
'BaseTestCase'

Added in version 3.9.

str.removesuffix(suffix, /)

Se la stringa termina con la stringa suffix e tale suffix non è vuota, restituisce string[:-len(suffix)]. Altrimenti, restituisce una copia della stringa originale:

>>> 'MiscTests'.removesuffix('Tests')
'Misc'
>>> 'TmpDirMixin'.removesuffix('Tests')
'TmpDirMixin'

Added in version 3.9.

str.replace(old, new[, count])

Restituisce una copia della stringa con tutte le occorrenze della sottostringa old sostituite da new. Se viene fornito l’argomento opzionale count, solo le prime count occorrenze vengono sostituite.

str.rfind(sub[, start[, end]])

Restituisce l’indice più alto nella stringa dove la sottostringa sub viene trovata, in modo tale che sub sia contenuta in s[start:end]. Gli argomenti opzionali start e end sono interpretati come nella notazione delle sezioni. Restituisce -1 in caso di fallimento.

str.rindex(sub[, start[, end]])

Come rfind() ma solleva ValueError quando la sottostringa sub non viene trovata.

str.rjust(width[, fillchar])

Restituisce la stringa allineata a destra in una stringa di lunghezza width. La spaziatura viene eseguita utilizzando il fillchar specificato (il valore predefinito è uno spazio ASCII). La stringa originale viene restituita se width è minore o uguale alla lunghezza di len(s).

str.rpartition(sep)

Divide la stringa all’ultima occorrenza di sep, e restituisce una tuple a 3 elementi contenente la parte prima del separatore, il separatore stesso, e la parte dopo il separatore. Se il separatore non viene trovato, restituisce una tuple a 3 elementi contenente due stringhe vuote, seguite dalla stringa stessa.

str.rsplit(sep=None, maxsplit=-1)

Restituisce un elenco delle parole nella stringa, utilizzando sep come stringa delimitante. Se è dato maxsplit, sono eseguite al massimo maxsplit divisioni, quelle più a destra. Se sep non è specificato o è None, qualsiasi stringa di spazi bianchi è un separatore. A eccezione della divisione da destra, rsplit() si comporta come split() che viene descritto in dettaglio sotto.

str.rstrip([chars])

Restituisce una copia della stringa con i caratteri finali rimossi. L’argomento chars è una stringa che specifica l’insieme di caratteri da rimuovere. Se omesso o None, l’argomento chars predefinito rimuove gli spazi bianchi. L’argomento chars non è un suffisso; piuttosto, tutte le combinazioni dei suoi valori vengono rimosse:

>>> '   spacious   '.rstrip()
'   spacious'
>>> 'mississippi'.rstrip('ipz')
'mississ'

Vedi str.removesuffix() per un metodo che rimuova un singolo suffisso stringa piuttosto che tutti i caratteri di un insieme. Ad esempio:

>>> 'Monty Python'.rstrip(' Python')
'M'
>>> 'Monty Python'.removesuffix(' Python')
'Monty'

str.split(sep=None, maxsplit=-1)

Restituisce un elenco delle parole nella stringa, utilizzando sep come stringa delimitante. Se è dato maxsplit, sono eseguite al massimo maxsplit divisioni (quindi, l’elenco avrà al massimo maxsplit+1 elementi). Se maxsplit non è specificato o è -1, allora non c’è limite al numero di divisioni (vengono eseguite tutte le divisioni possibili).

If sep is given, consecutive delimiters are not grouped together and are deemed to delimit empty strings (for example, '1,,2'.split(',') returns ['1', '', '2']). The sep argument may consist of multiple characters as a single delimiter (to split with multiple delimiters, use re.split()). Splitting an empty string with a specified separator returns [''].

Ad esempio:

>>> '1,2,3'.split(',')
['1', '2', '3']
>>> '1,2,3'.split(',', maxsplit=1)
['1', '2,3']
>>> '1,2,,3,'.split(',')
['1', '2', '', '3', '']
>>> '1<>2<>3<4'.split('<>')
['1', '2', '3<4']

Se sep non è specificato o è None, viene applicato un algoritmo di divisione diverso: sequenze di spazi bianchi consecutivi sono considerate come un unico separatore, e il risultato non conterrà stringhe vuote all’inizio o alla fine se la stringa ha spazi bianchi iniziali o finali. Di conseguenza, dividendo una stringa vuota o una stringa composta solo di spazi bianchi con un separatore None si ottiene [].

Ad esempio:

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

Restituisce un elenco delle righe nella stringa, suddividendo alle linee di demarcazione. Le interruzioni di linea non sono incluse nell’elenco risultante a meno che keepends non sia dato e vero.

Questo metodo divide sulle seguenti linee di demarcazione. In particolare, i confini sono un sovrainsieme delle universal newlines.

Rappresentazione	Descrizione
\n	Line Feed
\r	Carriage Return
\r\n	Carriage Return + Line Feed
\v o \x0b	Line Tabulation
\f o \x0c	Form Feed
\x1c	File Separator
\x1d	Group Separator
\x1e	Record Separator
\x85	Codice di controllo C1 «Next Line»
\u2028	Separatore di riga
\u2029	Separatore di paragrafo

Cambiato nella versione 3.2: \v e \f aggiunti all’elenco dei limiti di riga.

Ad esempio:

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

A differenza del metodo split() quando viene fornita una stringa delimitatore sep, questo metodo restituisce una lista vuota per la stringa vuota e un’interruzione di riga terminale non comporta una linea aggiuntiva:

>>> "".splitlines()
[]
>>> "One line\n".splitlines()
['One line']

Per confronto, split('\n') restituisce:

>>> ''.split('\n')
['']
>>> 'Two lines\n'.split('\n')
['Two lines', '']

str.startswith(prefix[, start[, end]])

Restituisce True se la stringa inizia con il prefisso, altrimenti restituisce False. prefix può essere anche una tupla di prefissi da cercare. Con start opzionale, testa la stringa iniziando da quella posizione. Con end opzionale, smette di confrontare la stringa in quella posizione.

str.strip([chars])

Restituisce una copia della stringa con i caratteri iniziali e finali rimossi. L’argomento chars è una stringa che specifica l’insieme dei caratteri da rimuovere. Se omesso o None, l’argomento chars predefinisce la rimozione degli spazi bianchi. L’argomento chars non è un prefisso o un suffisso; piuttosto, tutte le combinazioni dei suoi valori vengono eliminate:

>>> '   spacious   '.strip()
'spacious'
>>> 'www.example.com'.strip('cmowz.')
'example'

I valori esterni iniziali e finali dell’argomento chars vengono rimossi dalla stringa. I caratteri vengono rimossi dall’inizio fino a raggiungere un carattere della stringa che non è contenuto nel set di caratteri in chars. Un’azione simile avviene alla fine. Per esempio:

>>> comment_string = '#....... Section 3.2.1 Issue #32 .......'
>>> comment_string.strip('.#! ')
'Section 3.2.1 Issue #32'

str.swapcase()

Restituisce una copia della stringa con i caratteri maiuscoli convertiti in minuscoli e viceversa. Nota che non è necessariamente vero che s.swapcase().swapcase() == s.

str.title()

Restituisce una versione della stringa con iniziali maiuscole, dove le parole iniziano con un carattere maiuscolo e i caratteri rimanenti sono minuscoli.

Ad esempio:

>>> 'Hello world'.title()
'Hello World'

L’algoritmo utilizza una semplice definizione indipendente dalla lingua di una parola come gruppi di lettere consecutive. La definizione funziona in molti contesti, ma ciò significa che gli apostrofi nelle contrazioni e nei possessivi formano confini di parola, il che potrebbe non essere il risultato desiderato:

>>> "they're bill's friends from the UK".title()
"They'Re Bill'S Friends From The Uk"

La funzione string.capwords() non ha questo problema, poiché divide le parole solo sugli spazi.

In alternativa, è possibile costruire una soluzione per gli apostrofi utilizzando le espressioni regolari:

>>> import re
>>> def titlecase(s):
...     return re.sub(r"[A-Za-z]+('[A-Za-z]+)?",
...                   lambda mo: mo.group(0).capitalize(),
...                   s)
...
>>> titlecase("they're bill's friends.")
"They're Bill's Friends."

str.translate(table)

Restituisce una copia della stringa in cui ciascun carattere è stato mappato attraverso la tabella di traduzione fornita. La tabella deve essere un oggetto che implementa l’indicizzazione tramite __getitem__(), tipicamente un mapping o una sequence. Quando indicizzato tramite un ordinale Unicode (un intero), l’oggetto tabella può fare una delle seguenti azioni: restituire un ordinale Unicode o una stringa, per mappare il carattere a uno o più altri caratteri; restituire None, per eliminare il carattere dalla stringa di ritorno; o lanciare un’eccezione LookupError, per mappare il carattere a se stesso.

Puoi usare str.maketrans() per creare una mappa di traduzione da mappature carattere-a-carattere in diversi formati.

Vedi anche il modulo codecs per un approccio più flessibile alle mappature personalizzate dei caratteri.

str.upper()

Restituisce una copia della stringa con tutti i caratteri [4] in maiuscolo convertiti in maiuscolo. Nota che s.upper().isupper() potrebbe essere False se s contiene caratteri non maiuscoli o se la categoria Unicode dei caratteri risultanti non è «Lu» (Lettera, maiuscolo), ma ad esempio «Lt» (Lettera, titolo).

L’algoritmo di conversione in maiuscolo usato è descritto nella sezione 3.13 “Default Case Folding” dello Standard Unicode.

str.zfill(width)

Restituisce una copia della stringa riempita a sinistra con cifre ASCII '0' per fare una stringa della lunghezza width. Un prefisso di segno principale ('+'/'-') viene gestito inserendo il padding dopo il carattere del segno piuttosto che prima. La stringa originale viene restituita se width è minore o uguale a len(s).

Ad esempio:

>>> "42".zfill(5)
'00042'
>>> "-42".zfill(5)
'-0042'

Formattazione delle stringhe in stile printf

Nota

Le operazioni di formattazione descritte qui mostrano una varietà di caratteristiche particolari che portano a numerosi errori comuni (come il fallimento nel visualizzare correttamente tuple e dizionari). Utilizzare le più recenti stringhe letterali formattate, l’interfaccia str.format(), o stringhe template potrebbe aiutare a evitare questi errori. Ciascuna di queste alternative offre i propri compromessi e vantaggi di semplicità, flessibilità e/o estensibilità.

Gli oggetti stringa hanno un’unica operazione built-in: l’operatore % (modulo). Questo è anche conosciuto come operatore di formattazione o interpolazione delle stringhe. Dato format % values (dove format è una stringa), le specifiche di conversione % in format vengono sostituite con zero o più elementi di values. L’effetto è simile all’uso della sprintf() nel linguaggio C.

Se format richiede un singolo argomento, values può essere un singolo oggetto che non è una tupla. [5] Altrimenti, values deve essere una tupla con esattamente il numero di elementi specificati dalla stringa di formattazione, o un singolo oggetto di mappatura (ad esempio, un dizionario).

Uno specificatore di conversione contiene due o più caratteri e ha i seguenti componenti, che devono apparire in questo ordine:

1. Il carattere '%', che segna l’inizio dello specificatore.

2. Chiave di mappatura (opzionale), costituita da una sequenza tra parentesi di caratteri (ad esempio, (somename)).

3. Flag di conversione (opzionali), che influiscono sul risultato di alcuni tipi di conversione.

4. Larghezza minima del campo (opzionale). Se specificata come '*' (asterisco), la larghezza effettiva viene letta dal prossimo elemento della tupla in values, e l’oggetto da convertire viene dopo la larghezza minima del campo e la precisione opzionale.

5. Precisione (opzionale), data come '.' (punto) seguita dalla precisione. Se specificata come '*' (un asterisco), la precisione effettiva viene letta dal prossimo elemento della tupla in values, e il valore da convertire viene dopo la precisione.

6. Modificatore di lunghezza (opzionale).

7. Tipo di conversione.

Quando l’argomento di destra è un dizionario (o un altro tipo di mappatura), i formati nella stringa devono includere una chiave di mappatura tra parentesi in quel dizionario inserita immediatamente dopo il carattere '%'. La chiave di mappatura seleziona il valore da formattare dalla mappatura. Ad esempio:

>>> print('%(language)s has %(number)03d quote types.' %
...       {'language': "Python", "number": 2})
Python has 002 quote types.

In questo caso non possono comparire specificatori * in un formato (poiché richiedono un elenco di parametri sequenziale).

I caratteri di flag di conversione sono:

Flag	Significato
'#'	La conversione del valore utilizzerà la «forma alternativa» (dove definita di seguito).
'0'	La conversione sarà riempita di zeri per i valori numerici.
'-'	Il valore convertito è allineato a sinistra (sovrascrive la conversione '0' se entrambi sono forniti).
' '	(uno spazio) Uno spazio vuoto dovrebbe essere lasciato prima di un numero positivo (o stringa vuota) prodotto da una conversione con segno.
'+'	Un carattere di segno ('+' o '-') precederà la conversione (sovrascrive un flag «spazio»).

Un modificatore di lunghezza (h, l, o L) può essere presente, ma viene ignorato poiché non è necessario per Python – quindi ad esempio %ld è identico a %d.

I tipi di conversione sono:

Conversione	Significato	Note
'd'	Intero con segno decimale.
'i'	Intero con segno decimale.
'o'	Valore ottale con segno.	(1)
'u'	Tipo obsoleto – è identico a 'd'.	(6)
'x'	Esadecimale con segno (minuscolo).	(2)
'X'	Esadecimale con segno (maiuscolo).	(2)
'e'	Floating-point exponential format (lowercase).	(3)
'E'	Floating-point exponential format (uppercase).	(3)
'f'	Floating-point decimal format.	(3)
'F'	Floating-point decimal format.	(3)
'g'	Floating-point format. Uses lowercase exponential format if exponent is less than -4 or not less than precision, decimal format otherwise.	(4)
'G'	Floating-point format. Uses uppercase exponential format if exponent is less than -4 or not less than precision, decimal format otherwise.	(4)
'c'	Singolo carattere (accetta un intero o una stringa di un singolo carattere).
'r'	Stringa (converte qualsiasi oggetto Python usando repr()).	(5)
's'	Stringa (converte qualsiasi oggetto Python usando str()).	(5)
'a'	Stringa (converte qualsiasi oggetto Python usando ascii()).	(5)
'%'	Nessun argomento viene convertito, il risultato è un carattere '%' nel risultato.

Note:

1. La forma alternativa fa sì che venga inserito un prefisso ottale ('0o') prima della prima cifra.

2. La forma alternativa fa sì che venga inserito un prefisso '0x' o '0X' (a seconda che sia stato usato il formato 'x' o 'X') prima della prima cifra.

3. La forma alternativa fa sì che il risultato contenga sempre un punto decimale, anche se non ci sono cifre che seguono.

   La precisione determina il numero di cifre dopo il punto decimale e il valore predefinito è 6.

4. La forma alternativa fa sì che il risultato contenga sempre un punto decimale e gli zeri finali non vengono rimossi come avverrebbe altrimenti.

   La precisione determina il numero di cifre significative prima e dopo il punto decimale e il valore predefinito è 6.

5. Se la precisione è N, l’output è troncato a N caratteri.

6. Vedi PEP 237.

Poiché le stringhe Python hanno una lunghezza esplicita, le conversioni %s non assumono che '\0' sia la fine della stringa.

Cambiato nella versione 3.1: Le conversioni %f per i numeri il cui valore assoluto è superiore a 1e50 non vengono più sostituite dalle conversioni %g.

Tipi di sequenze binarie — bytes, bytearray, memoryview

I tipi incorporati principali per manipolare i dati binari sono bytes e bytearray. Sono supportati da memoryview che utilizza il protocollo buffer per accedere alla memoria di altri oggetti binari senza necessità di fare una copia.

Il modulo array supporta l’archiviazione efficiente di tipi di dati di base come interi a 32 bit e valori a virgola mobile a doppia precisione IEEE754.

Oggetti bytes

Gli oggetti bytes sono sequenze immutabili di singoli byte. Poiché molti protocolli binari principali sono basati sulla codifica del testo ASCII, gli oggetti bytes offrono diversi metodi validi solo quando si lavora con dati compatibili con ASCII e sono strettamente correlati agli oggetti stringa in vari altri modi.

class bytes([source[, encoding[, errors]]])

In primo luogo, la sintassi per i letterali bytes è sostanzialmente la stessa di quella per i letterali stringa, tranne per il fatto che viene aggiunto un prefisso b:

• Virgolette singole: b'still allows embedded "double" quotes'

• Virgolette doppie: b"still allows embedded 'single' quotes"

• Virgolette triple: b'''3 single quotes''', b"""3 double quotes"""

Sono permessi solo caratteri ASCII nei letterali bytes (indipendentemente dalla codifica dichiarata del codice sorgente). Qualsiasi valore binario superiore a 127 deve essere inserito nei letterali bytes usando la sequenza di escape appropriata.

Come per i letterali stringa, i letterali bytes possono anche usare il prefisso r per disabilitare l’elaborazione delle sequenze di escape. Vedi String and Bytes literals per maggiori informazioni sulle varie forme di letterali bytes, comprese le sequenze di escape supportate.

Sebbene i letterali bytes e le loro rappresentazioni si basino sul testo ASCII, gli oggetti bytes si comportano effettivamente come sequenze immutabili di interi, con ciascun valore nella sequenza limitato in modo tale che 0 <= x < 256 (i tentativi di violare questa restrizione attiveranno ValueError). Questo viene fatto deliberatamente per enfatizzare che, sebbene molti formati binari includano elementi basati su ASCII e possano essere utilmente manipolati con alcuni algoritmi orientati al testo, questo non è generalmente il caso per dati binari arbitrari (applicare ciecamente algoritmi di elaborazione del testo a formati di dati binari non compatibili con ASCII di solito porta a corruzione dei dati).

Oltre alle forme letterali, gli oggetti bytes possono essere creati in diversi altri modi:

• Un oggetto bytes riempito di zeri di una lunghezza specificata: bytes(10)

• Da un iterable di interi: bytes(range(20))

• Copiando dati binari esistenti tramite il protocollo buffer: bytes(obj)

Vedi anche il built-in bytes.

Poiché 2 cifre esadecimali corrispondono esattamente a un singolo byte, i numeri esadecimali sono un formato comunemente usato per descrivere i dati binari. Di conseguenza, il tipo bytes ha un metodo di classe aggiuntivo per leggere i dati in tale formato:

classmethod fromhex(string)

Questo metodo di classe bytes restituisce un oggetto bytes, decodificando il dato oggetto stringa. La stringa deve contenere due cifre esadecimali per byte, e gli spazi bianchi ASCII vengono ignorati.

>>> bytes.fromhex('2Ef0 F1f2  ')
b'.\xf0\xf1\xf2'

Cambiato nella versione 3.7: bytes.fromhex() ora salta tutti gli spazi bianchi ASCII nella stringa, non solo gli spazi.

Esiste una funzione di conversione inversa per trasformare un oggetto bytes nella sua rappresentazione esadecimale.

hex([sep[, bytes_per_sep]])

Restituisce un oggetto stringa contenente due cifre esadecimali per ogni byte nell’istanza.

>>> b'\xf0\xf1\xf2'.hex()
'f0f1f2'

Se vuoi rendere la stringa esadecimale più leggibile, puoi specificare un parametro separatore sep per includere un singolo carattere nell’output. Per impostazione predefinita, questo separatore verrà incluso tra ogni byte. Un secondo parametro opzionale bytes_per_sep controlla la spaziatura. I valori positivi calcolano la posizione del separatore da destra, i valori negativi da sinistra.

>>> value = b'\xf0\xf1\xf2'
>>> value.hex('-')
'f0-f1-f2'
>>> value.hex('_', 2)
'f0_f1f2'
>>> b'UUDDLRLRAB'.hex(' ', -4)
'55554444 4c524c52 4142'

Added in version 3.5.

Cambiato nella versione 3.8: bytes.hex() ora supporta i parametri opzionali sep e bytes_per_sep per inserire separatori tra i byte nell’output esadecimale.

Poiché gli oggetti bytes sono sequenze di interi (simili a una tupla), per un oggetto bytes b, b[0] sarà un intero, mentre b[0:1] sarà un oggetto bytes di lunghezza 1. (Questo contrasta con le stringhe di testo, dove sia l’indicizzazione che il slicing produrranno una stringa di lunghezza 1)

La rappresentazione degli oggetti bytes usa il formato letterale (b'...') poiché è spesso più utile di, ad esempio, bytes([46, 46, 46]). Puoi sempre convertire un oggetto bytes in una lista di interi usando list(b).

Oggetti Bytearray

Gli oggetti bytearray sono una controparte mutabile degli oggetti bytes.

class bytearray([source[, encoding[, errors]]])

Non esiste una sintassi letterale dedicata per gli oggetti bytearray, essi vengono sempre creati chiamando il costruttore:

• Creazione di un’istanza vuota: bytearray()

• Creazione di un’istanza riempita di zeri con una lunghezza data: bytearray(10)

• Da un iterable di interi: bytearray(range(20))

• Copiando dati binari esistenti tramite il protocollo buffer: bytearray(b'Hi!')

Poiché gli oggetti bytearray sono mutabili, supportano le operazioni di sequenza mutable oltre alle comuni operazioni bytes e bytearray descritte in Operazioni su Bytes e Bytearray.

Vedi anche il built-in bytearray.

Poiché 2 cifre esadecimali corrispondono esattamente a un singolo byte, i numeri esadecimali sono un formato comunemente usato per descrivere i dati binari. Di conseguenza, il tipo bytearray ha un metodo di classe aggiuntivo per leggere i dati in tale formato:

classmethod fromhex(string)

Questo metodo di classe bytearray restituisce un oggetto bytearray, decodificando il dato oggetto stringa. La stringa deve contenere due cifre esadecimali per byte, e gli spazi bianchi ASCII vengono ignorati.

>>> bytearray.fromhex('2Ef0 F1f2  ')
bytearray(b'.\xf0\xf1\xf2')

Cambiato nella versione 3.7: bytearray.fromhex() ora salta tutti gli spazi bianchi ASCII nella stringa, non solo gli spazi.

Esiste una funzione di conversione inversa per trasformare un oggetto bytearray nella sua rappresentazione esadecimale.

hex([sep[, bytes_per_sep]])

Restituisce un oggetto stringa contenente due cifre esadecimali per ogni byte nell’istanza.

>>> bytearray(b'\xf0\xf1\xf2').hex()
'f0f1f2'

Added in version 3.5.

Cambiato nella versione 3.8: Simile a bytes.hex(), bytearray.hex() ora supporta i parametri opzionali sep e bytes_per_sep per inserire separatori tra i byte nell’output esadecimale.

Poiché gli oggetti bytearray sono sequenze di interi (simili a una lista), per un oggetto bytearray b, b[0] sarà un intero, mentre b[0:1] sarà un oggetto bytearray di lunghezza 1. (Questo contrasta con le stringhe di testo, dove sia l’indicizzazione che il slicing produrranno una stringa di lunghezza 1)

La rappresentazione degli oggetti bytearray usa il formato letterale bytes (bytearray(b'...')) poiché è spesso più utile di, ad esempio, bytearray([46, 46, 46]). Puoi sempre convertire un oggetto bytearray in una lista di interi usando list(b).

Operazioni su Bytes e Bytearray

Sia gli oggetti bytes che bytearray supportano le operazioni di sequenza common. Essi interoperano non solo con operandi dello stesso tipo, ma con qualsiasi bytes-like object. Grazie a questa flessibilità, possono essere liberamente mescolati nelle operazioni senza causare errori. Tuttavia, il tipo restituito del risultato può dipendere dall’ordine degli operandi.

Nota

I metodi sugli oggetti bytes e bytearray non accettano stringhe come argomenti, così come i metodi sulle stringhe non accettano bytes come argomenti. Ad esempio, devi scrivere:

a = "abc"
b = a.replace("a", "f")

e:

a = b"abc"
b = a.replace(b"a", b"f")

Alcune operazioni su bytes e bytearray presumono l’uso di formati binari compatibili con ASCII e, pertanto, dovrebbero essere evitate quando si lavora con dati binari arbitrari. Queste restrizioni sono trattate di seguito.

Nota

Utilizzare queste operazioni basate su ASCII per manipolare dati binari che non sono memorizzati in un formato basato su ASCII può portare a corruzione dei dati.

I seguenti metodi sugli oggetti bytes e bytearray possono essere utilizzati con dati binari arbitrari.

bytes.count(sub[, start[, end]])

bytearray.count(sub[, start[, end]])

Restituisce il numero di occorrenze non sovrapposte della sottosequenza sub nell’intervallo [start, end]. Gli argomenti opzionali start e end sono interpretati come nella notazione di slice.

La sottosequenza da cercare può essere qualsiasi bytes-like object o un intero nell’intervallo da 0 a 255.

Se sub è vuoto, restituisce il numero di slice vuoti tra i caratteri che è la lunghezza dell’oggetto bytes più uno.

Cambiato nella versione 3.3: Accetta anche un intero nell’intervallo da 0 a 255 come sottosequenza.

bytes.removeprefix(prefix, /)

bytearray.removeprefix(prefix, /)

Se i dati binari iniziano con la stringa prefix, restituisce bytes[len(prefix):]. Altrimenti, restituisce una copia dei dati binari originali:

>>> b'TestHook'.removeprefix(b'Test')
b'Hook'
>>> b'BaseTestCase'.removeprefix(b'Test')
b'BaseTestCase'

Il prefix può essere qualsiasi bytes-like object.

Nota

La versione di questo metodo per bytearray non opera in place - produce sempre un nuovo oggetto, anche se non sono state apportate modifiche.

Added in version 3.9.

bytes.removesuffix(suffix, /)

bytearray.removesuffix(suffix, /)

Se i dati binari terminano con la stringa suffix e questo suffix non è vuoto, ritorna bytes[:-len(suffix)]. Altrimenti, ritorna una copia dei dati binari originali:

>>> b'MiscTests'.removesuffix(b'Tests')
b'Misc'
>>> b'TmpDirMixin'.removesuffix(b'Tests')
b'TmpDirMixin'

Il suffix può essere qualsiasi oggetto simile a bytes.

Nota

La versione di questo metodo per bytearray non opera in place - produce sempre un nuovo oggetto, anche se non sono state apportate modifiche.

Added in version 3.9.

bytes.decode(encoding='utf-8', errors='strict')

bytearray.decode(encoding='utf-8', errors='strict')

Restituisce i bytes decodificati in una str.

encoding di default è 'utf-8'; vedere Standard Encodings per i valori possibili.

errors controlla come vengono gestiti gli errori di decodifica. Se 'strict' (il valore predefinito), viene sollevata un’eccezione UnicodeError. Altri valori possibili sono 'ignore', 'replace', e qualsiasi altro nome registrato tramite codecs.register_error(). Vedi Error Handlers per i dettagli.

Per ragioni di prestazioni, il valore di errors non viene verificato per validità a meno che non si verifichi effettivamente un errore di decodifica, sia abilitato Python Development Mode o venga utilizzata una build di debug.

Nota

Passare l’argomento encoding a str permette di decodificare qualsiasi oggetto simile a bytes direttamente, senza dover creare un oggetto temporaneo bytes o bytearray.

Cambiato nella versione 3.1: Aggiunto supporto per argomenti di tipo keyword.

Cambiato nella versione 3.9: Il valore dell’argomento errors ora viene controllato in Python Development Mode e in modalità di debug.

bytes.endswith(suffix[, start[, end]])

bytearray.endswith(suffix[, start[, end]])

Restituisce True se i dati binari terminano con il suffix specificato, altrimenti restituisce False. suffix può essere anche una tupla di suffissi da cercare. Con start opzionale, il test inizia a quella posizione. Con end opzionale, smette di confrontare a quella posizione.

Il/i suffisso/i da cercare possono essere qualsiasi oggetto simile a bytes.

bytes.find(sub[, start[, end]])

bytearray.find(sub[, start[, end]])

Restituisce l’indice più basso nei dati dove si trova la sottosequenza sub, tale che sub sia contenuto nella slice s[start:end]. Gli argomenti opzionali start e end sono interpretati come nella notazione delle slice. Restituisce -1 se sub non viene trovato.

La sottosequenza da cercare può essere qualsiasi bytes-like object o un intero nell’intervallo da 0 a 255.

Nota

Il metodo find() dovrebbe essere utilizzato solo se hai bisogno di conoscere la posizione di sub. Per verificare se sub è una sottostringa o no, usa l’operatore in:

>>> b'Py' in b'Python'
True

Cambiato nella versione 3.3: Accetta anche un intero nell’intervallo da 0 a 255 come sottosequenza.

bytes.index(sub[, start[, end]])

bytearray.index(sub[, start[, end]])

Come find(), ma solleva ValueError quando la sottosequenza non viene trovata.

La sottosequenza da cercare può essere qualsiasi bytes-like object o un intero nell’intervallo da 0 a 255.

Cambiato nella versione 3.3: Accetta anche un intero nell’intervallo da 0 a 255 come sottosequenza.

bytes.join(iterable)

bytearray.join(iterable)

Restituisce un oggetto bytes o bytearray che è la concatenazione delle sequenze di dati binari in iterable. Verrà sollevata una TypeError se ci sono valori in iterable che non sono oggetti simili a bytes, inclusi gli oggetti str. Il separatore tra gli elementi è il contenuto dell’oggetto bytes o bytearray che fornisce questo metodo.

static bytes.maketrans(from, to)

static bytearray.maketrans(from, to)

Questo metodo statico restituisce una tabella di traduzione utilizzabile per bytes.translate() che mapperà ciascun carattere in from nel carattere nella stessa posizione in to; from e to devono essere entrambi oggetti simili a bytes e avere la stessa lunghezza.

Added in version 3.1.

bytes.partition(sep)

bytearray.partition(sep)

Divide la sequenza alla prima occorrenza di sep, e restituisce una tupla a 3 elementi contenente la parte prima del separatore, il separatore stesso o la sua copia bytearray, e la parte dopo il separatore. Se il separatore non viene trovato, restituisce una tupla a 3 elementi contenente una copia della sequenza originale, seguita da due oggetti vuoti bytes o bytearray.

Il separatore da cercare può essere qualsiasi oggetto simile a bytes.

bytes.replace(old, new[, count])

bytearray.replace(old, new[, count])

Restituisce una copia della sequenza con tutte le occorrenze della sottosequenza old sostituite da new. Se viene specificato l’argomento opzionale count, vengono sostituite solo le prime count occorrenze.

La sottosequenza da cercare e la sua sostituzione possono essere qualsiasi oggetto simile a bytes.

Nota

La versione di questo metodo per bytearray non opera in place - produce sempre un nuovo oggetto, anche se non sono state apportate modifiche.

bytes.rfind(sub[, start[, end]])

bytearray.rfind(sub[, start[, end]])

Restituisce l’indice più alto nella sequenza dove si trova la sottosequenza sub, tale che sub sia contenuto in s[start:end]. Gli argomenti opzionali start e end sono interpretati come nella notazione delle slice. Restituisce -1 in caso di fallimento.

La sottosequenza da cercare può essere qualsiasi bytes-like object o un intero nell’intervallo da 0 a 255.

Cambiato nella versione 3.3: Accetta anche un intero nell’intervallo da 0 a 255 come sottosequenza.

bytes.rindex(sub[, start[, end]])

bytearray.rindex(sub[, start[, end]])

Come rfind() ma solleva ValueError quando la sottosequenza sub non viene trovata.

La sottosequenza da cercare può essere qualsiasi bytes-like object o un intero nell’intervallo da 0 a 255.

Cambiato nella versione 3.3: Accetta anche un intero nell’intervallo da 0 a 255 come sottosequenza.

bytes.rpartition(sep)

bytearray.rpartition(sep)

Divide la sequenza all’ultima occorrenza di sep, e restituisce una tupla a 3 elementi contenente la parte prima del separatore, il separatore stesso o la sua copia bytearray, e la parte dopo il separatore. Se il separatore non viene trovato, restituisce una tupla a 3 elementi contenente due oggetti vuoti bytes o bytearray, seguiti da una copia della sequenza originale.

Il separatore da cercare può essere qualsiasi oggetto simile a bytes.

bytes.startswith(prefix[, start[, end]])

bytearray.startswith(prefix[, start[, end]])

Restituisce True se i dati binari iniziano con il prefix specificato, altrimenti restituisce False. prefix può essere anche una tupla di prefissi da cercare. Con start opzionale, il test inizia a quella posizione. Con end opzionale, smette di confrontare a quella posizione.

Il/i prefisso/i da cercare possono essere qualsiasi oggetto simile a bytes.

bytes.translate(table, /, delete=b'')

bytearray.translate(table, /, delete=b'')

Restituisce una copia dell’oggetto bytes o bytearray dove tutti i bytes presenti nell’argomento opzionale delete sono stati rimossi, e i bytes rimanenti sono stati mappati attraverso la tabella di traduzione data, che deve essere un oggetto bytes di lunghezza 256.

Puoi usare il metodo bytes.maketrans() per creare una tabella di traduzione.

Imposta l’argomento table su None per traduzioni che eliminano solo i caratteri:

>>> b'read this short text'.translate(None, b'aeiou')
b'rd ths shrt txt'

Cambiato nella versione 3.6: delete ora è supportato come argomento keyword.

I seguenti metodi su oggetti bytes e bytearray hanno comportamenti predefiniti che assumono l’uso di formati binari compatibili con ASCII, ma possono essere comunque utilizzati con dati binari arbitrari passando argomenti appropriati. Nota che tutti i metodi bytearray in questa sezione non operano in place, e invece producono nuovi oggetti.

bytes.center(width[, fillbyte])

bytearray.center(width[, fillbyte])

Restituisce una copia dell’oggetto centrato in una sequenza di lunghezza width. L’imbottitura viene fatta usando il fillbyte specificato (il predefinito è uno spazio ASCII). Per oggetti bytes, la sequenza originale viene restituita se width è minore o uguale a len(s).

Nota

La versione di questo metodo per bytearray non opera in place - produce sempre un nuovo oggetto, anche se non sono state apportate modifiche.

bytes.ljust(width[, fillbyte])

bytearray.ljust(width[, fillbyte])

Restituisce una copia dell’oggetto giustificato a sinistra in una sequenza di lunghezza width. L’imbottitura viene fatta usando il fillbyte specificato (il predefinito è uno spazio ASCII). Per oggetti bytes, la sequenza originale viene restituita se width è minore o uguale a len(s).

Nota

La versione di questo metodo per bytearray non opera in place - produce sempre un nuovo oggetto, anche se non sono state apportate modifiche.

bytes.lstrip([chars])

bytearray.lstrip([chars])

Restituisce una copia della sequenza con i bytes iniziali specificati rimossi. L’argomento chars è una sequenza binaria che specifica il set di valori dei byte da rimuovere - il nome si riferisce al fatto che questo metodo è solitamente usato con caratteri ASCII. Se omesso o None, l’argomento chars predefinito è rimuovere gli spazi bianchi ASCII. L’argomento chars non è un prefisso; piuttosto, tutte le combinazioni dei suoi valori vengono rimosse:

>>> b'   spacious   '.lstrip()
b'spacious   '
>>> b'www.example.com'.lstrip(b'cmowz.')
b'example.com'

La sequenza binaria di valori byte da rimuovere può essere qualsiasi oggetto simile a bytes. Vedi removeprefix() per un metodo che rimuoverà una singola stringa prefisso anziché tutti i caratteri di un set. Ad esempio:

>>> b'Arthur: three!'.lstrip(b'Arthur: ')
b'ee!'
>>> b'Arthur: three!'.removeprefix(b'Arthur: ')
b'three!'

Nota

La versione di questo metodo per bytearray non opera in place - produce sempre un nuovo oggetto, anche se non sono state apportate modifiche.

bytes.rjust(width[, fillbyte])

bytearray.rjust(width[, fillbyte])

Restituisce una copia dell’oggetto giustificato a destra in una sequenza di lunghezza width. L’imbottitura viene fatta usando il fillbyte specificato (il predefinito è uno spazio ASCII). Per oggetti bytes, la sequenza originale viene restituita se width è minore o uguale a len(s).

Nota

La versione di questo metodo per bytearray non opera in place - produce sempre un nuovo oggetto, anche se non sono state apportate modifiche.

bytes.rsplit(sep=None, maxsplit=-1)

bytearray.rsplit(sep=None, maxsplit=-1)

Divide la sequenza binaria in sottosequenze dello stesso tipo, usando sep come stringa delimitatore. Se viene specificato maxsplit, vengono effettuate al massimo maxsplit divisioni, le ultime. Se sep non è specificato o è None, qualsiasi sottosequenza costituita esclusivamente da spazi bianchi ASCII è un separatore. A parte per la divisione da destra, rsplit() si comporta come split() che è descritto in dettaglio di seguito.

bytes.rstrip([chars])

bytearray.rstrip([chars])

Restituisce una copia della sequenza con i bytes finali specificati rimossi. L’argomento chars è una sequenza binaria che specifica il set di valori dei byte da rimuovere - il nome si riferisce al fatto che questo metodo è solitamente usato con caratteri ASCII. Se omesso o None, l’argomento chars predefinito è rimuovere gli spazi bianchi ASCII. L’argomento chars non è un suffisso; piuttosto, tutte le combinazioni dei suoi valori vengono rimosse:

>>> b'   spacious   '.rstrip()
b'   spacious'
>>> b'mississippi'.rstrip(b'ipz')
b'mississ'

La sequenza binaria di valori byte da rimuovere può essere qualsiasi oggetto simile a bytes. Vedi removesuffix() per un metodo che rimuoverà una singola stringa suffisso anziché tutti i caratteri di un set. Ad esempio:

>>> b'Monty Python'.rstrip(b' Python')
b'M'
>>> b'Monty Python'.removesuffix(b' Python')
b'Monty'

Nota

La versione di questo metodo per bytearray non opera in place - produce sempre un nuovo oggetto, anche se non sono state apportate modifiche.

bytes.split(sep=None, maxsplit=-1)

bytearray.split(sep=None, maxsplit=-1)

Divide la sequenza binaria in sottosequenze dello stesso tipo, usando sep come stringa delimitatore. Se maxsplit è dato e non negativo, vengono effettuate al massimo maxsplit divisioni (quindi, la lista avrà al massimo maxsplit+1 elementi). Se maxsplit non è specificato o è -1, non c’è limite al numero di divisioni (vengono effettuate tutte le possibili divisioni).

If sep is given, consecutive delimiters are not grouped together and are deemed to delimit empty subsequences (for example, b'1,,2'.split(b',') returns [b'1', b'', b'2']). The sep argument may consist of a multibyte sequence as a single delimiter. Splitting an empty sequence with a specified separator returns [b''] or [bytearray(b'')] depending on the type of object being split. The sep argument may be any bytes-like object.

Ad esempio:

>>> 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'']
>>> b'1<>2<>3<4'.split(b'<>')
[b'1', b'2', b'3<4']

Se sep non è specificato o è None, viene applicato un diverso algoritmo di divisione: le sequenze di spazi bianchi ASCII consecutivi sono considerate come un singolo separatore, e il risultato non conterrà stringhe vuote all’inizio o alla fine se la sequenza ha spazi bianchi iniziali o finali. Pertanto, dividendo una sequenza vuota o una sequenza costituita esclusivamente da spazi bianchi ASCII senza un separatore specificato si ottiene [].

Ad esempio:

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

Restituisce una copia della sequenza con i bytes iniziali e finali specificati rimossi. L’argomento chars è una sequenza binaria che specifica il set di valori dei byte da rimuovere - il nome si riferisce al fatto che questo metodo è solitamente usato con caratteri ASCII. Se omesso o None, l’argomento chars predefinito è rimuovere gli spazi bianchi ASCII. L’argomento chars non è un prefisso o un suffisso; piuttosto, tutte le combinazioni dei suoi valori vengono rimosse:

>>> b'   spacious   '.strip()
b'spacious'
>>> b'www.example.com'.strip(b'cmowz.')
b'example'

La sequenza binaria di valori byte da rimuovere può essere qualsiasi oggetto simile a bytes.

Nota

La versione di questo metodo per bytearray non opera in place - produce sempre un nuovo oggetto, anche se non sono state apportate modifiche.

I seguenti metodi sugli oggetti bytes e bytearray assumono l’uso di formati binari compatibili con ASCII e non dovrebbero essere applicati a dati binari arbitrari. Nota che tutti i metodi bytearray in questa sezione non operano in place, e invece producono nuovi oggetti.

bytes.capitalize()

bytearray.capitalize()

Restituisce una copia della sequenza con ogni byte interpretato come un carattere ASCII, e il primo byte capitalizzato e il resto in minuscolo. I valori dei byte non ASCII vengono trasmessi senza modifiche.

Nota

La versione di questo metodo per bytearray non opera in place - produce sempre un nuovo oggetto, anche se non sono state apportate modifiche.

bytes.expandtabs(tabsize=8)

bytearray.expandtabs(tabsize=8)

Restituisce una copia della sequenza dove tutti i caratteri ASCII tab sono sostituiti da uno o più spazi ASCII, a seconda della colonna corrente e della dimensione del tab fornita. Le posizioni della tabulazione si verificano ogni tabsize byte (il valore predefinito è 8, dando le posizioni della tabulazione alle colonne 0, 8, 16 e così via). Per espandere la sequenza, la colonna corrente viene impostata a zero e la sequenza viene esaminata byte per byte. Se il byte è un carattere tabulazione ASCII (b'\t'), uno o più spazi vengono inseriti nel risultato fino a quando la colonna corrente è uguale alla prossima posizione di tabulazione. (Il carattere tabulazione stesso non viene copiato.) Se il byte corrente è una nuova riga ASCII (b'\n') o ritorno a capo (b'\r'), viene copiato e la colonna corrente viene reimpostata a zero. Qualsiasi altro valore di byte viene copiato senza modifiche e la colonna corrente viene incrementata di uno indipendentemente da come il valore del byte viene rappresentato quando viene stampato:

>>> b'01\t012\t0123\t01234'.expandtabs()
b'01      012     0123    01234'
>>> b'01\t012\t0123\t01234'.expandtabs(4)
b'01  012 0123    01234'

Nota

La versione di questo metodo per bytearray non opera in place - produce sempre un nuovo oggetto, anche se non sono state apportate modifiche.

bytes.isalnum()

bytearray.isalnum()

Restituisce True se tutti i byte nella sequenza sono caratteri alfabetici ASCII o cifre decimali ASCII e la sequenza non è vuota, False altrimenti. I caratteri alfabetici ASCII sono quei valori di byte nella sequenza b'abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ'. Le cifre decimali ASCII sono quei valori di byte nella sequenza b'0123456789'.

Ad esempio:

>>> b'ABCabc1'.isalnum()
True
>>> b'ABC abc1'.isalnum()
False

bytes.isalpha()

bytearray.isalpha()

Restituisce True se tutti i byte nella sequenza sono caratteri alfabetici ASCII e la sequenza non è vuota, False altrimenti. I caratteri alfabetici ASCII sono quei valori di byte nella sequenza b'abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ'.

Ad esempio:

>>> b'ABCabc'.isalpha()
True
>>> b'ABCabc1'.isalpha()
False

bytes.isascii()

bytearray.isascii()

Restituisce True se la sequenza è vuota o se tutti i byte nella sequenza sono ASCII, False altrimenti. I byte ASCII sono nell’intervallo 0-0x7F.

Added in version 3.7.

bytes.isdigit()

bytearray.isdigit()

Restituisce True se tutti i byte nella sequenza sono cifre decimali ASCII e la sequenza non è vuota, False altrimenti. Le cifre decimali ASCII sono quei valori di byte nella sequenza b'0123456789'.

Ad esempio:

>>> b'1234'.isdigit()
True
>>> b'1.23'.isdigit()
False

bytes.islower()

bytearray.islower()

Restituisce True se c’è almeno un carattere minuscolo ASCII nella sequenza e nessun carattere maiuscolo ASCII, False altrimenti.

Ad esempio:

>>> b'hello world'.islower()
True
>>> b'Hello world'.islower()
False

I caratteri minuscoli ASCII sono quei valori di byte nella sequenza b'abcdefghijklmnopqrstuvwxyz'. I caratteri maiuscoli ASCII sono quei valori di byte nella sequenza b'ABCDEFGHIJKLMNOPQRSTUVWXYZ'.

bytes.isspace()

bytearray.isspace()

Restituisce True se tutti i byte nella sequenza sono spazi bianchi ASCII e la sequenza non è vuota, False altrimenti. I caratteri di spazio bianco ASCII sono quei valori di byte nella sequenza b' \t\n\r\x0b\f' (spazio, tabulazione, nuova riga, ritorno a capo, tabulazione verticale, form feed).

bytes.istitle()

bytearray.istitle()

Restituisce True se la sequenza è in formato ASCII «titlecase» e la sequenza non è vuota, False altrimenti. Vedi bytes.title() per maggiori dettagli sulla definizione di «titlecase».

Ad esempio:

>>> b'Hello World'.istitle()
True
>>> b'Hello world'.istitle()
False

bytes.isupper()

bytearray.isupper()

Restituisce True se c’è almeno un carattere alfabetico ASCII maiuscolo nella sequenza e nessun carattere ASCII minuscolo, False altrimenti.

Ad esempio:

>>> b'HELLO WORLD'.isupper()
True
>>> b'Hello world'.isupper()
False

I caratteri minuscoli ASCII sono quei valori di byte nella sequenza b'abcdefghijklmnopqrstuvwxyz'. I caratteri maiuscoli ASCII sono quei valori di byte nella sequenza b'ABCDEFGHIJKLMNOPQRSTUVWXYZ'.

bytes.lower()

bytearray.lower()

Restituisce una copia della sequenza con tutti i caratteri ASCII maiuscoli convertiti nei loro corrispondenti caratteri minuscoli.

Ad esempio:

>>> b'Hello World'.lower()
b'hello world'

I caratteri minuscoli ASCII sono quei valori di byte nella sequenza b'abcdefghijklmnopqrstuvwxyz'. I caratteri maiuscoli ASCII sono quei valori di byte nella sequenza b'ABCDEFGHIJKLMNOPQRSTUVWXYZ'.

Nota

La versione di questo metodo per bytearray non opera in place - produce sempre un nuovo oggetto, anche se non sono state apportate modifiche.

bytes.splitlines(keepends=False)

bytearray.splitlines(keepends=False)

Restituisce un elenco delle linee nella sequenza binaria, suddividendo ai confini delle linee ASCII. Questo metodo utilizza l’approccio delle universal newlines per dividere le linee. Le interruzioni di linea non sono incluse nell’elenco risultante a meno che keepends non sia fornito e impostato su vero.

Ad esempio:

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

A differenza di split() quando viene dato un delimitatore di stringa sep, questo metodo restituisce un elenco vuoto per la stringa vuota, e un’interruzione di linea terminale non produce una linea extra:

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

Restituisce una copia della sequenza con tutti i caratteri ASCII minuscoli convertiti nei loro corrispondenti caratteri maiuscoli e viceversa.

Ad esempio:

>>> b'Hello World'.swapcase()
b'hELLO wORLD'

I caratteri minuscoli ASCII sono quei valori di byte nella sequenza b'abcdefghijklmnopqrstuvwxyz'. I caratteri maiuscoli ASCII sono quei valori di byte nella sequenza b'ABCDEFGHIJKLMNOPQRSTUVWXYZ'.

Unlike str.swapcase(), it is always the case that bin.swapcase().swapcase() == bin for the binary versions. Case conversions are symmetrical in ASCII, even though that is not generally true for arbitrary Unicode code points.

Nota

La versione di questo metodo per bytearray non opera in place - produce sempre un nuovo oggetto, anche se non sono state apportate modifiche.

bytes.title()

bytearray.title()

Restituisce una versione in formato «titlecase» della sequenza binaria in cui le parole iniziano con un carattere ASCII maiuscolo e i rimanenti caratteri sono minuscoli. I valori di byte senza distinzione di maiuscole e minuscole non vengono modificati.

Ad esempio:

>>> b'Hello world'.title()
b'Hello World'

I caratteri ASCII minuscoli sono quei valori di byte nella sequenza b'abcdefghijklmnopqrstuvwxyz'. I caratteri ASCII maiuscoli sono quei valori di byte nella sequenza b'ABCDEFGHIJKLMNOPQRSTUVWXYZ'. Tutti gli altri valori di byte sono senza distinzione di maiuscole e minuscole.

L’algoritmo utilizza una semplice definizione indipendente dalla lingua di una parola come gruppi di lettere consecutive. La definizione funziona in molti contesti, ma ciò significa che gli apostrofi nelle contrazioni e nei possessivi formano confini di parola, il che potrebbe non essere il risultato desiderato:

>>> b"they're bill's friends from the UK".title()
b"They'Re Bill'S Friends From The Uk"

Una soluzione alternativa per gli apostrofi può essere costruita utilizzando espressioni regolari:

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

Nota

La versione di questo metodo per bytearray non opera in place - produce sempre un nuovo oggetto, anche se non sono state apportate modifiche.

bytes.upper()

bytearray.upper()

Restituisce una copia della sequenza con tutti i caratteri ASCII minuscoli convertiti nei loro corrispondenti caratteri maiuscoli.

Ad esempio:

>>> b'Hello World'.upper()
b'HELLO WORLD'

I caratteri minuscoli ASCII sono quei valori di byte nella sequenza b'abcdefghijklmnopqrstuvwxyz'. I caratteri maiuscoli ASCII sono quei valori di byte nella sequenza b'ABCDEFGHIJKLMNOPQRSTUVWXYZ'.

Nota

La versione di questo metodo per bytearray non opera in place - produce sempre un nuovo oggetto, anche se non sono state apportate modifiche.

bytes.zfill(width)

bytearray.zfill(width)

Restituisce una copia della sequenza riempita a sinistra con i caratteri ASCII b'0' per creare una sequenza della lunghezza width. Un prefisso di segno principale (b'+'/ b'-') viene gestito inserendo il padding dopo il carattere del segno anziché prima. Per gli oggetti bytes, la sequenza originale viene restituita se width è inferiore o uguale a len(seq).

Ad esempio:

>>> b"42".zfill(5)
b'00042'
>>> b"-42".zfill(5)
b'-0042'

Nota

La versione di questo metodo per bytearray non opera in place - produce sempre un nuovo oggetto, anche se non sono state apportate modifiche.

Formattazione Bytes stile printf

Nota

Le operazioni di formattazione descritte qui mostrano una varietà di stranezze che portano a numerosi errori comuni (come la visualizzazione errata di tuple e dizionari). Se il valore da stampare potrebbe essere una tupla o un dizionario, racchiudilo in una tupla.

Gli oggetti Bytes (bytes/bytearray) hanno un’operazione integrata unica: l’operatore % (modulo). Questo è anche noto come operatore di formattazione o interpolazione dei bytes. Dato format % values (dove format è un oggetto bytes), le specifiche di conversione % in format sono sostituite con uno o più elementi di values. L’effetto è simile all’uso della funzione sprintf() nel linguaggio C.

Se format richiede un singolo argomento, values può essere un singolo oggetto non-tuple. [5] Altrimenti, values deve essere una tupla con esattamente il numero di elementi specificati dall’oggetto bytes di formato, o un singolo oggetto di mappatura (ad esempio, un dizionario).

Uno specificatore di conversione contiene due o più caratteri e ha i seguenti componenti, che devono apparire in questo ordine:

1. Il carattere '%', che segna l’inizio dello specificatore.

2. Chiave di mappatura (opzionale), costituita da una sequenza tra parentesi di caratteri (ad esempio, (somename)).

3. Flag di conversione (opzionali), che influiscono sul risultato di alcuni tipi di conversione.

4. Larghezza minima del campo (opzionale). Se specificata come '*' (asterisco), la larghezza effettiva viene letta dal prossimo elemento della tupla in values, e l’oggetto da convertire viene dopo la larghezza minima del campo e la precisione opzionale.

5. Precisione (opzionale), data come '.' (punto) seguita dalla precisione. Se specificata come '*' (un asterisco), la precisione effettiva viene letta dal prossimo elemento della tupla in values, e il valore da convertire viene dopo la precisione.

6. Modificatore di lunghezza (opzionale).

7. Tipo di conversione.

Quando l’argomento a destra è un dizionario (o un altro tipo di mappatura), allora i formati nell’oggetto bytes devono includere una chiave di mappatura tra parentesi in quel dizionario inserita immediatamente dopo il carattere '%'. La chiave di mappatura seleziona il valore da formattare dalla mappatura. Ad esempio:

>>> print(b'%(language)s has %(number)03d quote types.' %
...       {b'language': b"Python", b"number": 2})
b'Python has 002 quote types.'

In questo caso non possono comparire specificatori * in un formato (poiché richiedono un elenco di parametri sequenziale).

I caratteri di flag di conversione sono:

Flag	Significato
'#'	La conversione del valore utilizzerà la «forma alternativa» (dove definita di seguito).
'0'	La conversione sarà riempita di zeri per i valori numerici.
'-'	Il valore convertito è allineato a sinistra (sovrascrive la conversione '0' se entrambi sono forniti).
' '	(uno spazio) Uno spazio vuoto dovrebbe essere lasciato prima di un numero positivo (o stringa vuota) prodotto da una conversione con segno.
'+'	Un carattere di segno ('+' o '-') precederà la conversione (sovrascrive un flag «spazio»).

Un modificatore di lunghezza (h, l, o L) può essere presente, ma viene ignorato poiché non è necessario per Python – quindi ad esempio %ld è identico a %d.

I tipi di conversione sono:

Conversione	Significato	Note
'd'	Intero con segno decimale.
'i'	Intero con segno decimale.
'o'	Valore ottale con segno.	(1)
'u'	Tipo obsoleto – è identico a 'd'.	(8)
'x'	Esadecimale con segno (minuscolo).	(2)
'X'	Esadecimale con segno (maiuscolo).	(2)
'e'	Floating-point exponential format (lowercase).	(3)
'E'	Floating-point exponential format (uppercase).	(3)
'f'	Floating-point decimal format.	(3)
'F'	Floating-point decimal format.	(3)
'g'	Floating-point format. Uses lowercase exponential format if exponent is less than -4 or not less than precision, decimal format otherwise.	(4)
'G'	Floating-point format. Uses uppercase exponential format if exponent is less than -4 or not less than precision, decimal format otherwise.	(4)
'c'	Byte singolo (accetta oggetti interi o byte singoli).
'b'	Bytes (qualsiasi oggetto che segue il buffer protocol o ha __bytes__()).	(5)
's'	's' è un alias per 'b' e dovrebbe essere usato solo per basi di codice Python2/3.	(6)
'a'	Bytes (converte qualsiasi oggetto Python utilizzando repr(obj).encode('ascii', 'backslashreplace')).	(5)
'r'	'r' è un alias per 'a' e dovrebbe essere usato solo per basi di codice Python2/3.	(7)
'%'	Nessun argomento viene convertito, il risultato è un carattere '%' nel risultato.

Note:

1. La forma alternativa fa sì che venga inserito un prefisso ottale ('0o') prima della prima cifra.

2. La forma alternativa fa sì che venga inserito un prefisso '0x' o '0X' (a seconda che sia stato usato il formato 'x' o 'X') prima della prima cifra.

3. La forma alternativa fa sì che il risultato contenga sempre un punto decimale, anche se non ci sono cifre che seguono.

   La precisione determina il numero di cifre dopo il punto decimale e il valore predefinito è 6.

4. La forma alternativa fa sì che il risultato contenga sempre un punto decimale e gli zeri finali non vengono rimossi come avverrebbe altrimenti.

   La precisione determina il numero di cifre significative prima e dopo il punto decimale e il valore predefinito è 6.

5. Se la precisione è N, l’output è troncato a N caratteri.

6. b'%s' è deprecato, ma non verrà rimosso durante la serie 3.x.

7. b'%r' è deprecato, ma non verrà rimosso durante la serie 3.x.

8. Vedi PEP 237.

Nota

La versione di questo metodo per bytearray non opera in place - produce sempre un nuovo oggetto, anche se non sono state apportate modifiche.

Vedi anche

PEP 461 - Aggiunta della formattazione % a bytes e bytearray

Added in version 3.5.

Memory Views

Gli oggetti memoryview permettono al codice Python di accedere ai dati interni di un oggetto che supporta il buffer protocol senza copiarli.

class memoryview(object)

Crea un memoryview che fa riferimento a object. object deve supportare il buffer protocol. Gli oggetti integrati che supportano il buffer protocol includono bytes e bytearray.

Un memoryview ha la nozione di elemento, che è l’unità di memoria atomica gestita dall”object originario. Per molti tipi semplici come bytes e bytearray, un elemento è un byte singolo, ma altri tipi come array.array possono avere elementi più grandi.

len(view) è uguale alla lunghezza di tolist, che è la rappresentazione dell’elenco nidificato della vista. Se view.ndim = 1, questo è uguale al numero di elementi nella vista.

Cambiato nella versione 3.12: Se view.ndim == 0, len(view) ora solleva TypeError invece di restituire 1.

L’attributo itemsize ti fornirà il numero di byte in un singolo elemento.

Un memoryview supporta slicing e indicizzazioni per esporre i suoi dati. Lo slicing monodimensionale risulterà in una sotto-vista:

>>> v = memoryview(b'abcefg')
>>> v[1]
98
>>> v[-1]
103
>>> v[1:4]
<memory at 0x7f3ddc9f4350>
>>> bytes(v[1:4])
b'bce'

Se format è uno degli specificatori di formato nativi del modulo struct, l’indicizzazione con un intero o una tupla di interi è anche supportata e restituisce un singolo elemento con il tipo corretto. Le memoryview monodimensionali possono essere indicizzate con un intero o una tupla di un intero. Le memoryview multidimensionali possono essere indicizzate con tuple di esattamente ndim interi dove ndim è il numero di dimensioni. Le memoryview zero-dimensionali possono essere indicizzate con la tupla vuota.

Ecco un esempio con un formato non-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]

Se l’oggetto sottostante è scrivibile, la memoryview supporta l’assegnazione di slice monodimensionale. Non è permesso il ridimensionamento:

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

Le memoryview monodimensionali di tipi hashable (di sola lettura) con formati “B”, “b” o “c” sono anche hashable. L’hash è definito come 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

Cambiato nella versione 3.3: Le memoryview monodimensionali possono ora essere slice. Le memoryview monodimensionali con formati “B”, “b” o “c” sono ora hashable.

Cambiato nella versione 3.4: memoryview è ora registrato automaticamente con collections.abc.Sequence

Cambiato nella versione 3.5: le memoryview possono ora essere indicizzate con tuple di interi.

memoryview ha diversi metodi:

__eq__(exporter)

Una memoryview e un esportatore PEP 3118 sono uguali se le loro forme sono equivalenti e se tutti i valori corrispondenti sono uguali quando i rispettivi codici di formato degli operandi sono interpretati utilizzando la sintassi struct.

Per il sottoinsieme di stringhe di formato struct attualmente supportato da tolist(), v e w sono uguali se v.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

Se una delle stringhe di formato non è supportata dal modulo struct, allora gli oggetti saranno sempre considerati diversi (anche se le stringhe di formato e i contenuti del buffer sono identici):

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

Note that, as with floating-point numbers, v is w does not imply v == w for memoryview objects.

Cambiato nella versione 3.3: Le versioni precedenti confrontavano la memoria grezza senza considerare il formato degli elementi e la struttura dell’array logico.

tobytes(order='C')

Restituisce i dati nel buffer come una stringa di byte. Questo è equivalente a chiamare il costruttore bytes sulla memoryview.

>>> m = memoryview(b"abc")
>>> m.tobytes()
b'abc'
>>> bytes(m)
b'abc'

Per gli array non contigui il risultato è uguale alla rappresentazione dell’elenco appiattito con tutti gli elementi convertiti in byte. tobytes() supporta tutte le stringhe di formato, comprese quelle che non sono nella sintassi del modulo struct.

Added in version 3.8: order può essere {“C”, “F”, “A”}. Quando order è “C” o “F”, i dati dell’array originale sono convertiti in ordine C o Fortran. Per le viste contigue, “A” restituisce una copia esatta della memoria fisica. In particolare, l’ordine Fortran in memoria viene preservato. Per le viste non contigue, i dati sono prima convertiti in C. order=None è equivalente a order=”C”.

hex([sep[, bytes_per_sep]])

Restituisce un oggetto stringa contenente due cifre esadecimali per ogni byte nel buffer.

>>> m = memoryview(b"abc")
>>> m.hex()
'616263'

Added in version 3.5.

Cambiato nella versione 3.8: Simile a bytes.hex(), memoryview.hex() supporta ora i parametri opzionali sep e bytes_per_sep per inserire separatori tra i byte nell’output esadecimale.

tolist()

Restituisce i dati nel buffer come una lista di elementi.

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

Cambiato nella versione 3.3: tolist() supporta ora tutti i formati nativi a singolo carattere nella sintassi del modulo struct nonché rappresentazioni multidimensionali.

toreadonly()

Restituisce una versione di sola lettura dell’oggetto memoryview. L’oggetto memoryview originale rimane invariato.

>>> m = memoryview(bytearray(b'abc'))
>>> mm = m.toreadonly()
>>> mm.tolist()
[97, 98, 99]
>>> mm[0] = 42
Traceback (most recent call last):
  File "<stdin>", line 1, in <module>
TypeError: cannot modify read-only memory
>>> m[0] = 43
>>> mm.tolist()
[43, 98, 99]

Added in version 3.8.

release()

Rilascia il buffer sottostante esposto dall’oggetto memoryview. Molti oggetti prendono azioni speciali quando una vista è mantenuta su di essi (ad esempio, un bytearray temporaneamente vieterebbe il ridimensionamento); quindi, chiamare release() è utile per rimuovere queste restrizioni (e liberare eventuali risorse sospese) il più presto possibile.

After this method has been called, any further operation on the view raises a ValueError (except release() itself which can be called multiple times):

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

Il protocollo di gestione del contesto può essere utilizzato per un effetto simile, usando l’istruzione 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

Added in version 3.2.

cast(format[, shape])

Converte un memoryview in un nuovo formato o forma. shape di default è [byte_length//new_itemsize], il che significa che la vista risultante sarà unidimensionale. Il valore restituito è un nuovo memoryview, ma il buffer stesso non è copiato. I cast supportati sono 1D -> C-contiguous e C-contiguous -> 1D.

Il formato di destinazione è limitato a un formato nativo a singolo elemento nella sintassi del modulo struct. Uno dei formati deve essere un formato byte (“B”, “b” o “c”). La lunghezza in byte del risultato deve essere uguale alla lunghezza originale. Nota che tutte le lunghezze in byte possono dipendere dal sistema operativo.

Converte 1D/long in 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

Converte 1D/unsigned bytes in 1D/char:

>>> b = bytearray(b'zyz')
>>> x = memoryview(b)
>>> x[0] = b'a'
Traceback (most recent call last):
  ...
TypeError: memoryview: invalid type for format 'B'
>>> y = x.cast('c')
>>> y[0] = b'a'
>>> b
bytearray(b'ayz')

Converte 1D/bytes in 3D/ints in 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

Converte 1D/unsigned long in 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]]

Added in version 3.3.

Cambiato nella versione 3.5: Il formato di origine non è più limitato quando si converte in una vista byte.

Sono disponibili anche diversi attributi di sola lettura:

obj

L’oggetto sottostante del memoryview:

>>> b  = bytearray(b'xyz')
>>> m = memoryview(b)
>>> m.obj is b
True

Added in version 3.3.

nbytes

nbytes == product(shape) * itemsize == len(m.tobytes()). Questo è lo spazio in byte che l’array utilizzarebbe in una rappresentazione contigua. Non necessariamente uguale a 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

Array multidimensionali:

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

Added in version 3.3.

readonly

Un bool che indica se la memoria è di sola lettura.

format

Una stringa contenente il formato (nello stile del modulo struct) per ogni elemento nella vista. Un memoryview può essere creato da esportatori con stringhe di formato arbitrario, ma alcuni metodi (es.: tolist()) sono limitati ai formati a singolo elemento nativi.

Cambiato nella versione 3.3: Il formato 'B' viene ora gestito secondo la sintassi del modulo struct. Ciò significa che memoryview(b'abc')[0] == b'abc'[0] == 97.

itemsize

La dimensione in byte di ogni elemento del 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 intero che indica quante dimensioni di un array multidimensionale la memoria rappresenta.

shape

Una tupla di numeri interi della lunghezza di ndim che indica la forma della memoria come un array N-dimensionale.

Cambiato nella versione 3.3: Una tupla vuota invece di None quando ndim = 0.

strides

Una tupla di numeri interi della lunghezza di ndim che indica la dimensione in byte per accedere a ogni elemento per ciascuna dimensione dell’array.

Cambiato nella versione 3.3: Una tupla vuota invece di None quando ndim = 0.

suboffsets

Usato internamente per array in stile PIL. Il valore è solo informativo.

c_contiguous

Un bool che indica se la memoria è C-contiguous.

Added in version 3.3.

f_contiguous

Un bool che indica se la memoria è Fortran contiguous.

Added in version 3.3.

contiguous

Un bool che indica se la memoria è contiguous.

Added in version 3.3.

Tipi di Insiemi — set, frozenset

Un oggetto set è una collezione non ordinata di oggetti distinti hashable. Usati comunemente per test di appartenenza, rimozione di duplicati da una sequenza e operazioni matematiche come intersezione, unione, differenza e differenza simmetrica. (Per altri contenitori vedi le classi integrate dict, list e tuple, e il modulo collections.)

Come altre collezioni, gli insiemi supportano x in set, len(set) e for x in set. Essendo una collezione non ordinata, gli insiemi non tengono traccia della posizione degli elementi o dell’ordine di inserimento. Di conseguenza, gli insiemi non supportano indicizzazione, slicing o altro comportamento simile a una sequenza.

Attualmente esistono due tipi di insiemi incorporati, set e frozenset. Il tipo set è mutabile — il contenuto può essere cambiato usando metodi come add() e remove(). Poiché è mutabile, non ha un valore di hash e non può essere utilizzato come chiave di un dizionario o come elemento di un altro insieme. Il tipo frozenset è immutabile e hashable — i suoi contenuti non possono essere alterati dopo la sua creazione; può quindi essere utilizzato come chiave di un dizionario o come elemento di un altro insieme.

Gli insiemi non vuoti (non i frozenset) possono essere creati mettendo un elenco di elementi separati da virgole tra parentesi graffe, per esempio: {'jack', 'sjoerd'}, oltre al costruttore set.

I costruttori per entrambe le classi funzionano allo stesso modo:

class set([iterable])

class frozenset([iterable])

Restituisce un nuovo oggetto set o frozenset i cui elementi sono presi da iterable. Gli elementi di un insieme devono essere hashable. Per rappresentare insiemi di insiemi, gli insiemi interni devono essere oggetti frozenset. Se iterable non è specificato, viene restituito un nuovo insieme vuoto.

Gli insiemi possono essere creati in diversi modi:

• Usa un elenco di elementi separati da virgole tra parentesi graffe: {'jack', 'sjoerd'}

• Usa una comprensione dell’insieme: {c for c in 'abracadabra' if c not in 'abc'}

• Usa il costruttore di tipo: set(), set('foobar'), set(['a', 'b', 'foo'])

Le istanze di set e frozenset forniscono le seguenti operazioni:

len(s)

Restituisce il numero di elementi nell’insieme s (cardinalità di s).

x in s

Verifica l’appartenenza di x in s.

x not in s

Verifica la non appartenenza di x in s.

isdisjoint(other)

Restituisce True se l’insieme non ha elementi in comune con other. Gli insiemi sono disgiunti se e solo se la loro intersezione è l’insieme vuoto.

issubset(other)

set <= other

Verifica se ogni elemento nell’insieme è in other.

set < other

Verifica se l’insieme è un sottoinsieme proprio di other, cioè, set <= other e set != other.

issuperset(other)

set >= other

Verificare se ogni elemento in other è presente nell’insieme.

set > other

Verificare se l’insieme è un superinsieme proprio di other, cioè set >= other and set != other.

union(*others)

set | other | ...

Restituire un nuovo insieme con elementi dall’insieme e tutti gli altri.

intersection(*others)

set & other & ...

Restituire un nuovo insieme con elementi comuni all’insieme e a tutti gli altri.

difference(*others)

set - other - ...

Restituire un nuovo insieme con elementi presenti nell’insieme ma non negli altri.

symmetric_difference(other)

set ^ other

Restituire un nuovo insieme con elementi presenti nell’insieme o in other ma non in entrambi.

copy()

Restituire una copia superficiale dell’insieme.

Nota, le versioni non operatore dei metodi union(), intersection(), difference(), symmetric_difference(), issubset() e issuperset() accettano qualsiasi iterabile come argomento. Al contrario, le loro controparti basate su operatori richiedono che i loro argomenti siano insiemi. Questo esclude costruzioni inclini all’errore come set('abc') & 'cbs' a favore di set('abc').intersection('cbs') più leggibile.

Sia set che frozenset supportano confronti tra insiemi. Due insiemi sono uguali se e solo se ogni elemento di ciascun insieme è contenuto nell’altro (ciascuno è un sottoinsieme dell’altro). Un insieme è minore di un altro insieme se e solo se il primo insieme è un sottoinsieme proprio del secondo insieme (è un sottoinsieme, ma non è uguale). Un insieme è maggiore di un altro insieme se e solo se il primo insieme è un superinsieme proprio del secondo insieme (è un superinsieme, ma non è uguale).

Le istanze di set sono confrontate con le istanze di frozenset basandosi sui loro membri. Ad esempio, set('abc') == frozenset('abc') restituisce True e anche set('abc') in set([frozenset('abc')]).

I confronti di sottoinsieme e uguaglianza non si generalizzano a una funzione di ordinamento totale. Ad esempio, due insiemi non vuoti e disgiunti non sono uguali e non sono sottoinsiemi l’uno dell’altro, quindi tutti i seguenti restituiscono False: a<b, a==b o a>b.

Poiché gli insiemi definiscono solo un ordinamento parziale (relazioni di sottoinsieme), l’output del metodo list.sort() è indefinito per le liste di insiemi.

Gli elementi dell’insieme, come le chiavi del dizionario, devono essere hashable.

Le operazioni binarie che mescolano istanze di set con frozenset restituiscono il tipo del primo operando. Ad esempio: frozenset('ab') | set('bc') restituisce un’istanza di frozenset.

La seguente tabella elenca le operazioni disponibili per set che non si applicano alle istanze immutabili di frozenset:

update(*others)

set |= other | ...

Aggiornare l’insieme, aggiungendo elementi da tutti gli altri.

intersection_update(*others)

set &= other & ...

Aggiornare l’insieme, mantenendo solo gli elementi presenti in esso e in tutti gli altri.

difference_update(*others)

set -= other | ...

Aggiornare l’insieme, rimuovendo gli elementi trovati negli altri.

symmetric_difference_update(other)

set ^= other

Aggiornare l’insieme, mantenendo solo gli elementi presenti in un insieme o nell’altro, ma non in entrambi.

add(elem)

Aggiungere l’elemento elem all’insieme.

remove(elem)

Rimuovere l’elemento elem dall’insieme. Solleva KeyError se elem non è contenuto nell’insieme.

discard(elem)

Rimuovere l’elemento elem dall’insieme, se presente.

pop()

Rimuovere e restituire un elemento arbitrario dall’insieme. Solleva KeyError se l’insieme è vuoto.

clear()

Rimuovere tutti gli elementi dall’insieme.

Nota, le versioni non operatore dei metodi update(), intersection_update(), difference_update() e symmetric_difference_update() accettano qualsiasi iterabile come argomento.

Nota, l’argomento elem per i metodi __contains__(), remove() e discard() può essere un insieme. Per supportare la ricerca di un frozenset equivalente, uno temporaneo viene creato da elem.

Tipi di Mapping — dict

Un oggetto mapping mappa valori hashable a oggetti arbitrari. Le mappature sono oggetti mutabili. Attualmente esiste solo un tipo standard di mappatura, il dizionario. (Per altri contenitori, vedere le classi incorporate list, set e tuple, e il modulo collections.)

Le chiavi di un dizionario sono valori quasi arbitrari. Valori che non sono hashable, cioè valori che contengono liste, dizionari o altri tipi mutabili (che sono comparati per valore anziché per identità dell’oggetto) non possono essere usati come chiavi. Valori che sono comparati come uguali (come 1, 1.0 e True) possono essere usati in modo intercambiabile per indicizzare la stessa voce del dizionario.

class dict(**kwargs)

class dict(mapping, **kwargs)

class dict(iterable, **kwargs)

Restituire un nuovo dizionario inizializzato da un argomento posizionale opzionale e un insieme possibilmente vuoto di argomenti chiave-valore.

I dizionari possono essere creati con diversi metodi:

• Utilizzare un elenco separato da virgole di coppie chiave: valore tra parentesi graffe: {'jack': 4098, 'sjoerd': 4127} o {4098: 'jack', 4127: 'sjoerd'}

• Usare una comprensione del dizionario: {}, {x: x ** 2 per x in range(10)}

• Utilizzare il costruttore di tipi: dict(), dict([('foo', 100), ('bar', 200)]), dict(foo=100, bar=200)

If no positional argument is given, an empty dictionary is created. If a positional argument is given and it defines a keys() method, a dictionary is created by calling __getitem__() on the argument with each returned key from the method. Otherwise, the positional argument must be an iterable object. Each item in the iterable must itself be an iterable with exactly two elements. The first element of each item becomes a key in the new dictionary, and the second element the corresponding value. If a key occurs more than once, the last value for that key becomes the corresponding value in the new dictionary.

Se vengono forniti argomenti chiave-valore, gli argomenti chiave-valore e i loro valori vengono aggiunti al dizionario creato dall’argomento posizionale. Se una chiave aggiunta è già presente, il valore dall’argomento chiave-valore sostituisce il valore dall’argomento posizionale.

Per illustrare, i seguenti esempi restituiscono tutti un dizionario uguale a {"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})
>>> f = dict({'one': 1, 'three': 3}, two=2)
>>> a == b == c == d == e == f
True

Fornire argomenti chiave-valore come nel primo esempio funziona solo per chiavi che sono identificatori Python validi. Altrimenti, è possibile utilizzare qualsiasi chiave valida.

Queste sono le operazioni che i dizionari supportano (e che quindi, anche i tipi di mappatura personalizzati dovrebbero supportare):

list(d)

Restituire un elenco di tutte le chiavi utilizzate nel dizionario d.

len(d)

Restituire il numero di voci nel dizionario d.

d[key]

Restituire la voce di d con chiave key. Solleva un’eccezione KeyError se key non è nella mappa.

Se una sottoclasse di dict definisce un metodo __missing__() e key non è presente, l’operazione d[key] chiama quel metodo con la chiave key come argomento. L’operazione d[key] quindi restituisce o solleva qualunque cosa venga restituita o sollevata dalla chiamata __missing__(key). Nessun’altra operazione o metodo invoca __missing__(). Se __missing__() non è definito, viene sollevata un’eccezione KeyError. __missing__() deve essere un metodo; non può essere una variabile di istanza:

>>> class Counter(dict):
...     def __missing__(self, key):
...         return 0
...
>>> c = Counter()
>>> c['red']
0
>>> c['red'] += 1
>>> c['red']
1

L’esempio sopra mostra parte dell’implementazione di collections.Counter. Un diverso metodo __missing__ è utilizzato da collections.defaultdict.

d[key] = value

Impostare d[key] su value.

del d[key]

Rimuovere d[key] da d. Solleva una KeyError se key non è nella mappa.

key in d

Restituire True se d ha una chiave key, altrimenti False.

key not in d

Equivalente a not key in d.

iter(d)

Restituire un iteratore sulle chiavi del dizionario. Questo è un collegamento a iter(d.keys()).

clear()

Rimuovere tutte le voci dal dizionario.

copy()

Restituisce una copia superficiale del dizionario.

classmethod fromkeys(iterable, value=None, /)

Crea un nuovo dizionario con chiavi da iterable e valori impostati su value.

fromkeys() è un metodo di classe che restituisce un nuovo dizionario. value predefinito è None. Tutti i valori si riferiscono a una singola istanza, quindi generalmente non ha senso che value sia un oggetto mutabile come una lista vuota. Per ottenere valori distinti, utilizzare invece una dict comprehension.

get(key, default=None)

Restituisce il valore per key se key è nel dizionario, altrimenti default. Se default non è fornito, predefinito è None, in modo che questo metodo non sollevi mai una KeyError.

items()

Restituisce una nuova vista degli elementi del dizionario (coppie (key, value)). Vedi la documentazione degli oggetti view.

keys()

Restituisce una nuova vista delle chiavi del dizionario. Vedi la documentazione degli oggetti view.

pop(key[, default])

Se key è nel dizionario, rimuovilo e restituisci il suo valore, altrimenti restituisci default. Se default non è fornito e key non è nel dizionario, viene sollevata una KeyError.

popitem()

Rimuove e restituisce una coppia (key, value) dal dizionario. Le coppie sono restituite in ordine LIFO.

popitem() è utile per iterare distruttivamente su un dizionario, come spesso utilizzato negli algoritmi di set. Se il dizionario è vuoto, chiamare popitem() solleva una KeyError.

Cambiato nella versione 3.7: L’ordine LIFO è ora garantito. Nelle versioni precedenti, popitem() avrebbe restituito una coppia chiave/valore arbitraria.

reversed(d)

Restituisce un iteratore inverso sulle chiavi del dizionario. Questo è un collegamento rapido per reversed(d.keys()).

Added in version 3.8.

setdefault(key, default=None)

Se key è nel dizionario, restituisce il suo valore. Se non lo è, inserisce key con un valore di default e restituisce default. default predefinito è None.

update([other])

Aggiorna il dizionario con le coppie chiave/valore da other, sovrascrivendo le chiavi esistenti. Restituisce None.

update() accepts either another object with a keys() method (in which case __getitem__() is called with every key returned from the method) 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()

Restituisce una nuova vista dei valori del dizionario. Vedi la documentazione degli oggetti view.

Un confronto di uguaglianza tra una vista dict.values() e un’altra restituirà sempre False. Questo vale anche quando si confronta dict.values() con se stesso:

>>> d = {'a': 1}
>>> d.values() == d.values()
False

d | other

Crea un nuovo dizionario con le chiavi e i valori uniti di d e other, che devono essere entrambi dizionari. I valori di other hanno la priorità quando d e other condividono chiavi.

Added in version 3.9.

d |= other

Aggiorna il dizionario d con chiavi e valori da other, che può essere un mapping o un iterable di coppie chiave/valore. I valori di other hanno la priorità quando d e other condividono chiavi.

Added in version 3.9.

I dizionari si confrontano uguali se e solo se hanno le stesse coppie (key, value) (indipendentemente dall’ordinamento). I confronti di ordine (“<”, “<=”, “>=”, “>”) sollevano TypeError.

I dizionari preservano l’ordine di inserimento. Nota che aggiornare una chiave non influenza l’ordine. Le chiavi aggiunte dopo la cancellazione vengono inserite alla fine.

>>> d = {"one": 1, "two": 2, "three": 3, "four": 4}
>>> d
{'one': 1, 'two': 2, 'three': 3, 'four': 4}
>>> list(d)
['one', 'two', 'three', 'four']
>>> list(d.values())
[1, 2, 3, 4]
>>> d["one"] = 42
>>> d
{'one': 42, 'two': 2, 'three': 3, 'four': 4}
>>> del d["two"]
>>> d["two"] = None
>>> d
{'one': 42, 'three': 3, 'four': 4, 'two': None}

Cambiato nella versione 3.7: L’ordine del dizionario è garantito essere l’ordine di inserimento. Questo comportamento era un dettaglio di implementazione di CPython dalla versione 3.6.

I dizionari e le viste del dizionario sono reversibili.

>>> d = {"one": 1, "two": 2, "three": 3, "four": 4}
>>> d
{'one': 1, 'two': 2, 'three': 3, 'four': 4}
>>> list(reversed(d))
['four', 'three', 'two', 'one']
>>> list(reversed(d.values()))
[4, 3, 2, 1]
>>> list(reversed(d.items()))
[('four', 4), ('three', 3), ('two', 2), ('one', 1)]

Cambiato nella versione 3.8: I dizionari sono ora reversibili.

Vedi anche

types.MappingProxyType può essere utilizzato per creare una vista di sola lettura di un dict.

Oggetti vista del dizionario

Gli oggetti restituiti da dict.keys(), dict.values() e dict.items() sono oggetti vista. Forniscono una vista dinamica sulle voci del dizionario, il che significa che quando il dizionario cambia, la vista riflette questi cambiamenti.

Le viste del dizionario possono essere iterate per restituire i rispettivi dati e supportano i test di appartenenza:

len(dictview)

Restituisce il numero di voci nel dizionario.

iter(dictview)

Restituisce un iteratore sulle chiavi, valori o elementi (rappresentati come tuple (key, value)) nel dizionario.

Le chiavi e i valori sono iterati in ordine di inserimento. Questo permette la creazione di coppie (value, key) usando zip(): pairs = zip(d.values(), d.keys()). Un altro modo per creare la stessa lista è pairs = [(v, k) for (k, v) in d.items()].

Le viste di iterazione durante l’aggiunta o l’eliminazione di voci nel dizionario possono sollevare una RuntimeError o fallire nell’iterare su tutte le voci.

Cambiato nella versione 3.7: L’ordine del dizionario è garantito essere l’ordine di inserimento.

x in dictview

Restituisce True se x è nelle chiavi, valori o elementi del dizionario sottostante (in quest’ultimo caso, x deve essere una tupla (key, value)).

reversed(dictview)

Restituisce un iteratore inverso sulle chiavi, valori o elementi del dizionario. La vista verrà iterata in ordine inverso rispetto all’inserimento.

Cambiato nella versione 3.8: Le viste del dizionario sono ora reversibili.

dictview.mapping

Restituisce un types.MappingProxyType che incapsula il dizionario originale cui si riferisce la vista.

Added in version 3.10.

Le viste delle chiavi sono simili a insiemi poiché le loro voci sono uniche e hashable. Anche le viste degli elementi hanno operazioni simili a insiemi poiché le coppie (key, value) sono uniche e le chiavi sono hashable. Se anche tutti i valori in una vista di elementi sono hashable, allora la vista degli elementi può interoperare con altri insiemi. (Le viste dei valori non sono trattate come simili agli insiemi poiché le voci generalmente non sono uniche.) Per le viste simili agli insiemi, sono disponibili tutte le operazioni definite per la classe base astratta collections.abc.Set (ad esempio, ==, <, o ^). Durante l’uso degli operatori di insiemi, le viste simili agli insiemi accettano qualsiasi iterabile come l’altro operando, a differenza degli insiemi che accettano solo insiemi come input.

Un esempio di utilizzo delle viste del dizionario:

>>> 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 (insertion order)
>>> list(keys)
['eggs', 'sausage', 'bacon', 'spam']
>>> list(values)
[2, 1, 1, 500]

>>> # view objects are dynamic and reflect dict changes
>>> del dishes['eggs']
>>> del dishes['sausage']
>>> list(keys)
['bacon', 'spam']

>>> # set operations
>>> keys & {'eggs', 'bacon', 'salad'}
{'bacon'}
>>> keys ^ {'sausage', 'juice'} == {'juice', 'sausage', 'bacon', 'spam'}
True
>>> keys | ['juice', 'juice', 'juice'] == {'bacon', 'spam', 'juice'}
True

>>> # get back a read-only proxy for the original dictionary
>>> values.mapping
mappingproxy({'bacon': 1, 'spam': 500})
>>> values.mapping['spam']
500

Tipi di gestori di contesti

La dichiarazione with di Python supporta il concetto di un contesto di runtime definito da un gestore di contesto. Questo è implementato utilizzando una coppia di metodi che consentono alle classi definite dall’utente di definire un contesto di runtime che viene inserito prima che il corpo della dichiarazione venga eseguito ed esce quando la dichiarazione termina:

contextmanager.__enter__()

Entra nel contesto di runtime e restituisce questo oggetto o un altro oggetto relativo al contesto di runtime. Il valore restituito da questo metodo è associato all’identificatore nella clausola as di dichiarazioni with che usano questo gestore di contesto.

Un esempio di un gestore di contesto che restituisce se stesso è un file object. Gli oggetti file restituiscono se stessi da __enter__() per permettere di usare open() come espressione di contesto in una dichiarazione with.

Un esempio di un gestore di contesto che restituisce un oggetto correlato è quello restituito da decimal.localcontext(). Questi gestori impostano il contesto decimale attivo su una copia del contesto decimale originale e quindi restituiscono la copia. Questo consente di apportare modifiche al contesto decimale corrente nel corpo della dichiarazione with senza influenzare il codice al di fuori della dichiarazione with.

contextmanager.__exit__(exc_type, exc_val, exc_tb)

Esce dal contesto di runtime e restituisce un flag booleano che indica se deve essere soppressa un’eccezione che si è verificata. Se si è verificata un’eccezione durante l’esecuzione del corpo della dichiarazione with, gli argomenti contengono il tipo di eccezione, il valore e le informazioni di traceback. Altrimenti, tutti e tre gli argomenti sono None.

Restituire un valore vero da questo metodo farà sì che la dichiarazione with sopprima l’eccezione e continui l’esecuzione con l’istruzione immediatamente successiva alla dichiarazione with. Altrimenti, l’eccezione continua a propagarsi dopo che questo metodo ha terminato l’esecuzione. Le eccezioni che si verificano durante l’esecuzione di questo metodo sostituiranno qualsiasi eccezione che si è verificata nel corpo della dichiarazione with.

L’eccezione passata non dovrebbe mai essere riesposta esplicitamente - invece, questo metodo dovrebbe restituire un valore falso per indicare che il metodo è stato completato con successo e non vuole sopprimere l’eccezione sollevata. Questo consente al codice di gestione del contesto di rilevare facilmente se un metodo __exit__() ha effettivamente fallito.

Python definisce diversi gestori di contesto per supportare una facile sincronizzazione dei thread, la chiusura rapida di file o altri oggetti e una manipolazione più semplice del contesto di aritmetica decimale attivo. I tipi specifici non sono trattati in modo speciale oltre alla loro implementazione del protocollo di gestione del contesto. Vedi il modulo contextlib per alcuni esempi.

I generatori di Python e il decoratore contextlib.contextmanager forniscono un modo conveniente per implementare questi protocolli. Se una funzione generatrice è decorata con il decoratore contextlib.contextmanager, restituirà un gestore di contesto che implementa i metodi necessari __enter__() e __exit__(), piuttosto che l’iteratore prodotto da una funzione generatrice non decorata.

Si noti che non esiste uno slot specifico per nessuno di questi metodi nella struttura dei tipi per gli oggetti Python nell’API Python/C. I tipi di estensione che desiderano definire questi metodi devono fornirli come un normale metodo accessibile da Python. Rispetto al sovraccarico di impostare il contesto di runtime, il sovraccarico di una singola ricerca nel dizionario della classe è trascurabile.

Tipi di annotazione di tipo — Alias generico, Union

I tipi core incorporati per type annotations sono Generic Alias e Union.

Tipo Generic Alias

Gli oggetti GenericAlias sono generalmente creati tramite subscripting di una classe. Sono più spesso utilizzati con container classes, come list o dict. Ad esempio, list[int] è un oggetto GenericAlias creato facendo subscripting della classe list con l’argomento int. Gli oggetti GenericAlias sono progettati principalmente per essere usati con type annotations.

Nota

Generalmente è possibile fare subscripting di una classe solo se la classe implementa il metodo speciale __class_getitem__().

Un oggetto GenericAlias funge da proxy per un generic type, implementando parameterized generics.

Per una container class, l’argomento o gli argomenti forniti a un subscription della classe possono indicare il tipo o i tipi degli elementi che un oggetto contiene. Ad esempio, set[bytes] può essere utilizzato nelle type annotations per indicare un set in cui tutti gli elementi sono di tipo bytes.

Per una classe che definisce __class_getitem__() ma non è un container, l’argomento o gli argomenti forniti a un subscription della classe spesso indicheranno il tipo di ritorno di uno o più metodi definiti su un oggetto. Ad esempio, regular expressions può essere utilizzato sia sul tipo di dato str che sul tipo di dato bytes:

• Se x = re.search('foo', 'foo'), x sarà un oggetto re.Match dove i valori di ritorno di x.group(0) e x[0] saranno entrambi di tipo str. Possiamo rappresentare questo tipo di oggetto nelle type annotations con il GenericAlias re.Match[str].

• Se y = re.search(b'bar', b'bar'), (nota il b per bytes), y sarà anch’esso un’istanza di re.Match, ma i valori di ritorno di y.group(0) e y[0] saranno entrambi di tipo bytes. Nelle type annotations, rappresenteremmo questa varietà di oggetti re.Match con re.Match[bytes].

Gli oggetti GenericAlias sono istanze della classe types.GenericAlias, che può essere utilizzata anche per creare direttamente oggetti GenericAlias.

T[X, Y, ...]

Crea un GenericAlias che rappresenta un tipo T parametrizzato dai tipi X, Y e altro a seconda del T utilizzato. Ad esempio, una funzione che si aspetta una list contenente elementi di tipo float:

def average(values: list[float]) -> float:
    return sum(values) / len(values)

Un altro esempio per gli oggetti mapping, utilizzando un dict, che è un tipo generico che si aspetta due parametri di tipo che rappresentano il tipo delle chiavi e il tipo dei valori. In questo esempio, la funzione si aspetta un dict con chiavi di tipo str e valori di tipo int:

def send_post_request(url: str, body: dict[str, int]) -> None:
    ...

Le funzioni incorporate isinstance() e issubclass() non accettano tipi GenericAlias come secondo argomento:

>>> isinstance([1, 2], list[str])
Traceback (most recent call last):
  File "<stdin>", line 1, in <module>
TypeError: isinstance() argument 2 cannot be a parameterized generic

Il runtime Python non impone type annotations. Questo si estende ai tipi generici e ai loro parametri di tipo. Quando si crea un oggetto container da un GenericAlias, gli elementi nel container non vengono verificati in base al loro tipo. Ad esempio, il seguente codice è sconsigliato, ma verrà eseguito senza errori:

>>> t = list[str]
>>> t([1, 2, 3])
[1, 2, 3]

Inoltre, i generici parametrizzati eliminano i parametri di tipo durante la creazione dell’oggetto:

>>> t = list[str]
>>> type(t)
<class 'types.GenericAlias'>

>>> l = t()
>>> type(l)
<class 'list'>

Chiamare repr() o str() su un generico mostra il tipo parametrizzato:

>>> repr(list[int])
'list[int]'

>>> str(list[int])
'list[int]'

Il metodo __getitem__() dei container generici solleverà un’eccezione per impedire errori come dict[str][str]:

>>> dict[str][str]
Traceback (most recent call last):
  ...
TypeError: dict[str] is not a generic class

Tuttavia, tali espressioni sono valide quando vengono utilizzate le type variables. L’indice deve avere tanti elementi quanti sono gli item delle variabili di tipo nell’oggetto GenericAlias __args__.:

>>> from typing import TypeVar
>>> Y = TypeVar('Y')
>>> dict[str, Y][int]
dict[str, int]

Classi Generiche Standard

Le seguenti classi della libreria standard supportano i generici parametrizzati. Questa lista non è esaustiva.

• tuple

• list

• dict

• set

• frozenset

• type

• collections.deque

• collections.defaultdict

• collections.OrderedDict

• collections.Counter

• collections.ChainMap

• collections.abc.Awaitable

• collections.abc.Coroutine

• collections.abc.AsyncIterable

• collections.abc.AsyncIterator

• collections.abc.AsyncGenerator

• collections.abc.Iterable

• collections.abc.Iterator

• collections.abc.Generator

• collections.abc.Reversible

• collections.abc.Container

• collections.abc.Collection

• collections.abc.Callable

• collections.abc.Set

• collections.abc.MutableSet

• collections.abc.Mapping

• collections.abc.MutableMapping

• collections.abc.Sequence

• collections.abc.MutableSequence

• collections.abc.ByteString

• collections.abc.MappingView

• collections.abc.KeysView

• collections.abc.ItemsView

• collections.abc.ValuesView

• contextlib.AbstractContextManager

• contextlib.AbstractAsyncContextManager

• dataclasses.Field

• functools.cached_property

• functools.partialmethod

• os.PathLike

• queue.LifoQueue

• queue.Queue

• queue.PriorityQueue

• queue.SimpleQueue

• re.Pattern

• re.Match

• shelve.BsdDbShelf

• shelve.DbfilenameShelf

• shelve.Shelf

• types.MappingProxyType

• weakref.WeakKeyDictionary

• weakref.WeakMethod

• weakref.WeakSet

• weakref.WeakValueDictionary

Attributi Speciali per oggetti GenericAlias

Tutti i generici parametrici implementano attributi speciali di sola lettura.

genericalias.__origin__

Questo attributo punta alla classe generica non parametrizzata:

>>> list[int].__origin__
<class 'list'>

genericalias.__args__

Questo attributo è una tuple (possibilmente di lunghezza 1) di tipi generici passati al metodo originale __class_getitem__() della classe generica:

>>> dict[str, list[int]].__args__
(<class 'str'>, list[int])

genericalias.__parameters__

Questo attributo è una tupla calcolata pigramente (possibilmente vuota) di variabili di tipo uniche trovate in __args__:

>>> from typing import TypeVar

>>> T = TypeVar('T')
>>> list[T].__parameters__
(~T,)

Nota

Un oggetto GenericAlias con parametri typing.ParamSpec potrebbe non avere __parameters__ corretti dopo la sostituzione perché typing.ParamSpec è destinato principalmente al controllo statico dei tipi.

genericalias.__unpacked__

Un booleano che è vero se l’alias è stato espanso usando l’operatore * (vedere TypeVarTuple).

Added in version 3.11.

Vedi anche

PEP 484 - Suggerimenti di Tipo

Introduzione al framework di Python per le annotazioni di tipo.

PEP 585 - Indicazione di Tipo Generica nelle Collezioni Standard

Introduzione alla capacità di parametrizzare nativamente le classi della libreria standard, a condizione che implementino il metodo speciale di classe __class_getitem__().

Generics, user-defined generics e typing.Generic

Documentazione su come implementare classi generiche che possono essere parametrizzate in fase di esecuzione e comprese dai controllori di tipo statico.

Added in version 3.9.

Tipo Unione

Un oggetto unione contiene il valore dell’operazione | (or bit a bit) su più oggetti di tipo. Questi tipi sono destinati principalmente alle annotazioni di tipo. L’espressione del tipo unione consente una sintassi più pulita per i suggerimenti di tipo rispetto a typing.Union.

X | Y | ...

Definisce un oggetto unione che contiene i tipi X, Y, e così via. X | Y significa X o Y. È equivalente a typing.Union[X, Y]. Ad esempio, la seguente funzione si aspetta un argomento di tipo int o float:

def square(number: int | float) -> int | float:
    return number ** 2

Nota

L’operando | non può essere utilizzato in fase di esecuzione per definire unioni dove uno o più membri sono un riferimento in avanti. Ad esempio, int | "Foo", dove "Foo" è un riferimento a una classe non ancora definita, fallirà in fase di esecuzione. Per le unioni che includono riferimenti in avanti, presentare l’intera espressione come una stringa, ad esempio "int | Foo".

union_object == other

Gli oggetti unione possono essere testati per uguaglianza con altri oggetti unione. Dettagli:

• Le unioni di unioni sono appiattite:

  (int | str) | float == int | str | float
  

• I tipi ridondanti sono rimossi:

  int | str | int == int | str
  

• Quando si confrontano le unioni, l’ordine è ignorato:

  int | str == str | int
  

• È compatibile con typing.Union:

  int | str == typing.Union[int, str]
  

• I tipi opzionali possono essere scritti come un’unione con None:

  str | None == typing.Optional[str]
  

isinstance(obj, union_object)

issubclass(obj, union_object)

Anche le chiamate a isinstance() e issubclass() sono supportate con un oggetto unione:

>>> isinstance("", int | str)
True

Tuttavia, generici parametrici negli oggetti unione non possono essere verificati:

>>> isinstance(1, int | list[int])  # short-circuit evaluation
True
>>> isinstance([1], int | list[int])
Traceback (most recent call last):
  ...
TypeError: isinstance() argument 2 cannot be a parameterized generic

Il tipo esposto all’utente per l’oggetto unione può essere accessibile da types.UnionType e utilizzato per i controlli isinstance(). Un oggetto non può essere istanziato dal tipo:

>>> import types
>>> isinstance(int | str, types.UnionType)
True
>>> types.UnionType()
Traceback (most recent call last):
  File "<stdin>", line 1, in <module>
TypeError: cannot create 'types.UnionType' instances

Nota

Il metodo __or__() per gli oggetti di tipo è stato aggiunto per supportare la sintassi X | Y. Se una metaclasse implementa __or__(), l’Unione può sovrascriverlo:

>>> class M(type):
...     def __or__(self, other):
...         return "Hello"
...
>>> class C(metaclass=M):
...     pass
...
>>> C | int
'Hello'
>>> int | C
int | C

Vedi anche

PEP 604 – PEP che propone la sintassi X | Y e il tipo Unione.

Added in version 3.10.

Altri Tipi Integrati

L’interprete supporta diversi altri tipi di oggetti. La maggior parte di questi supporta solo una o due operazioni.

Moduli

L’unica operazione speciale su un modulo è l’accesso agli attributi: m.name, dove m è un modulo e name accede a un nome definito nella tabella dei simboli di m. Gli attributi del modulo possono essere assegnati. (Nota che l’istruzione import non è, strettamente parlando, un’operazione su un oggetto modulo; import foo non richiede che esista un oggetto modulo chiamato foo, ma richiede una definizione (esterna) per un modulo denominato foo da qualche parte.)

Un attributo speciale di ogni modulo è __dict__. Questo è il dizionario contenente la tabella dei simboli del modulo. La modifica di questo dizionario cambierà effettivamente la tabella dei simboli del modulo, ma l’assegnazione diretta all’attributo __dict__ non è possibile (puoi scrivere m.__dict__['a'] = 1, che definisce m.a come 1, ma non puoi scrivere m.__dict__ = {}). Modificare direttamente __dict__ non è consigliato.

I moduli integrati nell’interprete sono scritti così: <module 'sys' (built-in)>. Se caricati da un file, sono scritti come <module 'os' from '/usr/local/lib/pythonX.Y/os.pyc'>.

Classi e Istanze di Classe

Vedi Objects, values and types e Class definitions per questi.

Funzioni

Gli oggetti funzione sono creati dalle definizioni di funzione. L’unica operazione su un oggetto funzione è chiamarlo: func(lista-argomenti).

Esistono realmente due tipi di oggetti funzione: funzioni integrate e funzioni definite dall’utente. Entrambi supportano la stessa operazione (chiamare la funzione), ma l’implementazione è diversa, da cui i diversi tipi di oggetti.

Vedi Function definitions per ulteriori informazioni.

Metodi

I metodi sono funzioni chiamate utilizzando la notazione degli attributi. Ci sono due tipi: metodi integrati (come append() su liste) e metodi delle istanze di classe. I metodi integrati sono descritti con i tipi che li supportano.

Se accedi a un metodo (una funzione definita in uno spazio dei nomi di una classe) tramite un’istanza, ottieni un oggetto speciale: un oggetto metodo vincolato (anche chiamato metodo istanza). Quando viene chiamato, aggiungerà l’argomento self all’elenco degli argomenti. I metodi vincolati hanno due attributi speciali di sola lettura: m.__self__ è l’oggetto su cui il metodo opera, e m.__func__ è la funzione che implementa il metodo. Chiamare m(arg-1, arg-2, ..., arg-n) è completamente equivalente a chiamare m.__func__(m.__self__, arg-1, arg-2, ..., arg-n).

Come oggetti funzione, gli oggetti metodo vincolati supportano l’acquisizione di attributi arbitrari. Tuttavia, poiché gli attributi del metodo sono effettivamente memorizzati sull’oggetto funzione sottostante (method.__func__), impostare attributi del metodo sui metodi vincolati non è consentito. Il tentativo di impostare un attributo su un metodo provoca il sollevamento di un’eccezione AttributeError. Per impostare un attributo del metodo, devi esplicitamente impostarlo sull’oggetto funzione sottostante:

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

Vedi Instance methods per ulteriori informazioni.

Oggetti Codice

Gli oggetti codice sono utilizzati dall’implementazione per rappresentare il codice Python «pseudo-compilato» eseguibile come il corpo di una funzione. Differiscono dagli oggetti funzione perché non contengono un riferimento al loro ambiente di esecuzione globale. Gli oggetti codice sono restituiti dalla funzione integrata compile() e possono essere estratti dagli oggetti funzione attraverso il loro attributo __code__. Vedi anche il modulo code.

L’accesso a __code__ solleva un evento di auditing object.__getattr__ con argomenti obj e "__code__".

Un oggetto codice può essere eseguito o valutato passandolo (anziché una stringa sorgente) alle funzioni integrate exec() o eval().

Vedi The standard type hierarchy per ulteriori informazioni.

Oggetti Tipo

Gli oggetti tipo rappresentano i vari tipi di oggetto. Il tipo di un oggetto è accessibile tramite la funzione integrata type(). Non ci sono operazioni speciali sui tipi. Il modulo standard types definisce nomi per tutti i tipi integrati standard.

I tipi sono scritti così: <class 'int'>.

L’Oggetto Null

Questo oggetto è restituito da funzioni che non restituiscono esplicitamente un valore. Non supporta operazioni speciali. C’è esattamente un oggetto null, chiamato None (un nome integrato). type(None)() produce lo stesso singleton.

È scritto come None.

L’Oggetto Ellipsis

Questo oggetto è comunemente usato dall’operatore di slicing (vedi Slicings). Non supporta operazioni speciali. C’è esattamente un oggetto ellissi, chiamato Ellipsis (un nome integrato). type(Ellipsis)() produce il singleton Ellipsis.

È scritto come Ellipsis o ....

L’Oggetto NotImplemented

Questo oggetto è restituito da confronti e operazioni binarie quando questi sono richiesti di operare su tipi che non supportano. Vedi Comparisons per maggiori informazioni. C’è esattamente un oggetto NotImplemented. type(NotImplemented)() produce l’istanza singleton.

È scritto come NotImplemented.

Oggetti Interni

Vedi The standard type hierarchy per queste informazioni. Descrive stack frame objects, traceback objects, e oggetti slice.

Attributi Speciali

L’implementazione aggiunge alcuni attributi speciali di sola lettura a diversi tipi di oggetti, ove rilevanti. Alcuni di questi non sono riportati dalla funzione integrata dir().

definition.__name__

Il nome della classe, funzione, metodo, descrittore o istanza del generatore.

definition.__qualname__

Il qualified name della classe, funzione, metodo, descrittore o istanza del generatore.

Added in version 3.3.

definition.__module__

The name of the module in which a class or function was defined.

definition.__doc__

The documentation string of a class or function, or None if undefined.

definition.__type_params__

The type parameters of generic classes, functions, and type aliases. For classes and functions that are not generic, this will be an empty tuple.

Added in version 3.12.

Limitazione della lunghezza di conversione delle stringhe di interi

CPython ha un limite globale per la conversione tra int e str per mitigare gli attacchi denial of service. Questo limite si applica solo alle basi decimali o ad altre basi numeriche non potenze di due. Le conversioni esadecimali, ottali e binarie sono illimitate. Il limite può essere configurato.

Il tipo int in CPython è un numero di lunghezza arbitraria memorizzato in forma binaria (comunemente noto come «bignum»). Non esiste alcun algoritmo che possa convertire una stringa in un intero binario o un intero binario in una stringa in tempo lineare, a meno che la base non sia una potenza di 2. Anche i migliori algoritmi conosciuti per la base 10 hanno una complessità sub-quadratica. La conversione di un valore grande come int('1' * 500_000) può richiedere più di un secondo su una CPU veloce.

Limitare la dimensione della conversione offre un modo pratico per evitare CVE 2020-10735.

Il limite si applica al numero di caratteri numerici nella stringa di input o output quando sarebbe coinvolto un algoritmo di conversione non lineare. Gli underscore e il segno non vengono contati ai fini del limite.

Quando un’operazione supererebbe il limite, viene sollevata un’eccezione ValueError:

>>> import sys
>>> sys.set_int_max_str_digits(4300)  # Illustrative, this is the default.
>>> _ = int('2' * 5432)
Traceback (most recent call last):
...
ValueError: Exceeds the limit (4300 digits) for integer string conversion: value has 5432 digits; use sys.set_int_max_str_digits() to increase the limit
>>> i = int('2' * 4300)
>>> len(str(i))
4300
>>> i_squared = i*i
>>> len(str(i_squared))
Traceback (most recent call last):
...
ValueError: Exceeds the limit (4300 digits) for integer string conversion; use sys.set_int_max_str_digits() to increase the limit
>>> len(hex(i_squared))
7144
>>> assert int(hex(i_squared), base=16) == i*i  # Hexadecimal is unlimited.

Il limite predefinito è di 4300 cifre come indicato in sys.int_info.default_max_str_digits. Il limite più basso che può essere configurato è 640 cifre come indicato in sys.int_info.str_digits_check_threshold.

Verifica:

>>> import sys
>>> assert sys.int_info.default_max_str_digits == 4300, sys.int_info
>>> assert sys.int_info.str_digits_check_threshold == 640, sys.int_info
>>> msg = int('578966293710682886880994035146873798396722250538762761564'
...           '9252925514383915483333812743580549779436104706260696366600'
...           '571186405732').to_bytes(53, 'big')
...

Added in version 3.11.

API influenzate

La limitazione si applica solo alle conversioni potenzialmente lente tra int e str o bytes:

• int(string) con base predefinita 10.

• int(string, base) per tutte le basi che non sono una potenza di 2.

• str(integer).

• repr(integer).

• qualsiasi altra conversione di stringhe in base 10, ad esempio f"{integer}", "{}".format(integer), o b"%d" % integer.

Le limitazioni non si applicano alle funzioni con un algoritmo lineare:

• int(string, base) con base 2, 4, 8, 16 o 32.

• int.from_bytes() e int.to_bytes().

• hex(), oct(), bin().

• Format Specification Mini-Language per i numeri esadecimali, ottali e binari.

• str a float.

• str a decimal.Decimal.

Configurazione del limite

Prima dell’avvio di Python, è possibile utilizzare una variabile d’ambiente o un flag da linea di comando dell’interprete per configurare il limite:

• PYTHONINTMAXSTRDIGITS, ad es. PYTHONINTMAXSTRDIGITS=640 python3 per impostare il limite a 640 o PYTHONINTMAXSTRDIGITS=0 python3 per disabilitare la limitazione.

• -X int_max_str_digits, ad es. python3 -X int_max_str_digits=640

• sys.flags.int_max_str_digits contiene il valore di PYTHONINTMAXSTRDIGITS o -X int_max_str_digits. Se sia la variabile d’ambiente che l’opzione -X sono impostate, l’opzione -X ha la precedenza. Un valore di -1 indica che entrambi non erano impostati, quindi durante l’inizializzazione è stato utilizzato un valore di sys.int_info.default_max_str_digits.

Dal codice, puoi ispezionare il limite corrente e impostarne uno nuovo utilizzando queste API del modulo sys:

• sys.get_int_max_str_digits() e sys.set_int_max_str_digits() sono un getter e un setter per il limite a livello dell’interprete. I sotto-interpreti hanno il proprio limite.

Informazioni sul predefinito e sul minimo possono essere trovate in sys.int_info:

• sys.int_info.default_max_str_digits è il limite predefinito compilato.

• sys.int_info.str_digits_check_threshold è il valore minimo accettato per il limite (ad eccezione di 0 che lo disabilita).

Added in version 3.11.

Attenzione

Impostare un limite basso può portare a problemi. Sebbene raro, esiste del codice che contiene costanti intere in decimale nel loro sorgente che superano la soglia minima. Una conseguenza dell’impostazione del limite è che il codice sorgente Python contenente letterali interi decimali più lunghi del limite incontrerà un errore durante l’analisi, solitamente all’avvio o al momento dell’importazione o anche durante l’installazione - ogni volta che un .pyc non aggiornato non esiste già per il codice. Un workaround per il sorgente che contiene tali costanti grandi è convertirle in forma esadecimale 0x poiché non ha limite.

Testa accuratamente la tua applicazione se utilizzi un limite basso. Assicurati che i tuoi test vengano eseguiti con il limite impostato in anticipo tramite l’ambiente o il flag in modo che si applichi durante l’avvio e anche durante qualsiasi passaggio di installazione che potrebbe invocare Python per precompilare i sorgenti .py in file .pyc.

Configurazione consigliata

Il sys.int_info.default_max_str_digits predefinito è previsto per essere ragionevole per la maggior parte delle applicazioni. Se la tua applicazione richiede un limite diverso, impostalo dal tuo punto di ingresso principale utilizzando codice agnostico alla versione di Python poiché queste API sono state aggiunte in rilasci di patch di sicurezza in versioni precedenti alla 3.12.

Esempio:

>>> import sys
>>> if hasattr(sys, "set_int_max_str_digits"):
...     upper_bound = 68000
...     lower_bound = 4004
...     current_limit = sys.get_int_max_str_digits()
...     if current_limit == 0 or current_limit > upper_bound:
...         sys.set_int_max_str_digits(upper_bound)
...     elif current_limit < lower_bound:
...         sys.set_int_max_str_digits(lower_bound)

Se hai bisogno di disabilitarlo completamente, impostalo a 0.

Note a piè di pagina

[1]

Ulteriori informazioni su questi metodi speciali possono essere trovate nel Manuale di Riferimento Python (Basic customization).

[2]

Di conseguenza, l’elenco [1, 2] è considerato uguale a [1.0, 2.0], e analogamente per le tuple.

[3]

Devono esserlo poiché il parser non può determinare il tipo degli operandi.

[4] (1,2,3,4)

I caratteri con distinzione di maiuscole e minuscole sono quelli con proprietà di categoria generale «Lu» (Lettera, maiuscola), «Ll» (Lettera, minuscola) o «Lt» (Lettera, maiuscola a inizio parola).

[5] (1,2)

Per formattare solo una tupla, dovresti quindi fornire una tupla singleton il cui unico elemento è la tupla da formattare.