# 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`.

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

Python’s generators provide a convenient way to implement the iterator protocol. If a container object’s `__iter__()` method is implemented as a generator, it will automatically return an iterator object (technically, a generator object) supplying the `__iter__()` and `__next__()` methods. More information about generators can be found in the documentation for the yield expression.

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

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

  Return true if all characters in the string are printable, false if it contains at least one non-printable character.

  Here «printable» means the character is suitable for `repr()` to use in its output; «non-printable» means that `repr()` on built-in types will hex-escape the character. It has no bearing on the handling of strings written to `sys.stdout` or `sys.stderr`.

  The printable characters are those which in the Unicode character database (see `unicodedata`) have a general category in group Letter, Mark, Number, Punctuation, or Symbol (L, M, N, P, or S); plus the ASCII space 0x20. Nonprintable characters are those in group Separator or Other (Z or C), except the ASCII space.

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`

- `asyncio.Future`

- `asyncio.Task`

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