Вбудовані типи

У наступних розділах описуються стандартні типи, вбудовані в інтерпретатор.

Основними вбудованими типами є числа, послідовності, відображення, класи, екземпляри та винятки.

Деякі класи колекцій є мутабельними. Методи, які додають, віднімають або переставляють свої члени на місці, і не повертають конкретний елемент, ніколи не повертають сам екземпляр колекції, а натомість повертають None.

Деякі операції підтримуються кількома типами об’єктів; зокрема, практично всі об’єкти можна порівняти на рівність, перевірити на значення істинності та перетворити на рядок (за допомогою функції repr() або трохи іншої функції str()). Остання функція неявно використовується, коли об’єкт записується функцією print().

Перевірка значення на істинність

Будь-який об’єкт можна перевірити на значення істинності для використання як умову в конструкціях if або while або як операнд булевих операцій, наведених нижче.

За замовчуванням об’єкт вважається істинним, якщо його клас не визначає або метод __bool__(), що повертає False, або метод __len__(), що повертає нуль, коли викликати його для цього об’єкта. [1] Тут наведена більшість вбудованих об’єктів, що вважаються хибними:

• константи, визначені як хибні: None і False

• нуль будь-якого числового типу: 0, 0.0, 0j, Decimal(0), Fraction(0, 1)

• порожні послідовності та колекції: '', (), [], {}, set(), range(0)

Операції та вбудовані функції, які мають булевий результат, завжди повертають 0 або False для хибного значення і 1 або True для істинного, якщо не вказано інше. (Важливий виняток: логічні операції or та and завжди повертають один зі своїх операндів.)

Булеві операції — and, or, not

Ось булеві операції, впорядковані за зростанням пріоритету:

Операція	Результат	Примітки
x or y	якщо x є істинним, то x, інакше y	(1)
x and y	якщо x є хибним, тоді x, інакше y	(2)
not x	якщо x є хибним, тоді True, інакше False	(3)

Примітки:

1. Це оператор зі скороченим обчисленням, тому він обчислює другий аргумент лише якщо перший є хибним.

2. Це оператор короткого замикання, тому він обчислює лише другий аргумент, якщо перший істинний.

3. not має нижчий пріоритет, ніж не-булеві оператори, тому not a == b інтерпретується як not (a == b), а a == not b є синтаксичною помилкою.

Порівняння

У Python є вісім операцій порівняння. Усі вони мають однаковий пріоритет (вищий, ніж у булевих операцій). Порівняння можна довільно додавати у ланцюжки; наприклад, x < y <= z еквівалентно x < y and y <= z, за винятком того, що y обчислюється лише один раз (але в обох випадках z узагалі не обчислюється, коли x < y виявляється хибним).

Ця таблиця підсумовує операції порівняння:

Операція	Значення
<	строго менше ніж
<=	менше або дорівнює
>	строго більше ніж
>=	більше або дорівнює
==	дорівнює
!=	не дорівнює
is	ідентичність об’єктів
is not	заперечення ідентичності об’єктів

Об’єкти різних типів, за винятком різних числових типів, ніколи не дорівнюють одне одному. Оператор == завжди визначений, але для деяких типів об’єктів (наприклад, об’єктів класу) еквівалентний is. Оператори <, <=, > і >= визначені лише там, де вони мають сенс; наприклад, вони викликають виняток TypeError, коли один із аргументів є комплексним числом.

Порівняння неідентичних екземплярів класу зазвичай дає хибний результат, якщо лише у класі не визначений метод __eq__().

Екземпляри класу не можуть бути впорядковані відносно інших екземплярів того самого класу або інших типів об’єктів, якщо клас не визначає достатньо методів __lt__(), __le__(),:meth:~object.__gt__ і __ge__() (зазвичай, методів __lt__() і __eq__() достатньо, якщо вас влаштовує звичайна поведінка операторів порівняння).

Поведінку операторів is і is not не можна налаштувати; також вони можуть бути застосовані до будь-яких двох об’єктів і ніколи не викликають винятків.

Ще дві операції з тим же синтаксичним пріоритетом, in і not in, підтримуються типами, що є ітерабельними чи реалізують метод __contains__()

Числові типи — int, float, complex

Існує три різних числових типи: цілі, числа з рухомою комою та комплексні числа. На додачу, булеві числа є підтипом цілих чисел. Цілі числа мають необмежену точність. Числа з рухомою комою зазвичай реалізуються за допомогою double у C; інформацію про точність та внутрішнє представлення чисел з рухомою комою для машини, на якій виконується ваша програма, можна знайти у sys.float_info. Комплексні числа мають дійсну та уявну частини, кожна з яких є числом з рухомою комою. Щоб отримати ці частини з комплексного числа z, використовуйте z.real та z.imag. (Стандартна бібліотека включає додаткові числові типи fractions.Fraction для раціональних чисел та decimal.Decimal для чисел з рухомою комою з точністю, визначеною користувачем).

Числа створюються за допомогою числового літерала або як результат вбудованих функцій та операторів. Неприкрашені цілочисельні літерали (включаючи шістнадцяткові, вісімкові та двійкові числа) дають цілі числа. Числові літерали, що містять десяткову крапку або знак експоненти, дають числа з рухомою комою. Додавання 'j' або 'J' до числового літерала дає уявне число (комплексне число з нульовою дійсною частиною), яке ви можете додати до цілого числа або до числа з рухомою комою, щоб отримати комплексне число з дійсною та уявною частинами.

Python повністю підтримує змішану арифметику: коли двійковий арифметичний оператор має операнди різних числових типів, операнд із «вужчим» типом розширюється до операнда іншого типу, де ціле число вужче за число з рухомою комою, яке є вужчим за комплексне. Порівняння між числами різних типів поводиться так, ніби порівнюються точні значення цих чисел. [2]

Конструктори int(), float() і complex() можна використовувати для отримання чисел певного типу.

Усі числові типи (крім комплексних) підтримують наступні операції (пріоритети операцій див. Пріоритет оператора):

Операція	Результат	Примітки	Повна документація
x + y	сума x і y
x - y	різниця x і y
x * y	добуток x і y
x / y	частка x і y
x // y	округлена донизу частка x і y	(1)(2)
x % y	остача від x / y	(2)
-x	протилежне x
+x	x без змін
abs(x)	абсолютне значення або величина x		abs()
int(x)	x, перетворене на ціле число	(3)(6)	int()
float(x)	x, перетворене на число з рухомою комою	(4)(6)	float()
complex(re, im)	комплексне число з дійсною частиною re, уявною частиною im. im за замовчуванням дорівнює нулю.	(6)	complex()
c.conjugate()	спряжене комплексне число c
divmod(x, y)	пара (x // y, x % y)	(2)	divmod()
pow(x, y)	x у степені y	(5)	pow()
x ** y	x у степені y	(5)

Примітки:

1. Інша назва - цілочисельне ділення. Для операндів типу int результат має тип int. Для операндів типу float результат має тип float. У загальному випадку результатом є ціле число, хоча тип результату не обов’язково int. Результат завжди округлюється в бік мінус нескінченності: 1//2 дорівнює 0, (-1)//2 дорівнює -1, 1//(-2) дорівнює -1, а (-1)//(-2) дорівнює 0.

2. Не для комплексних чисел. Натомість конвертуйте у числа з рухомою комою за допомогою abs(), якщо це доречно.

3. При перетворенні float в int відбувається усічення, дробова частина відкидається. Дивіться функції math.floor() та math.ceil() для альтернативних перетворень.

4. float також приймає рядки «nan» і «inf» з необов’язковим префіксом «+» або «-» на позначення Not a Number (NaN, Не Число) і додатною або від’ємною нескінченністю.

5. Python визначає pow(0, 0) і 0 ** 0 як 1, як це прийнято для мов програмування.

6. Прийнятні числові літерали включають цифри від 0 до 9 або будь-який еквівалент Unicode (кодові пункти з властивістю Nd).

   Повний список кодових пунктів з властивістю Nd див. у Стандарті Юнікоду.

Усі типи numbers.Real (int і float) також містять такі операції:

Операція	Результат
math.trunc(x)	x, усічене до Integral
round(x[, n])	x, округлене до n цифр, з округленням половини до парного числа. Якщо n опущено, за замовчанням дорівнює 0.
math.floor(x)	найбільший Integral <= x
math.ceil(x)	найменший Integral >= x

Для отримання додаткових числових операцій перегляньте модулі math і cmath.

Побітові операції над цілими типами

Побітові операції мають сенс лише для цілих чисел. Результат побітових операцій обчислюється так, ніби виконується в доповненні до двох із нескінченною кількістю знакових бітів.

Пріоритети двійкових побітових операцій нижчі, ніж числових операцій, і вищі, ніж порівняння; унарна операція ~ має той самий пріоритет, що й інші унарні числові операції (+ і -).

У цій таблиці наведено порозрядні операції, відсортовані за зростанням пріоритету:

Операція	Результат	Примітки
x | y	побітове або x і y	(4)
x ^ y	побітове виключне або x і y	(4)
x & y	побітове і x і y	(4)
x << n	x, зсунуте ліворуч на n бітів	(1)(2)
x >> n	x, зсунуте праворуч на n бітів	(1)(3)
~x	інвертовані біти x

Примітки:

1. Зсуви на від’ємне число є неприпустимим і викликає ValueError.

2. Зсув ліворуч на n бітів еквівалентний множенню на pow(2, n).

3. Зсув праворуч на n бітів еквівалентний діленню з округленням донизу на pow(2, n).

4. Виконання цих обчислень із принаймні одним додатковим бітом розширення знака в скінченному поданні доповнення до двох (робоча бітова ширина 1 + max(x.bit_length(), y.bit_length()) або більше) є достатньою для отримання того самого результату, що й для нескінченної кількості знакових бітів.

Додаткові методи для цілих типів

Тип int реалізує абстрактний базовий клас numbers.Integral. Крім того, він надає ще кілька методів:

int.bit_length()

Повертає кількість бітів, необхідних для представлення цілого числа в двійковій системі, за винятком знака та нулів на початку:

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

Точніше, якщо x відмінне від нуля, то x.bit_length() є унікальним натуральним числом k таким, що 2**(k-1) <= abs(x) < 2**k. Аналогічно, коли abs(x) достатньо малий, щоб мати правильно округлений логарифм, тоді k = 1 + int(log(abs(x), 2)). Якщо x дорівнює нулю, то x.bit_length() повертає 0.

Еквівалентне:

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

Повертає кількість одиниць у двійковому представленні абсолютного значення цілого числа. Приклад:

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

Еквівалентне:

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

Added in version 3.10.

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

Повертає масив байтів, що представляє ціле число.

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

Ціле число представляється за допомогою length байтів і за замовчуванням дорівнює 1. Якщо ціле число не може бути представлено заданою кількістю байтів, генерується виняток OverflowError

Аргумент byteorder визначає порядок байтів, що використовується для представлення цілого числа, і за замовчуванням дорівнює "big". Якщо byteorder дорівнює "big", найзначущий байт знаходиться на початку масиву байтів. Якщо byteorder дорівнює "little", найзначущий байт знаходиться в кінці масиву байтів

Аргумент signed визначає, чи використовується доповнення до двох для представлення цілого числа. Якщо signed дорівнює False і вказане від’ємне ціле число, генерується виняток OverflowError. Значенням за замовчуванням для signed є False.

Значення за замовчуванням зручно застосовувати для перетворення цілого числа в однобайтовий об’єкт:

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

Однак, використовуючи аргумент за замовчуванням, не намагайтеся перетворити значення, більші за 255, інакше ви отримаєте OverflowError.

Еквівалентне:

def to_bytes(n, довжина=1, byteorder='big', signed=False):
    if byteorder == 'little':
        order = range(довжина)
    elif byteorder == 'big':
        order = reversed(range(довжина))
    else:
        raise ValueError("порядок байт повинен бути або 'little' або 'big'")

    повертати bytes((n >> i*8) & 0xff для i в порядку)

Added in version 3.2.

Змінено в версії 3.11: Додано значення аргументів за замовчуванням для length та byteorder.

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

Повертає ціле число, представлене заданим масивом байтів.

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

Аргумент bytes має бути або байт-подібним об’єктом, або ітерабельним об’єктом, що створює байти.

Аргумент byteorder визначає порядок байтів, що використовується для представлення цілого числа, і за замовчуванням дорівнює "big". Якщо byteorder дорівнює "big", найзначущий байт знаходиться на початку масиву байтів. Якщо byteorder дорівнює "little", найзначущий байт знаходиться в кінці масиву байтів

Аргумент signed вказує, чи використовується доповнення до двох для представлення цілого числа.

Еквівалентне:

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.

Змінено в версії 3.11: Додано значення аргументу за замовчуванням byteorder.

int.as_integer_ratio()

Повертає пару цілих чисел, відношення яких дорівнює вихідному цілому числу і має додатний знаменник. Цілочисельне відношення цілих чисел завжди має ціле число у чисельнику та 1 у знаменнику.

Added in version 3.8.

int.is_integer()

Повертає True. Існує для сумісності за «качиною типізацією» з float.is_integer().

Added in version 3.12.

Додаткові методи для Float

Тип float реалізує numbers.Real абстрактний базовий клас. float також має такі додаткові методи.

float.as_integer_ratio()

Повертає пару цілих чисел, чиє співвідношення точно дорівнює вихідному числу з рухомою комою. Відношення спрощене і має додатний знаменник. Генерує OverflowError на нескінченностях та ValueError на NaN.

float.is_integer()

Повертає True, якщо екземпляр float є кінцевим із цілим значенням, і False інакше:

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

Два методи підтримують перетворення до та з шістнадцяткових рядків. Оскільки числа з плаваючою точкою Python зберігаються усередині як двійкові числа, перетворення числа з плаваючою точкою в десятковий рядок або з нього зазвичай включає невелику помилку округлення. Навпаки, шістнадцяткові рядки дозволяють точне представлення та специфікацію чисел з плаваючою комою. Це може бути корисним під час налагодження та чисельної роботи.

float.hex()

Повертає представлення числа з плаваючою комою як шістнадцятковий рядок. Для скінченних чисел з плаваючою комою це представлення завжди включатиме 0x на початку та p у кінці та експоненту.

classmethod float.fromhex(s)

Метод класу для повернення числа з плаваючою точкою, представленого шістнадцятковим рядком s. Рядок s може мати пробіли на початку та в кінці.

Зауважте, що float.hex() є методом екземпляра, тоді як float.fromhex() є методом класу.

Шістнадцятковий рядок має вигляд:

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

де необов’язковий знак може мати + або -, ціле число і дріб є рядками шістнадцяткових цифр, а експонента є десятковим цілим числом з необов’язковим переднім знаком. Регістр не є значущим, і в цілому чи дробі має бути принаймні одна шістнадцяткова цифра. Цей синтаксис подібний до синтаксису, зазначеного в розділі 6.4.4.2 стандарту C99, а також до синтаксису, який використовується в Java 1.5 і далі. Зокрема, вихід float.hex() можна використовувати як шістнадцятковий літерал із плаваючою комою в коді C або Java, а також шістнадцяткові рядки, створені символом формату C %a або Double.toHexString Java приймаються float.fromhex().

Зауважте, що експонента записується в десятковій, а не в шістнадцятковій формі, і що вона дає ступінь 2, на який потрібно помножити коефіцієнт. Наприклад, шістнадцятковий рядок 0x3.a7p10 представляє число з плаваючою комою (3 + 10./16 + 7./16**2) * 2.0**10 або 3740.0:

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

Застосування зворотного перетворення до 3740.0 дає інший шістнадцятковий рядок, що представляє те саме число:

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

Хешування числових типів

For numbers x and y, possibly of different types, it’s a requirement that hash(x) == hash(y) whenever x == y (see the __hash__() method documentation for more details). For ease of implementation and efficiency across a variety of numeric types (including int, float, decimal.Decimal and fractions.Fraction) Python’s hash for numeric types is based on a single mathematical function that’s defined for any rational number, and hence applies to all instances of int and fractions.Fraction, and all finite instances of float and decimal.Decimal. Essentially, this function is given by reduction modulo P for a fixed prime P. The value of P is made available to Python as the modulus attribute of sys.hash_info.

Деталі реалізації CPython: В даний час простим числом, яке використовується, є P = 2**31 - 1 на машинах з 32-розрядним C long і P = 2**61 - 1 на машинах з 64-бітним C long.

Ось правила в деталях:

• Якщо x = m / n є невід’ємним раціональним числом, а n не ділиться на P, визначте hash(x) як m * invmod(n, P ) % P``, де invmod(n, P) дає обернене n за модулем P.

• Якщо x = m / n є невід’ємним раціональним числом, а n ділиться на P (але m не ділиться на m), тоді n не має оберненого модуля``P`` і правило вище не застосовується; у цьому випадку визначте hash(x) як постійне значення sys.hash_info.inf.

• Якщо x = m / n є від’ємним раціональним числом, визначте hash(x) як -hash(-x). Якщо отриманий хеш дорівнює -1, замініть його -2.

• Конкретні значення sys.hash_info.inf і -sys.hash_info.inf використовуються як хеш-значення для позитивної нескінченності або негативної нескінченності (відповідно).

• Для complex числа z хеш-значення дійсної та уявної частин поєднуються шляхом обчислення hash(z.real) + sys.hash_info.imag * hash(z.imag), зменшено за модулем 2**sys.hash_info.width так, щоб він знаходився в діапазоні (-2**(sys.hash_info.width - 1), 2**(sys.hash_info.width - 1) )). Знову ж таки, якщо результат -1, він замінюється на -2.

Щоб прояснити наведені вище правила, ось приклад коду Python, еквівалентного вбудованому хешу, для обчислення хешу раціонального числа, float або 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

Boolean Type - bool

Booleans represent truth values. The bool type has exactly two constant instances: True and False.

The built-in function bool() converts any value to a boolean, if the value can be interpreted as a truth value (see section Перевірка значення на істинність above).

For logical operations, use the boolean operators and, or and not. When applying the bitwise operators &, |, ^ to two booleans, they return a bool equivalent to the logical operations «and», «or», «xor». However, the logical operators and, or and != should be preferred over &, | and ^.

Застаріло починаючи з версії 3.12: The use of the bitwise inversion operator ~ is deprecated and will raise an error in Python 3.16.

bool is a subclass of int (see Числові типи — int, float, complex). In many numeric contexts, False and True behave like the integers 0 and 1, respectively. However, relying on this is discouraged; explicitly convert using int() instead.

Типи ітераторів

Python підтримує концепцію ітерації над контейнерами. Це реалізується за допомогою двох різних методів; вони використовуються, щоб дозволити визначеним користувачем класам підтримувати ітерацію. Послідовності, описані нижче більш детально, завжди підтримують ітераційні методи.

Потрібно визначити один метод для об’єктів-контейнерів, щоб забезпечити підтримку iterable:

container.__iter__()

Повертає об’єкт iterator. Об’єкт повинен підтримувати описаний нижче протокол ітератора. Якщо контейнер підтримує різні типи ітерацій, можна надати додаткові методи для спеціального запиту ітераторів для цих типів ітерацій. (Прикладом об’єкта, що підтримує кілька форм ітерації, може бути деревоподібна структура, яка підтримує обхід як у ширину, так і в глибину.) Цей метод відповідає слоту tp_iter структури типу для об’єктів Python в API Python/C.

Самі об’єкти ітератора повинні підтримувати наступні два методи, які разом утворюють iterator protocol:

iterator.__iter__()

Повертає сам об’єкт iterator. Це потрібно, щоб дозволити використовувати як контейнери, так і ітератори з операторами for і in. Цей метод відповідає слоту tp_iter структури типу для об’єктів Python в API Python/C.

iterator.__next__()

Повертає наступний елемент із iterator. Якщо більше елементів немає, підніміть виняток StopIteration. Цей метод відповідає слоту tp_iternext структури типу для об’єктів Python в API Python/C.

Python визначає декілька об’єктів-ітераторів для підтримки ітерації загальних і конкретних типів послідовностей, словників та інших більш спеціалізованих форм. Конкретні типи не важливі за межами їхньої реалізації протоколу ітератора.

Коли метод __next__() ітератора викликає StopIteration, він повинен продовжувати робити це під час наступних викликів. Реалізації, які не підкоряються цій властивості, вважаються зламаними.

Типи генераторів

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.

Типи послідовностей — list, tuple, range

Існує три основні типи послідовностей: списки, кортежі та об’єкти діапазону. Додаткові типи послідовностей, призначені для обробки бінарних даних і текстових рядків, описані у спеціальних розділах.

Загальні операції послідовності

Операції в наведеній нижче таблиці підтримують більшість типів послідовностей, як змінних, так і незмінних. collections.abc.Sequence ABC надається, щоб спростити правильну реалізацію цих операцій у настроюваних типах послідовностей.

У цій таблиці наведено послідовність операцій, відсортованих за зростанням пріоритету. У таблиці s і t — послідовності одного типу, n, i, j і k — цілі числа, а x — довільний об’єкт, який відповідає будь-яким обмеженням щодо типу та значення накладений s.

Операції in і not in мають ті самі пріоритети, що й операції порівняння. Операції + (конкатенація) і * (повторення) мають той самий пріоритет, що й відповідні числові операції. [3]

Операція	Результат	Примітки
x в s	True, якщо елемент s дорівнює x, інакше False	(1)
x не в s	False, якщо елемент s дорівнює x, інакше True	(1)
s + t	конкатенація s і t	(6)(7)
s * n або n * s	еквівалентно додаванню s до самого себе n разів	(2)(7)
s[i]	iий елемент з s, джерело 0	(3)
s[i:j]	фрагмент s від i до j	(3)(4)
s[i:j:k]	фрагмент s від i до j з кроком k	(3)(5)
len(s)	довжина s
хв(и)	найменший елемент s
max(s)	найбільший предмет s
s.index(x[, i[, j]])	індекс першого входження x у s (за або після індексу i та перед індексом j)	(8)
s.count(x)	загальна кількість входжень x у s

Послідовності одного типу також підтримують порівняння. Зокрема, кортежі та списки порівнюються лексикографічно шляхом порівняння відповідних елементів. Це означає, що для порівняння однаково кожен елемент повинен порівнюватись рівно, а дві послідовності мають бути одного типу та мати однакову довжину. (Для отримання повної інформації див. Порівняння у мовній довідці.)

Прямі та зворотні ітератори над змінними послідовностями отримують доступ до значень за допомогою індексу. Цей індекс буде продовжувати рух вперед (або назад), навіть якщо базова послідовність змінена. Ітератор завершується лише тоді, коли зустрічається IndexError або StopIteration (або коли індекс падає нижче нуля).

Примітки:

1. У той час як операції in і not in використовуються лише для простого тестування локалізації в загальному випадку, деякі спеціалізовані послідовності (такі як str, bytes і bytearray) також використовуйте їх для тестування підпослідовності:

   >>> "gg" in "eggs"
   True
   

2. Значення n, менші за 0, розглядаються як 0 (що дає порожню послідовність того самого типу, що й s). Зверніть увагу, що елементи в послідовності s не копіюються; на них посилаються кілька разів. Це часто переслідує нових програмістів Python; розглянути:

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

   Сталося те, що [[]] є одноелементним списком, який містить порожній список, тому всі три елементи [[]] * 3 є посиланнями на цей єдиний порожній список. Зміна будь-якого з елементів списків змінює цей єдиний список. Ви можете створити список різних списків таким чином:

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

   Подальші пояснення доступні в розділі поширених запитань Як створити багатовимірний список?.

3. Якщо i або j є від’ємними, індекс відноситься до кінця послідовності s: замінюється len(s) + i або len(s) + j. Але зауважте, що -0 все одно 0.

4. Зріз s від i до j визначається як послідовність елементів з індексом k, така що i <= k < j. Якщо i або j більше ніж len(s), використовуйте len(s). Якщо i пропущено або None, використовуйте 0. Якщо j пропущено або None, використовуйте len(s). Якщо i більше або дорівнює j, фрагмент порожній.

5. Зріз s від i до j з кроком k визначається як послідовність елементів з індексом x = i + n*k так, що 0 <= n < (j-i )/k. Іншими словами, індекси i, i+k, i+2*k, i+3*k і так далі, зупиняючись, коли j є досягнуто (але ніколи не включаючи j). Коли k додатне, i і j скорочуються до len(s), якщо вони більші. Коли k від’ємне, i та j скорочуються до len(s) - 1, якщо вони більші. Якщо i або j пропущені або None, вони стають «кінцевими» значеннями (кінець залежить від знака k). Зауважте, k не може дорівнювати нулю. Якщо k має значення None, воно розглядається як 1.

6. Конкатенація незмінних послідовностей завжди призводить до нового об’єкта. Це означає, що створення послідовності шляхом повторної конкатенації матиме квадратичну вартість виконання в загальній довжині послідовності. Щоб отримати лінійну вартість роботи, ви повинні перейти до однієї з наведених нижче альтернатив:

   • якщо конкатенувати об’єкти str, ви можете створити список і використовувати str.join() наприкінці або записати в екземпляр io.StringIO і отримати його значення після завершення

   • якщо конкатенація об’єктів bytes, ви можете так само використовувати bytes.join() або io.BytesIO, або ви можете виконати конкатенацію на місці з об’єктом bytearray. Об’єкти bytearray є змінними та мають ефективний механізм загального розподілу

   • якщо конкатенація об’єктів tuple, замість цього розширте list

   • для інших типів дослідіть відповідну документацію класу

7. Деякі типи послідовностей (наприклад, range) підтримують лише послідовності елементів, які відповідають певним шаблонам, і, отже, не підтримують конкатенацію або повторення послідовності.

8. index викликає ValueError, коли x не знайдено в s. Не всі реалізації підтримують передачу додаткових аргументів i і j. Ці аргументи дозволяють здійснювати ефективний пошук підрозділів послідовності. Передача додаткових аргументів приблизно еквівалентна використанню s[i:j].index(x), тільки без копіювання будь-яких даних і з повернутим індексом відносно початку послідовності, а не початку фрагмента. .

Незмінні типи послідовностей

Єдина операція, яку зазвичай реалізують незмінні типи послідовностей, яка також не реалізована змінними типами послідовностей, це підтримка вбудованого hash().

Ця підтримка дозволяє використовувати незмінні послідовності, такі як екземпляри tuple, як ключі dict і зберігати їх у екземплярах set і frozenset.

Спроба хешувати незмінну послідовність, яка містить нехешовані значення, призведе до TypeError.

Змінні типи послідовностей

Операції в наведеній нижче таблиці визначено для змінних типів послідовностей. collections.abc.MutableSequence ABC надається, щоб спростити правильну реалізацію цих операцій у настроюваних типах послідовностей.

У таблиці s є екземпляром змінного типу послідовності, t є будь-яким ітерованим об’єктом, а x є довільним об’єктом, який відповідає будь-яким обмеженням типу та значення, накладеним s (наприклад, bytearray приймає лише цілі числа, які відповідають обмеженню значення 0 <= x <= 255).

Операція	Результат	Примітки
s[i] = x	пункт i з s замінено на x
s[i:j] = t	фрагмент s від i до j замінюється вмістом ітерованого t
del s[i:j]	те саме, що s[i:j] = []
s[i:j:k] = t	елементи s[i:j:k] замінюються на елементи t	(1)
del s[i:j:k]	видаляє елементи s[i:j:k] зі списку
s.append(x)	додає x до кінця послідовності (те саме, що s[len(s):len(s)] = [x])
s.clear()	видаляє всі елементи з s (те саме, що del s[:])	(5)
s.copy()	створює поверхневу копію s (те саме, що s[:])	(5)
s.extend(t) або s += t	розширює s вмістом t (здебільшого те саме, що s[len(s):len(s)] = t)
s *= n	оновлює s з повторенням його вмісту n разів	(6)
s.insert(i, x)	вставляє x в s за індексом, заданим i (те саме, що s[i:i] = [x])
s.pop() або s.pop(i)	отримує елемент у i, а також видаляє його з s	(2)
s.remove(x)	removes the first item from s where s[i] is equal to x	(3)
s.reverse()	перевертає елементи s на місце	(4)

Примітки:

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

2. Необов’язковий аргумент i за умовчанням має значення -1, тому за замовчуванням останній елемент видаляється та повертається.

3. remove() викликає ValueError, коли x не знайдено в s.

4. Метод reverse() змінює поточну послідовність для економії простору під час реверсування великої послідовності. Щоб нагадати користувачам, що він працює за побічним ефектом, він не повертає зворотну послідовність.

5. clear() і copy() включено для узгодженості з інтерфейсами змінних контейнерів, які не підтримують операції зрізання (таких як dict і set). copy() не є частиною collections.abc.MutableSequence ABC, але більшість конкретних змінних класів послідовності надають його.

   Added in version 3.3: Методи clear() і copy().

6. Значення n є цілим числом або об’єктом, що реалізує __index__(). Нульові та негативні значення n очищають послідовність. Елементи послідовності не копіюються; на них посилаються кілька разів, як пояснюється для s * n у Загальні операції послідовності.

списки

Списки — це змінювані послідовності, які зазвичай використовуються для зберігання колекцій однорідних елементів (де точний ступінь подібності залежить від програми).

class list([iterable])

Списки можна створювати кількома способами:

• Використання пари квадратних дужок для позначення порожнього списку: []

• Використовуючи квадратні дужки, розділяючи елементи комами: [a], [a, b, c]

• Використання розуміння списку: [x for x in iterable]

• Використання конструктора типу: list() або list(iterable)

Конструктор створює список, елементи якого є такими ж і в тому ж порядку, що й елементи iterable. iterable може бути або послідовністю, контейнером, який підтримує ітерацію, або об’єктом ітератора. Якщо iterable вже є списком, копія створюється та повертається, подібно до iterable[:]. Наприклад, list('abc') повертає ['a', 'b', 'c'], а list( (1, 2, 3) ) повертає [ 1, 2, 3]. Якщо аргумент не задано, конструктор створює новий порожній список, [].

Багато інших операцій також створюють списки, включаючи вбудовану sorted().

Списки реалізують усі common і mutable операції послідовності. Списки також надають наступний додатковий метод:

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

Цей метод сортує список на місці, використовуючи лише < порівняння між елементами. Винятки не пригнічуються — якщо будь-яка операція порівняння завершиться невдало, вся операція сортування буде невдалою (і список, ймовірно, залишиться в частково зміненому стані).

sort() приймає два аргументи, які можуть бути передані лише ключовим словом (аргументи лише для ключових слів):

key визначає функцію одного аргументу, яка використовується для отримання ключа порівняння з кожного елемента списку (наприклад, key=str.lower). Ключ, що відповідає кожному елементу в списку, обчислюється один раз, а потім використовується для всього процесу сортування. Значення за замовчуванням «Немає» означає, що елементи списку сортуються безпосередньо без обчислення окремого значення ключа.

Утиліта functools.cmp_to_key() доступна для перетворення функції cmp у стилі 2.x на функцію key.

reverse — це логічне значення. Якщо встановлено значення True, елементи списку сортуються так, ніби кожне порівняння було зворотним.

Цей метод змінює наявну послідовність для економії простору під час сортування великої послідовності. Щоб нагадати користувачам, що він працює за побічним ефектом, він не повертає відсортовану послідовність (використовуйте sorted(), щоб явно запитати новий екземпляр відсортованого списку).

Метод sort() гарантовано буде стабільним. Сортування є стабільним, якщо воно гарантує відсутність зміни відносного порядку порівнюваних рівних елементів — це корисно для сортування за кілька проходів (наприклад, сортування за відділом, а потім за ступенем зарплати).

Приклади сортування та короткий посібник із сортування див. Sorting Techniques.

Деталі реалізації CPython: Поки список сортується, ефект від спроби змінити або навіть перевірити список не визначено. Реалізація Python на C робить список порожнім протягом певного часу та викликає ValueError, якщо він може виявити, що список було змінено під час сортування.

Кортежі

Кортежі — це незмінні послідовності, які зазвичай використовуються для зберігання колекцій різнорідних даних (таких як 2-кортежі, створені за допомогою вбудованої функції enumerate()). Кортежі також використовуються у випадках, коли потрібна незмінна послідовність однорідних даних (наприклад, дозволити зберігання в екземплярі set або dict).

class tuple([iterable])

Кортежі можна побудувати кількома способами:

• Використання пари круглих дужок для позначення порожнього кортежу: ()

• Використання кінцевої коми для одноэлементного кортежу: a, або (a,)

• Розділення елементів комами: a, b, c або (a, b, c)

• Використання вбудованого tuple(): tuple() або tuple(iterable)

Конструктор будує кортеж, елементи якого є такими ж і в тому ж порядку, що й елементи iterable. iterable може бути або послідовністю, контейнером, який підтримує ітерацію, або об’єктом ітератора. Якщо iterable вже є кортежем, він повертається без змін. Наприклад, tuple('abc') повертає ('a', 'b', 'c'), tuple( [1, 2, 3] ) повертає ( 1, 2, 3). Якщо аргумент не задано, конструктор створює новий порожній кортеж ().

Зауважте, що насправді кома створює кортеж, а не круглі дужки. Дужки необов’язкові, за винятком порожнього кортежу або коли вони потрібні для уникнення синтаксичної неоднозначності. Наприклад, «f(a, b, c)» — це виклик функції з трьома аргументами, тоді як «f((a, b, c))» — це виклик функції з 3-кортежем як єдиним аргумент.

Кортежі реалізують усі загальні операції послідовності.

Для різнорідних колекцій даних, де доступ за іменем є зрозумілішим, ніж доступ за індексом, collections.namedtuple() може бути більш відповідним вибором, ніж простий об’єкт кортежу.

діапазони

Тип range представляє незмінну послідовність чисел і зазвичай використовується для повторення певної кількості разів у циклах for.

class range(stop)

class range(start, stop[, step])

Аргументи конструктора діапазону мають бути цілими числами (або вбудованим int, або будь-яким об’єктом, який реалізує спеціальний метод __index__()). Якщо аргумент step опущено, за умовчанням він дорівнює 1. Якщо аргумент початок опущено, за умовчанням він дорівнює 0. Якщо крок дорівнює нулю, виникає ValueError.

Для позитивного кроку вміст діапазону r визначається за формулою r[i] = start + step*i, де i >= 0 і r[ i] < stop.

Для від’ємного кроку вміст діапазону все ще визначається формулою r[i] = start + step*i, але обмеження i >= 0 і r[ i] > stop.

Об’єкт діапазону буде порожнім, якщо r[0] не відповідає обмеженню значення. Діапазони підтримують негативні індекси, але вони інтерпретуються як індексування з кінця послідовності, визначеної позитивними індексами.

Діапазони, що містять абсолютні значення, більші за sys.maxsize, дозволені, але деякі функції (такі як len()) можуть викликати OverflowError.

Приклади асортименту:

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

Діапазони реалізують усі загальні операції послідовності, окрім конкатенації та повторення (через те, що об’єкти діапазону можуть представляти лише послідовності, які дотримуються строгого шаблону, а повторення та конкатенація зазвичай порушують цей шаблон).

start

Значення параметра start (або 0, якщо параметр не було надано)

stop

Значення параметра stop

step

Значення параметра step (або 1, якщо параметр не було надано)

Перевага типу range перед звичайним list або tuple полягає в тому, що об’єкт range завжди займатиме однаковий (невеликий) обсяг пам’яті, ні не має значення розмір діапазону, який він представляє (оскільки він зберігає лише значення start, stop і step, обчислюючи окремі елементи та піддіапазони за потреби).

Об’єкти діапазону реалізують collections.abc.Sequence ABC і надають такі функції, як тести на обмеження, пошук індексу елемента, нарізка та підтримка негативних індексів (див. Типи послідовностей — 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

Перевірка об’єктів діапазону на рівність за допомогою == і != порівнює їх як послідовності. Тобто два об’єкти діапазону вважаються рівними, якщо вони представляють однакову послідовність значень. (Зверніть увагу, що два об’єкти діапазону, які порівнюються, можуть мати різні атрибути start, stop і step, наприклад range(0 ) == діапазон(2, 1, 3) або діапазон(0, 3, 2) == діапазон(0, 4, 2).)

Змінено в версії 3.2: Реалізуйте послідовність ABC. Підтримка нарізки та негативних індексів. Перевіряйте об’єкти int на приналежність у постійному часі замість повторення всіх елементів.

Змінено в версії 3.3: Визначте «==» і «!=», щоб порівнювати об’єкти діапазону на основі послідовності значень, які вони визначають (замість порівняння на основі ідентичності об’єкта).

Added the start, stop and step attributes.

Дивись також

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

Тип текстової послідовності — str

Текстові дані в Python обробляються за допомогою об’єктів str або strings. Рядки є незмінними послідовностями кодових точок Unicode. Рядкові літерали записуються різними способами:

• Одинарні лапки: 'дозволяє вбудовані "подвійні" лапки'

• Подвійні лапки: "дозволяє вбудовані 'одинарні' лапки"

• Потрійні лапки: ''Три одинарні лапки'''', """Три подвійні лапки"""

Рядки з потрійними лапками можуть охоплювати кілька рядків - усі пов’язані пробіли будуть включені в рядковий літерал.

Рядкові літерали, які є частиною одного виразу і мають лише пробіли між собою, будуть неявно перетворені в один рядковий літерал. Тобто ("спам " "яйця") == "спам яйця".

See Рядкові та байтові літерали for more about the various forms of string literal, including supported escape sequences, and the r («raw») prefix that disables most escape sequence processing.

Рядки також можна створювати з інших об’єктів за допомогою конструктора str.

Оскільки окремого типу «символів» немає, індексування рядка створює рядки довжиною 1. Тобто для непорожнього рядка s s[0] == s[0:1].

Також немає змінного типу рядка, але str.join() або io.StringIO можна використовувати для ефективного створення рядків із кількох фрагментів.

Змінено в версії 3.3: Для зворотної сумісності з серією Python 2 префікс u знову дозволений у рядкових літералах. Він не впливає на значення рядкових літералів і не може поєднуватися з префіксом r.

class str(object='')

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

Повертає string версію об’єкта. Якщо object не надано, повертає порожній рядок. В іншому випадку поведінка str() залежить від того, чи вказано кодування чи помилки, як показано нижче.

If neither encoding nor errors is given, str(object) returns type(object).__str__(object), which is the «informal» or nicely printable string representation of object. For string objects, this is the string itself. If object does not have a __str__() method, then str() falls back to returning repr(object).

Якщо вказано принаймні одну з кодування або помилок, об’єкт має бути bytes-like object (наприклад, bytes або bytearray). У цьому випадку, якщо object є об’єктом bytes (або bytearray), тоді str(bytes, encoding, errors) еквівалентно bytes.decode (кодування, помилки). В іншому випадку об’єкт bytes, що лежить в основі об’єкта буфера, отримується перед викликом bytes.decode(). Перегляньте Типи бінарних послідовностей — bytes, bytearray, memoryview і Буферний протокол для отримання інформації про буферні об’єкти.

Передача об’єкта bytes до str() без аргументів encoding або errors підпадає під перший випадок повернення неформального представлення рядка (див. також команду -b- рядок для Python). Наприклад:

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

Додаткову інформацію про клас str і його методи див. у розділі Тип текстової послідовності — str і Рядкові методи нижче. Щоб вивести форматовані рядки, перегляньте розділи f-strings і Синтаксис рядка формату. Крім того, перегляньте розділ Послуги обробки тексту.

Рядкові методи

Рядки реалізують усі загальні операції послідовності разом із додатковими методами, описаними нижче.

Рядки також підтримують два стилі форматування рядків: один забезпечує велику гнучкість і налаштування (див. str.format(), Синтаксис рядка формату і Спеціальне форматування рядків), а інший базується на Форматування стилю C printf, яке обробляє вужчий діапазон типів і трохи важче правильно використовувати, але часто швидше для випадків, які воно може обробляти (Форматування рядків у стилі printf).

Розділ Послуги обробки тексту стандартної бібліотеки охоплює низку інших модулів, які надають різноманітні утиліти, пов’язані з текстом (зокрема підтримку регулярних виразів у модулі re).

str.capitalize()

Повертає копію рядка з великим першим символом, а решта малими.

Змінено в версії 3.8: Перший символ тепер вводиться в заголовок, а не у верхній регістр. Це означає, що такі символи, як диграфи, матимуть велику першу літеру, а не повний символ.

str.casefold()

Повертає згорнуту копію рядка. Для зіставлення без регістру можна використовувати рядки з регістром.

Згортання регістру подібне до нижнього регістру, але більш агресивне, оскільки воно призначене для видалення всіх відмінностей регістру в рядку. Наприклад, німецька мала літера 'ß' еквівалентна "ss". Оскільки це вже малий регістр, lower() нічого не зробить для 'ß'; casefold() перетворює його на "ss".

The casefolding algorithm is described in section 3.13 „Default Case Folding“ of the Unicode Standard.

Added in version 3.3.

str.center(width[, fillchar])

Повернення з центром у рядку довжиною width. Заповнення виконується за допомогою вказаного fillchar (за замовчуванням це пробіл ASCII). Оригінальний рядок повертається, якщо width менше або дорівнює len(s).

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

Повертає кількість неперекриваючих входжень підрядка sub у діапазоні [початок, кінець]. Необов’язкові аргументи початок і кінець інтерпретуються як у нотації фрагментів.

If sub is empty, returns the number of empty strings between characters which is the length of the string plus one.

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

Return the string encoded to bytes.

encoding defaults to 'utf-8'; see Стандартні кодування for possible values.

errors controls how encoding errors are handled. If 'strict' (the default), a UnicodeError exception is raised. Other possible values are 'ignore', 'replace', 'xmlcharrefreplace', 'backslashreplace' and any other name registered via codecs.register_error(). See Обробники помилок for details.

For performance reasons, the value of errors is not checked for validity unless an encoding error actually occurs, Режим розробки Python is enabled or a debug build is used.

Змінено в версії 3.1: Додано підтримку аргументів ключових слів.

Змінено в версії 3.9: The value of the errors argument is now checked in Режим розробки Python and in debug mode.

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

Повертає True, якщо рядок закінчується вказаним суфіксом, інакше повертає False. suffix також може бути кортежем суфіксів для пошуку. З необов’язковим початком тестування починається з цієї позиції. З необов’язковим end, припинити порівняння на цій позиції.

str.expandtabs(tabsize=8)

Повертає копію рядка, де всі символи табуляції замінені одним або кількома пробілами, залежно від поточного стовпця та заданого розміру табуляції. Позиції табуляції відбуваються з кожним символом tabsize (за замовчуванням — 8, надаючи позиції табуляції в стовпцях 0, 8, 16 тощо). Щоб розгорнути рядок, поточний стовпець встановлюється на нуль, а рядок перевіряється символ за символом. Якщо символ є табуляцією (\t), один або кілька символів пробілу вставляються в результат, доки поточний стовпець не зрівняється з позицією наступної табуляції. (Сам символ табуляції не копіюється.) Якщо символ є символом нового рядка (\n) або повернення (\r), він копіюється, а поточний стовпець скидається до нуля. Будь-який інший символ копіюється без змін, а поточний стовпець збільшується на одиницю незалежно від того, як символ представлено під час друку.

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

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

Повертає найнижчий індекс у рядку, де підрядок sub знайдено в фрагменті s[start:end]. Необов’язкові аргументи початок і кінець інтерпретуються як у нотації фрагментів. Повертає -1, якщо sub не знайдено.

Примітка

Метод find() слід використовувати, лише якщо вам потрібно знати позицію sub. Щоб перевірити, чи є sub підрядком, скористайтеся оператором in:

>>> 'Py' in 'Python'
True

str.format(*args, **kwargs)

Виконайте операцію форматування рядка. Рядок, у якому викликається цей метод, може містити літеральний текст або поля заміни, розділені дужками {}. Кожне поле заміни містить або числовий індекс позиційного аргументу, або назву ключового аргументу. Повертає копію рядка, де кожне поле заміни замінено рядковим значенням відповідного аргументу.

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

Перегляньте Синтаксис рядка формату для опису різних параметрів форматування, які можна вказати в рядках формату.

Примітка

Під час форматування числа (int, float, complex, decimal.Decimal і підкласів) із типом n (наприклад: '{:n}'.format(1234), функція тимчасово встановлює локаль LC_CTYPE на мову LC_NUMERIC для декодування полів decimal_point і thousands_sep localeconv(), якщо вони не є ASCII або довші за 1 байт, а локаль LC_NUMERIC відрізняється від локалі LC_CTYPE. Ця тимчасова зміна впливає на інші потоки.

Змінено в версії 3.7: Під час форматування числа за допомогою типу n, у деяких випадках функція тимчасово встановлює LC_CTYPE локаль LC_NUMERIC.

str.format_map(mapping, /)

Подібно до str.format(**mapping), за винятком того, що mapping використовується безпосередньо, а не копіюється в dict. Це корисно, якщо, наприклад, mapping є підкласом 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]])

Як find(), але викликає ValueError, коли підрядок не знайдено.

str.isalnum()

Повертає True, якщо всі символи в рядку є буквено-цифровими і є принаймні один символ, False інакше. Символ c є буквено-цифровим, якщо одне з наступного повертає True: c.isalpha(), c.isdecimal(), c.isdigit() або c.isnumeric().

str.isalpha()

Return True if all characters in the string are alphabetic and there is at least one character, False otherwise. Alphabetic characters are those characters defined in the Unicode character database as «Letter», i.e., those with general category property being one of «Lm», «Lt», «Lu», «Ll», or «Lo». Note that this is different from the Alphabetic property defined in the section 4.10 „Letters, Alphabetic, and Ideographic“ of the Unicode Standard.

str.isascii()

Повертає True, якщо рядок порожній або всі символи в рядку є ASCII, False інакше. Символи ASCII мають кодові точки в діапазоні U+0000-U+007F.

Added in version 3.7.

str.isdecimal()

Повертає True, якщо всі символи в рядку є десятковими символами і є принаймні один символ, False інакше. Десяткові символи – це ті, які можна використовувати для утворення чисел за основою 10, напр. U+0660, АРАБСЬКО-ІНДІЙСЬКА ЦИФРА НУЛЬ. Формально десятковий символ — це символ у загальній категорії Unicode «Nd».

str.isdigit()

Повертає True, якщо всі символи в рядку є цифрами і є принаймні один символ, False інакше. Цифри включають десяткові символи та цифри, які потребують спеціальної обробки, наприклад цифри сумісності над індексом. Це охоплює цифри, які не можна використовувати для формування чисел з основою 10, як-от числа Харості. Формально цифра — це символ, який має значення властивості Numeric_Type=Digit або Numeric_Type=Decimal.

str.isidentifier()

Повертає True, якщо рядок є дійсним ідентифікатором відповідно до визначення мови, розділ Ідентифікатори та ключові слова.

keyword.iskeyword() can be used to test whether string s is a reserved identifier, such as def and class.

Приклад:

>>> from keyword import iskeyword

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

str.islower()

Повертає True, якщо всі символи регістру [4] в рядку є малими і є принаймні один символ регістру, False інакше.

str.isnumeric()

Повертає True, якщо всі символи в рядку є цифровими символами, і є принаймні один символ, False інакше. Цифрові символи включають цифрові символи та всі символи, які мають властивість числового значення Unicode, напр. U+2155, ВУЛЬГАРНА ФРАКЦІЯ ОДНА П’ЯТА. Формально цифровими символами є символи зі значенням властивості Numeric_Type=Digit, Numeric_Type=Decimal або Numeric_Type=Numeric.

str.isprintable()

Повертає True, якщо всі символи в рядку можна надрукувати або рядок порожній, False інакше. Символи, що не друкуються, — це символи, визначені в базі даних символів Unicode як «Інші» або «Розділювачі», за винятком пробілу ASCII (0x20), який вважається придатним для друку. (Зауважте, що друковані символи в цьому контексті – це ті символи, які не слід екранувати, коли repr() викликається в рядку. Це не впливає на обробку рядків, записаних у sys.stdout або sys.stderr.)

str.isspace()

Повертає True, якщо в рядку є лише пробіли та є принаймні один символ, False інакше.

Символ є пробілом, якщо в базі даних символів Unicode (див. unicodedata) або його загальна категорія Zs («Роздільник, пробіл»), або його двонаправлений клас є одним із WS, B або S.

str.istitle()

Повертає True, якщо рядок є рядком із заголовком і містить принаймні один символ, наприклад, символи верхнього регістру можуть слідувати лише за символами без регістру, а символи нижнього регістру – лише за символами в регістрі. В іншому випадку поверніть False.

str.isupper()

Повертає True, якщо всі символи регістру [4] в рядку є верхніми і є принаймні один символ регістру, False інакше.

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

str.join(iterable)

Повертає рядок, який є конкатенацією рядків у iterable. Помилка TypeError буде викликана, якщо в iterable є будь-які нерядкові значення, включаючи об’єкти bytes. Роздільником між елементами є рядок, що забезпечує цей метод.

str.ljust(width[, fillchar])

Повертає рядок, вирівняний за лівим краєм, у рядку довжини width. Заповнення виконується за допомогою вказаного fillchar (за замовчуванням це пробіл ASCII). Оригінальний рядок повертається, якщо width менше або дорівнює len(s).

str.lower()

Повертає копію рядка з усіма регістровими символами [4], перетвореними на нижній регістр.

The lowercasing algorithm used is described in section 3.13 „Default Case Folding“ of the Unicode Standard.

str.lstrip([chars])

Повертає копію рядка з видаленими початковими символами. Аргумент chars — це рядок, який визначає набір символів, які потрібно видалити. Якщо пропущено або None, аргумент chars за умовчанням видаляє пробіли. Аргумент chars не є префіксом; навпаки, усі комбінації його значень видаляються:

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

Перегляньте str.removeprefix() для методу, який видаляє один рядок префікса, а не весь набір символів. Наприклад:

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

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

Цей статичний метод повертає таблицю перекладу, яку можна використовувати для str.translate().

Якщо є лише один аргумент, це має бути словник, який відображає порядкові номери Unicode (цілі числа) або символи (рядки довжиною 1) на порядкові номери Unicode, рядки (довільної довжини) або None. Потім символьні ключі будуть перетворені на порядкові.

Якщо є два аргументи, вони мають бути рядками однакової довжини, і в отриманому словнику кожен символ у x буде зіставлено зі символом у тій же позиції в y. Якщо є третій аргумент, це має бути рядок, символи якого будуть зіставлені на None у результаті.

str.partition(sep)

Розділіть рядок при першому входженні sep і поверніть 3-кортеж, що містить частину перед роздільником, сам роздільник і частину після роздільника. Якщо роздільник не знайдено, поверніть 3-кортеж, що містить сам рядок, а потім два порожні рядки.

str.removeprefix(prefix, /)

Якщо рядок починається з рядка prefix, поверніть string[len(prefix):]. В іншому випадку поверніть копію оригінального рядка:

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

Added in version 3.9.

str.removesuffix(suffix, /)

Якщо рядок закінчується рядком suffix і цей suffix не є порожнім, поверніть string[:-len(suffix)]. В іншому випадку поверніть копію оригінального рядка:

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

Added in version 3.9.

str.replace(old, new, count=-1)

Return a copy of the string with all occurrences of substring old replaced by new. If count is given, only the first count occurrences are replaced. If count is not specified or -1, then all occurrences are replaced.

Змінено в версії 3.13: count is now supported as a keyword argument.

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

Повертає найвищий індекс у рядку, де знайдено підрядок sub, так що sub міститься в s[start:end]. Необов’язкові аргументи початок і кінець інтерпретуються як у нотації фрагментів. Повернути -1 у разі помилки.

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

Подібно до rfind(), але викликає ValueError, коли підрядок sub не знайдено.

str.rjust(width[, fillchar])

Повертає рядок, вирівняний по правому краю, у рядку довжини width. Заповнення виконується за допомогою вказаного fillchar (за замовчуванням це пробіл ASCII). Оригінальний рядок повертається, якщо width менше або дорівнює len(s).

str.rpartition(sep)

Розділіть рядок на останнє входження sep і поверніть 3-кортеж, що містить частину перед роздільником, сам роздільник і частину після роздільника. Якщо роздільник не знайдено, поверніть 3-кортеж, що містить два порожні рядки, а потім сам рядок.

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

Повертає список слів у рядку, використовуючи sep як роздільник. Якщо задано maxsplit, виконується щонайбільше maxsplit розбиття, найправіші. Якщо sep не вказано або None, будь-який пробільний рядок є роздільником. За винятком розділення справа, rsplit() поводиться як split(), що детально описано нижче.

str.rstrip([chars])

Повертає копію рядка з видаленими кінцевими символами. Аргумент chars — це рядок, який визначає набір символів, які потрібно видалити. Якщо пропущено або None, аргумент chars за умовчанням видаляє пробіли. Аргумент chars не є суфіксом; навпаки, усі комбінації його значень видаляються:

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

Перегляньте str.removesuffix() для методу, який видаляє один рядок суфікса, а не весь набір символів. Наприклад:

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

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

Повертає список слів у рядку, використовуючи sep як роздільник. Якщо вказано maxsplit, виконується щонайбільше maxsplit розбиття (отже, список міститиме щонайбільше елементів maxsplit+1). Якщо maxsplit не вказано або -1, тоді немає обмеження на кількість розділень (виконуються всі можливі розділення).

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

Наприклад:

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

Якщо sep не вказано або має значення None, застосовується інший алгоритм поділу: цикли послідовних пробілів розглядаються як один роздільник, і результат не міститиме порожніх рядків на початку або в кінці, якщо рядок має пробіли на початку або в кінці. Отже, розділення порожнього рядка або рядка, що складається лише з пробілів, за допомогою розділювача None повертає [].

Наприклад:

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

Повертає список рядків у рядку, розриваючи межі рядків. Розриви рядків не включаються в результуючий список, якщо keepends не задано і не відповідає дійсності.

Цей метод розбивається на наступні межі рядків. Зокрема, межі є надмножиною universal newlines.

Представництво	опис
\n	Переведення рядка
\r	Повернення каретки
\r\n	Повернення каретки + Переведення рядка
\v або \x0b	Лінія табуляції
\f або \x0c	Подача форми
\x1c	Роздільник файлів
\x1d	Роздільник груп
\x1e	Розділювач записів
\x85	Наступний рядок (контрольний код C1)
\u2028	Розділювач рядків
\u2029	Роздільник абзаців

Змінено в версії 3.2: \v і \f додано до списку меж ліній.

Наприклад:

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

На відміну від split(), коли задано рядок роздільника sep, цей метод повертає порожній список для порожнього рядка, а розрив кінцевого рядка не призводить до додаткового рядка:

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

Для порівняння split('\n') дає:

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

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

Повертає True, якщо рядок починається з префікса, інакше повертає False. префікс також може бути кортежем префіксів для пошуку. З необов’язковим початком, тестовий рядок починається з цієї позиції. З необов’язковим end припиняє порівнювати рядок у цій позиції.

str.strip([chars])

Повертає копію рядка з видаленими початковими та кінцевими символами. Аргумент chars — це рядок, який визначає набір символів, які потрібно видалити. Якщо пропущено або None, аргумент chars за умовчанням видаляє пробіли. Аргумент chars не є префіксом або суфіксом; навпаки, усі комбінації його значень видаляються:

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

Зовнішні початкові та кінцеві значення аргументів chars видаляються з рядка. Символи видаляються з початку, доки не досягнеться символ рядка, який не міститься в наборі символів у chars. Подібна дія відбувається на кінці. Наприклад:

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

str.swapcase()

Повертає копію рядка з символами верхнього регістру, перетвореними на малі, і навпаки. Зауважте, що s.swapcase().swapcase() == s не обов’язково правда.

str.title()

Повертає версію рядка в заголовку, де слова починаються з великої літери, а решта символів – нижніми.

Наприклад:

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

Алгоритм використовує просте незалежне від мови визначення слова як групи послідовних букв. Визначення працює в багатьох контекстах, але це означає, що апостроф у скороченнях і присвійних формах формує межі слів, що може бути не бажаним результатом:

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

Функція string.capwords() не має цієї проблеми, оскільки вона розділяє слова лише на пробіли.

Крім того, обхідний шлях для апострофів можна створити за допомогою регулярних виразів:

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

Return a copy of the string in which each character has been mapped through the given translation table. The table must be an object that implements indexing via __getitem__(), typically a mapping or sequence. When indexed by a Unicode ordinal (an integer), the table object can do any of the following: return a Unicode ordinal or a string, to map the character to one or more other characters; return None, to delete the character from the return string; or raise a LookupError exception, to map the character to itself.

Ви можете використовувати str.maketrans(), щоб створити карту перекладу з відображень символів у різні формати.

Перегляньте також модуль codecs для більш гнучкого підходу до нестандартних відображень символів.

str.upper()

Повертає копію рядка з усіма символами [4], перетвореними на верхній регістр. Зауважте, що s.upper().isupper() може мати значення False, якщо s містить символи без регістру або якщо категорія Юнікоду результуючих символів не є «Lu» (літера , верхній регістр), але напр. «Lt» (літера, регістр).

The uppercasing algorithm used is described in section 3.13 „Default Case Folding“ of the Unicode Standard.

str.zfill(width)

Поверніть копію рядка зліва, заповненого цифрами ASCII '0'', щоб отримати рядок довжини width. Початковий префікс знака ('+'/'-') обробляється шляхом вставки заповнення після символу знака, а не перед ним. Оригінальний рядок повертається, якщо width менше або дорівнює len(s).

Наприклад:

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

Форматування рядків у стилі printf

Примітка

Операції форматування, описані тут, демонструють різноманітні особливості, які призводять до низки поширених помилок (наприклад, неправильне відображення кортежів і словників). Використання нових відформатованих рядкових літералів, інтерфейсу str.format() або шаблонних рядків може допомогти уникнути цих помилок. Кожна з цих альтернатив забезпечує власні компроміси та переваги простоти, гнучкості та/або розширюваності.

String objects have one unique built-in operation: the % operator (modulo). This is also known as the string formatting or interpolation operator. Given format % values (where format is a string), % conversion specifications in format are replaced with zero or more elements of values. The effect is similar to using the sprintf() function in the C language. For example:

>>> print('%s has %d quote types.' % ('Python', 2))
Python has 2 quote types.

Якщо для format потрібен один аргумент, values може бути одним некортежним об’єктом. [5] В іншому випадку values має бути кортежем із точною кількістю елементів, визначених рядком формату, або одним об’єктом відображення (наприклад, словником).

Специфікатор перетворення містить два або більше символів і має наступні компоненти, які мають відображатися в такому порядку:

1. Символ '%', який позначає початок специфікатора.

2. Ключ відображення (необов’язковий), що складається з послідовності символів у дужках (наприклад, (якесь ім’я)).

3. Прапорці перетворення (опціонально), які впливають на результат деяких типів перетворення.

4. Мінімальна ширина поля (опціонально). Якщо вказано як '*' (зірочка), фактична ширина зчитується з наступного елемента кортежу в значеннях, а об’єкт для перетворення йде після мінімальної ширини поля та необов’язкової точності.

5. Точність (необов’язкова), подається як '.' (крапка), за якою йде точність. Якщо вказано як '*' (зірочка), фактична точність зчитується з наступного елемента кортежу в значеннях, а значення для перетворення йде після точності.

6. Модифікатор довжини (необов’язково).

7. Тип перетворення.

Якщо правильний аргумент є словником (або іншим типом відображення), то формати в рядку мають містити ключ відображення в дужках у цьому словнику, вставлений одразу після символу '%'. Ключ відображення вибирає значення, яке потрібно відформатувати, із відображення. Наприклад:

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

У цьому випадку у форматі не може бути специфікаторів * (оскільки вони вимагають послідовного списку параметрів).

Символи прапора перетворення:

Прапор	Значення
'#''	Перетворення значень використовуватиме «альтернативну форму» (де визначено нижче).
'0'	Перетворення буде доповнено нулем для числових значень.
'-'	Перетворене значення коригується зліва (перевизначає перетворення '0', якщо подано обидва значення).
' '	(пробіл) Пробіл слід залишити перед додатним числом (або порожнім рядком), утвореним перетворенням зі знаком.
'+'	Символ знака ('+' або '-') передуватиме перетворенню (перевизначає позначку «пробіл»).

Модифікатор довжини (h, l або L) може бути присутнім, але він ігнорується, оскільки він не є необхідним для Python - так, напр. %ld ідентичний %d.

Типи перетворення:

Перетворення	Значення	Примітки
'd''	Ціле десяткове число зі знаком.
'я''	Ціле десяткове число зі знаком.
'o'	Вісімкове значення зі знаком.	(1)
'u''	Застарілий тип – він ідентичний 'd'.	(6)
'x''	Шістнадцяткове число зі знаком (нижній регістр).	(2)
'X''	Шістнадцяткове число зі знаком (верхній регістр).	(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''	Один символ (приймає рядок цілих чи односимвольних символів).
'r''	Рядок (перетворює будь-який об’єкт Python за допомогою repr()).	(5)
's''	Рядок (перетворює будь-який об’єкт Python за допомогою str()).	(5)
'a'	Рядок (перетворює будь-який об’єкт Python за допомогою ascii()).	(5)
'%'	Жоден аргумент не перетворюється, результатом є символ '%' в результаті.

Примітки:

1. Альтернативна форма призводить до того, що початковий вісімковий специфікатор ('0o') буде вставлено перед першою цифрою.

2. Альтернативна форма призводить до того, що початковий '0x' або '0X' (залежно від того, використовувався формат 'x' або 'X') буде вставлено перед перша цифра.

3. Альтернативна форма призводить до того, що результат завжди містить десяткову крапку, навіть якщо за нею не йде цифра.

   Точність визначає кількість цифр після коми та за замовчуванням дорівнює 6.

4. Альтернативна форма призводить до того, що результат завжди містить десяткову кому, а кінцеві нулі не видаляються, як це було б інакше.

   Точність визначає кількість значущих цифр до та після десяткової коми та за умовчанням дорівнює 6.

5. Якщо точність N, вивід скорочується до N символів.

6. Дивіться PEP 237.

Оскільки рядки Python мають явну довжину, перетворення %s не припускають, що '\0 є кінцем рядка.

Змінено в версії 3.1: Перетворення %f для чисел, абсолютне значення яких перевищує 1e50, більше не замінюються перетвореннями %g.

Типи бінарних послідовностей — bytes, bytearray, memoryview

Основними вбудованими типами для обробки двійкових даних є bytes і bytearray. Вони підтримуються memoryview, який використовує протокол буфера для доступу до пам’яті інших бінарних об’єктів без необхідності створення копії.

Модуль array підтримує ефективне зберігання основних типів даних, таких як 32-розрядні цілі числа та плаваючі значення подвійної точності IEEE754.

Об’єкти Bytes

Об’єкти Bytes — це незмінні послідовності окремих байтів. Оскільки багато основних двійкових протоколів базуються на текстовому кодуванні ASCII, об’єкти bytes пропонують кілька методів, які дійсні лише під час роботи з даними, сумісними з ASCII, і тісно пов’язані з рядковими об’єктами різними способами.

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

По-перше, синтаксис байтових літералів здебільшого такий самий, як і для рядкових літералів, за винятком того, що додано префікс b:

• Одинарні лапки: b'все ще дозволяє вбудовані "подвійні" лапки

• Подвійні лапки: b"все ще дозволяє вбудовані 'одинарні' лапки

• Потрійні лапки: b''''3 одинарні лапки'''', b"""3 подвійні лапки"""

У байтових літералах дозволені лише символи ASCII (незалежно від оголошеного кодування вихідного коду). Будь-які двійкові значення понад 127 потрібно вводити в байтові літерали за допомогою відповідної керуючої послідовності.

Як і рядкові літерали, літерали bytes також можуть використовувати префікс r, щоб вимкнути обробку керуючих послідовностей. Перегляньте Рядкові та байтові літерали, щоб дізнатися більше про різні форми літералів байтів, включаючи підтримувані керуючі послідовності.

У той час як байтові літерали та представлення базуються на тексті ASCII, об’єкти байтів фактично поводяться як незмінні послідовності цілих чисел, де кожне значення в послідовності обмежено таким чином, що 0 <= x < 256 (спроби порушити це обмеження викличуть ValueError). Це зроблено навмисно, щоб підкреслити, що хоча багато двійкових форматів включають елементи на основі ASCII і ними можна корисно маніпулювати за допомогою деяких текстово-орієнтованих алгоритмів, це зазвичай не стосується довільних двійкових даних (сліпе застосування алгоритмів обробки тексту до двійкових форматів даних, які не Сумісність із ASCII зазвичай призводить до пошкодження даних).

Окрім літеральних форм, об’єкти bytes можна створювати кількома іншими способами:

• Об’єкт із заповненими нулем байтами вказаної довжини: bytes(10)

• З ітерації цілих чисел: bytes(range(20))

• Копіювання існуючих двійкових даних через протокол буфера: bytes(obj)

Також перегляньте вбудований bytes.

Оскільки 2 шістнадцяткові цифри точно відповідають одному байту, шістнадцяткові числа є широко використовуваним форматом для опису двійкових даних. Відповідно, тип bytes має додатковий метод класу для читання даних у цьому форматі:

classmethod fromhex(string)

Цей метод класу bytes повертає об’єкт bytes, декодуючи даний рядковий об’єкт. Рядок має містити дві шістнадцяткові цифри на байт, при цьому пробіли ASCII ігноруються.

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

Змінено в версії 3.7: bytes.fromhex() тепер пропускає всі пробіли ASCII у рядку, а не лише пробіли.

Існує функція зворотного перетворення для перетворення об’єкта байтів у його шістнадцяткове представлення.

hex([sep[, bytes_per_sep]])

Повертає рядковий об’єкт, що містить дві шістнадцяткові цифри для кожного байта екземпляра.

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

If you want to make the hex string easier to read, you can specify a single character separator sep parameter to include in the output. By default, this separator will be included between each byte. A second optional bytes_per_sep parameter controls the spacing. Positive values calculate the separator position from the right, negative values from the left.

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

Змінено в версії 3.8: bytes.hex() тепер підтримує додаткові параметри sep і bytes_per_sep для вставки роздільників між байтами в шістнадцятковому виведенні.

Оскільки об’єкти bytes — це послідовності цілих чисел (подібно до кортежу), для об’єкта bytes b «b[0]» буде цілим числом, тоді як «b[0:1]» буде байтом об’єкт довжини 1. (Це контрастує з текстовими рядками, де як індексування, так і нарізка створять рядок довжиною 1)

Для представлення об’єктів bytes використовується літеральний формат (b'...''), оскільки він часто корисніший, ніж, наприклад, bytes([46, 46, 46]). Ви завжди можете перетворити об’єкт bytes на список цілих чисел за допомогою list(b).

Об’єкти байтового масиву

Об’єкти bytearray є змінними аналогами об’єктів bytes.

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

Для об’єктів bytearray немає виділеного синтаксису літералів, натомість вони завжди створюються шляхом виклику конструктора:

• Створення порожнього екземпляра: bytearray()

• Створення екземпляра із заповненням нуля із заданою довжиною: bytearray(10)

• З ітерації цілих чисел: bytearray(range(20))

• Копіювання наявних двійкових даних за допомогою буферного протоколу: bytearray(b'Hi!')

Оскільки об’єкти bytearray є змінними, вони підтримують операції послідовності mutable на додаток до звичайних операцій з байтами та байтовими масивами, описаних у Операції з байтами та масивом байтів.

Також перегляньте вбудований bytearray.

Оскільки 2 шістнадцяткові цифри точно відповідають одному байту, шістнадцяткові числа є широко використовуваним форматом для опису двійкових даних. Відповідно, тип bytearray має додатковий метод класу для читання даних у цьому форматі:

classmethod fromhex(string)

Цей метод класу bytearray повертає об’єкт bytearray, декодуючи заданий рядковий об’єкт. Рядок має містити дві шістнадцяткові цифри на байт, при цьому пробіли ASCII ігноруються.

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

Змінено в версії 3.7: bytearray.fromhex() тепер пропускає всі пробіли ASCII у рядку, а не лише пробіли.

Існує функція зворотного перетворення для перетворення об’єкта байтового масиву в його шістнадцяткове представлення.

hex([sep[, bytes_per_sep]])

Повертає рядковий об’єкт, що містить дві шістнадцяткові цифри для кожного байта екземпляра.

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

Added in version 3.5.

Змінено в версії 3.8: Подібно до bytes.hex(), bytearray.hex() тепер підтримує додаткові параметри sep і bytes_per_sep для вставки роздільників між байтами в шістнадцятковому виведенні.

Оскільки об’єкти bytearray — це послідовності цілих чисел (схожі на список), для об’єкта bytearray b «b[0]» буде цілим числом, а «b[0:1]» буде масивом bytearray об’єкт довжини 1. (Це контрастує з текстовими рядками, де як індексування, так і нарізка створять рядок довжиною 1)

У представленні об’єктів bytearray використовується формат літералу bytes (bytearray(b'...')), оскільки він часто корисніший, ніж, наприклад, bytearray([46, 46, 46]). Ви завжди можете перетворити об’єкт bytearray на список цілих чисел за допомогою list(b).

Операції з байтами та масивом байтів

Як об’єкти bytes, так і bytearray підтримують операції послідовності common. Вони взаємодіють не тільки з операндами того самого типу, але й з будь-яким bytes-like object. Завдяки цій гнучкості їх можна вільно змішувати під час операцій, не викликаючи помилок. Однак тип результату може залежати від порядку операндів.

Примітка

Методи для об’єктів bytes і bytearray не приймають рядки як аргументи, так само як методи для рядків не приймають байти як аргументи. Наприклад, ви повинні написати:

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

і:

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

Деякі операції з байтами та масивами байтів передбачають використання двійкових форматів, сумісних із ASCII, і тому їх слід уникати під час роботи з довільними двійковими даними. Ці обмеження описані нижче.

Примітка

Використання цих операцій на основі ASCII для обробки двійкових даних, які не зберігаються у форматі на основі ASCII, може призвести до пошкодження даних.

Наступні методи для об’єктів bytes і bytearray можна використовувати з довільними двійковими даними.

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

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

Повертає кількість неперекриваючих входжень підпослідовності sub у діапазоні [початок, кінець]. Необов’язкові аргументи початок і кінець інтерпретуються як у нотації фрагментів.

Підпослідовністю для пошуку може бути будь-який bytes-like object або ціле число в діапазоні від 0 до 255.

If sub is empty, returns the number of empty slices between characters which is the length of the bytes object plus one.

Змінено в версії 3.3: Також прийняти ціле число в діапазоні від 0 до 255 як підпослідовність.

bytes.removeprefix(prefix, /)

bytearray.removeprefix(prefix, /)

Якщо двійкові дані починаються з рядка prefix, поверніть bytes[len(prefix):]. В іншому випадку поверніть копію вихідних двійкових даних:

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

Префікс може бути будь-яким bytes-like object.

Примітка

Версія bytearray цього методу не працює на місці – вона завжди створює новий об’єкт, навіть якщо не було зроблено жодних змін.

Added in version 3.9.

bytes.removesuffix(suffix, /)

bytearray.removesuffix(suffix, /)

Якщо двійкові дані закінчуються рядком суфікса і цей суфікс не порожній, поверніть bytes[:-len(suffix)]. В іншому випадку поверніть копію вихідних двійкових даних:

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

Суфіксом може бути будь-який bytes-like object.

Примітка

Версія bytearray цього методу не працює на місці – вона завжди створює новий об’єкт, навіть якщо не було зроблено жодних змін.

Added in version 3.9.

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

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

Return the bytes decoded to a str.

encoding defaults to 'utf-8'; see Стандартні кодування for possible values.

errors controls how decoding errors are handled. If 'strict' (the default), a UnicodeError exception is raised. Other possible values are 'ignore', 'replace', and any other name registered via codecs.register_error(). See Обробники помилок for details.

For performance reasons, the value of errors is not checked for validity unless a decoding error actually occurs, Режим розробки Python is enabled or a debug build is used.

Примітка

Passing the encoding argument to str allows decoding any bytes-like object directly, without needing to make a temporary bytes or bytearray object.

Змінено в версії 3.1: Додано підтримку аргументів ключових слів.

Змінено в версії 3.9: The value of the errors argument is now checked in Режим розробки Python and in debug mode.

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

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

Повертає True, якщо двійкові дані закінчуються вказаним суфіксом, інакше повертає False. suffix також може бути кортежем суфіксів для пошуку. З необов’язковим початком тестування починається з цієї позиції. З необов’язковим end, припинити порівняння на цій позиції.

Суфікс(и) для пошуку може бути будь-яким bytes-like object.

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

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

Повертає найнижчий індекс у даних, де знайдено підпослідовність sub, так що sub міститься в сегменті s[start:end]. Необов’язкові аргументи початок і кінець інтерпретуються як у нотації фрагментів. Повертає -1, якщо sub не знайдено.

Підпослідовністю для пошуку може бути будь-який bytes-like object або ціле число в діапазоні від 0 до 255.

Примітка

Метод find() слід використовувати, лише якщо вам потрібно знати позицію sub. Щоб перевірити, чи є sub підрядком, скористайтеся оператором in:

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

Змінено в версії 3.3: Також прийняти ціле число в діапазоні від 0 до 255 як підпослідовність.

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

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

Як find(), але викликає ValueError, коли підпослідовність не знайдено.

Підпослідовністю для пошуку може бути будь-який bytes-like object або ціле число в діапазоні від 0 до 255.

Змінено в версії 3.3: Також прийняти ціле число в діапазоні від 0 до 255 як підпослідовність.

bytes.join(iterable)

bytearray.join(iterable)

Повертає об’єкт bytes або bytearray, який є конкатенацією двійкових послідовностей даних у iterable. Помилка TypeError буде викликана, якщо в iterable є будь-які значення, які не є bytes-подібними об’єктами, включаючи об’єкти str. Роздільником між елементами є вміст об’єкта bytes або bytearray, що забезпечує цей метод.

static bytes.maketrans(from, to)

static bytearray.maketrans(from, to)

Цей статичний метод повертає таблицю перекладу, придатну для bytes.translate(), яка відобразить кожен символ у from на символ у тій же позиції в to; from і to мають бути байтоподібними об’єктами і мати однакову довжину.

Added in version 3.1.

bytes.partition(sep)

bytearray.partition(sep)

Розділіть послідовність при першому входженні sep і поверніть 3-кортеж, що містить частину перед роздільником, сам роздільник або його копію байтового масиву та частину після роздільника. Якщо роздільник не знайдено, поверніть 3-кортеж, що містить копію вихідної послідовності, за якою слідують два порожні байти або об’єкти bytearray.

Роздільником для пошуку може бути будь-який bytes-like object.

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

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

Повертає копію послідовності з заміною всіх входжень підпослідовності old на new. Якщо вказано необов’язковий аргумент count, заміняються лише перші випадки count.

Підпослідовністю для пошуку та її заміною може бути будь-який bytes-like object.

Примітка

Версія bytearray цього методу не працює на місці – вона завжди створює новий об’єкт, навіть якщо не було зроблено жодних змін.

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

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

Повертає найвищий індекс у послідовності, де знайдено підпослідовність sub, так що sub міститься в s[start:end]. Необов’язкові аргументи початок і кінець інтерпретуються як у нотації фрагментів. Повернути -1 у разі помилки.

Підпослідовністю для пошуку може бути будь-який bytes-like object або ціле число в діапазоні від 0 до 255.

Змінено в версії 3.3: Також прийняти ціле число в діапазоні від 0 до 255 як підпослідовність.

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

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

Подібно до rfind(), але викликає ValueError, коли підпослідовність sub не знайдено.

Підпослідовністю для пошуку може бути будь-який bytes-like object або ціле число в діапазоні від 0 до 255.

Змінено в версії 3.3: Також прийняти ціле число в діапазоні від 0 до 255 як підпослідовність.

bytes.rpartition(sep)

bytearray.rpartition(sep)

Розділіть послідовність при останньому входженні sep і поверніть 3-кортеж, що містить частину перед роздільником, сам роздільник або його копію байтового масиву та частину після роздільника. Якщо роздільник не знайдено, поверніть 3-кортеж, що містить два порожні об’єкти байтів або масиву байтів, а потім копію вихідної послідовності.

Роздільником для пошуку може бути будь-який bytes-like object.

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

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

Повертає True, якщо двійкові дані починаються з указаного префікса, інакше повертає False. префікс також може бути кортежем префіксів для пошуку. З необов’язковим початком тестування починається з цієї позиції. З необов’язковим end, припинити порівняння на цій позиції.

Префікс(и) для пошуку може бути будь-яким bytes-like object.

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

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

Повертає копію об’єкта bytes або bytearray, де всі байти, що зустрічаються в необов’язковому аргументі delete, видаляються, а решта байтів відображено через задану таблицю перекладу, яка має бути об’єктом bytes довжиною 256.

Ви можете використовувати метод bytes.maketrans() для створення таблиці перекладу.

Встановіть для аргументу table значення None для перекладів, які видаляють лише символи:

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

Змінено в версії 3.6: delete тепер підтримується як аргумент ключового слова.

Наведені нижче методи для об’єктів bytes і bytearray мають поведінку за замовчуванням, яка передбачає використання ASCII-сумісних двійкових форматів, але все одно їх можна використовувати з довільними двійковими даними шляхом передачі відповідних аргументів. Зауважте, що всі методи bytearray у цьому розділі не працюють на місці, а створюють нові об’єкти.

bytes.center(width[, fillbyte])

bytearray.center(width[, fillbyte])

Повертає копію об’єкта з центром у послідовності довжиною шириною. Доповнення виконується за допомогою вказаного fillbyte (за замовчуванням це пробіл ASCII). Для об’єктів bytes оригінальна послідовність повертається, якщо width менше або дорівнює len(s).

Примітка

Версія bytearray цього методу не працює на місці – вона завжди створює новий об’єкт, навіть якщо не було зроблено жодних змін.

bytes.ljust(width[, fillbyte])

bytearray.ljust(width[, fillbyte])

Повертає копію об’єкта, вирівняну за лівим краєм у послідовності довжини ширина. Доповнення виконується за допомогою вказаного fillbyte (за замовчуванням це пробіл ASCII). Для об’єктів bytes вихідна послідовність повертається, якщо width менше або дорівнює len(s).

Примітка

Версія bytearray цього методу не працює на місці – вона завжди створює новий об’єкт, навіть якщо не було зроблено жодних змін.

bytes.lstrip([chars])

bytearray.lstrip([chars])

Повертає копію послідовності з видаленими вказаними початковими байтами. Аргумент chars є двійковою послідовністю, яка визначає набір значень байтів, які потрібно видалити. Назва вказує на те, що цей метод зазвичай використовується з символами ASCII. Якщо пропущено або None, аргумент chars за умовчанням видаляє пробіли ASCII. Аргумент chars не є префіксом; навпаки, усі комбінації його значень видаляються:

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

Двійкова послідовність байтових значень для видалення може бути будь-яким bytes-like object. Перегляньте removeprefix() для методу, який видаляє один рядок префікса, а не весь набір символів. Наприклад:

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

Примітка

Версія bytearray цього методу не працює на місці – вона завжди створює новий об’єкт, навіть якщо не було зроблено жодних змін.

bytes.rjust(width[, fillbyte])

bytearray.rjust(width[, fillbyte])

Повертає копію об’єкта, вирівняну по правому краю в послідовності довжина ширина. Доповнення виконується за допомогою вказаного fillbyte (за замовчуванням це пробіл ASCII). Для об’єктів bytes оригінальна послідовність повертається, якщо width менше або дорівнює len(s).

Примітка

Версія bytearray цього методу не працює на місці – вона завжди створює новий об’єкт, навіть якщо не було зроблено жодних змін.

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

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

Розділіть бінарну послідовність на підпослідовності одного типу, використовуючи sep як рядок-роздільник. Якщо задано maxsplit, виконується щонайбільше maxsplit розбиття, найправіші. Якщо sep не вказано або None, будь-яка підпослідовність, що складається виключно з пробілів ASCII, є роздільником. За винятком розділення справа, rsplit() поводиться як split(), що детально описано нижче.

bytes.rstrip([chars])

bytearray.rstrip([chars])

Повертає копію послідовності з видаленими вказаними кінцевими байтами. Аргумент chars є двійковою послідовністю, яка визначає набір значень байтів, які потрібно видалити. Назва вказує на те, що цей метод зазвичай використовується з символами ASCII. Якщо пропущено або None, аргумент chars за замовчуванням видаляє пробіли ASCII. Аргумент chars не є суфіксом; навпаки, усі комбінації його значень видаляються:

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

Двійкова послідовність байтових значень для видалення може бути будь-яким bytes-like object. Перегляньте removesuffix(), щоб дізнатися про метод, який видалить один рядок суфікса, а не весь набір символів. Наприклад:

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

Примітка

Версія bytearray цього методу не працює на місці – вона завжди створює новий об’єкт, навіть якщо не було зроблено жодних змін.

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

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

Розділіть бінарну послідовність на підпослідовності одного типу, використовуючи sep як рядок-роздільник. Якщо задано maxsplit і воно є невід’ємним, виконується щонайбільше розділень maxsplit (отже, список матиме щонайбільше елементів maxsplit+1). Якщо maxsplit не вказано або дорівнює -1, тоді немає обмежень на кількість розбивок (виконуються всі можливі розбиття).

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.

Наприклад:

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

Якщо sep не вказано або має значення None, застосовується інший алгоритм поділу: цикли послідовних пробілів ASCII розглядаються як один роздільник, і результат не міститиме порожніх рядків на початку або в кінці, якщо послідовність має пробіли на початку або в кінці. Отже, розділення порожньої послідовності або послідовності, що складається виключно з пробілів ASCII без указаного роздільника, повертає [].

Наприклад:

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

Повертає копію послідовності з вилученими вказаними початковим і кінцевим байтами. Аргумент chars є двійковою послідовністю, яка визначає набір значень байтів, які потрібно видалити. Назва вказує на те, що цей метод зазвичай використовується з символами ASCII. Якщо пропущено або None, аргумент chars за замовчуванням видаляє пробіли ASCII. Аргумент chars не є префіксом або суфіксом; навпаки, усі комбінації його значень видаляються:

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

Двійкова послідовність байтових значень для видалення може бути будь-яким bytes-like object.

Примітка

Версія bytearray цього методу не працює на місці – вона завжди створює новий об’єкт, навіть якщо не було зроблено жодних змін.

Наступні методи для об’єктів bytes і bytearray передбачають використання двійкових форматів, сумісних із ASCII, і їх не слід застосовувати до довільних двійкових даних. Зауважте, що всі методи bytearray у цьому розділі не працюють на місці, а створюють нові об’єкти.

bytes.capitalize()

bytearray.capitalize()

Повертає копію послідовності з кожним байтом, інтерпретованим як символ ASCII, і перший байт у великому регістрі, а решта – у нижньому. Байтові значення, відмінні від ASCII, передаються без змін.

Примітка

Версія bytearray цього методу не працює на місці – вона завжди створює новий об’єкт, навіть якщо не було зроблено жодних змін.

bytes.expandtabs(tabsize=8)

bytearray.expandtabs(tabsize=8)

Повертає копію послідовності, де всі символи табуляції ASCII замінено одним або декількома пробілами ASCII, залежно від поточного стовпця та заданого розміру табуляції. Позиції табуляції відбуваються кожні байти табуляції (за замовчуванням — 8, надаючи позиції табуляції в стовпцях 0, 8, 16 і так далі). Щоб розширити послідовність, поточний стовпець встановлюється на нуль і послідовність перевіряється побайтно. Якщо байт є символом табуляції ASCII (b'\t'), один або більше символів пробілу вставляються в результат, доки поточний стовпець не буде відповідати наступній позиції табуляції. (Сам символ табуляції не копіюється.) Якщо поточний байт є ASCII символом нового рядка (b'\n') або поверненням каретки (b'\r'), він копіюється і поточний стовпець скидається на нуль. Будь-яке інше значення байта копіюється без змін, а поточний стовпець збільшується на одиницю незалежно від того, як значення байта представлено під час друку:

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

Примітка

Версія bytearray цього методу не працює на місці – вона завжди створює новий об’єкт, навіть якщо не було зроблено жодних змін.

bytes.isalnum()

bytearray.isalnum()

Повертає True, якщо всі байти в послідовності є алфавітними символами ASCII або десятковими цифрами ASCII і послідовність не є порожньою, False інакше. Алфавітні символи ASCII – це значення байтів у послідовності b'abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ. Десяткові цифри ASCII – це значення байтів у послідовності b'0123456789.

Наприклад:

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

bytes.isalpha()

bytearray.isalpha()

Повертає True, якщо всі байти в послідовності є алфавітними символами ASCII і послідовність не є пустою, False інакше. Алфавітні символи ASCII – це значення байтів у послідовності b'abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ.

Наприклад:

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

bytes.isascii()

bytearray.isascii()

Повертає True, якщо послідовність порожня або всі байти в послідовності ASCII, False інакше. Байти ASCII знаходяться в діапазоні 0-0x7F.

Added in version 3.7.

bytes.isdigit()

bytearray.isdigit()

Повертає True, якщо всі байти в послідовності є десятковими цифрами ASCII і послідовність не порожня, False інакше. Десяткові цифри ASCII – це значення байтів у послідовності b'0123456789.

Наприклад:

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

bytes.islower()

bytearray.islower()

Повертає True, якщо в послідовності є принаймні один символ нижнього регістру ASCII і немає символів ASCII у верхньому регістрі, інакше False.

Наприклад:

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

Символи ASCII у нижньому регістрі – це значення байтів у послідовності b'abcdefghijklmnopqrstuvwxyz. Символи ASCII у верхньому регістрі – це значення байтів у послідовності b'ABCDEFGHIJKLMNOPQRSTUVWXYZ.

bytes.isspace()

bytearray.isspace()

Повертає True, якщо всі байти в послідовності є пробілами ASCII і послідовність не порожня, False інакше. Пробільні символи ASCII – це значення байтів у послідовності b' \t\n\r\x0b\f'' (пробіл, табуляція, новий рядок, повернення каретки, вертикальна табуляція, передача форми).

bytes.istitle()

bytearray.istitle()

Повертає True, якщо послідовність має регістр заголовків ASCII і послідовність не є порожньою, False інакше. Дивіться bytes.title(), щоб дізнатися більше про визначення «заголовка».

Наприклад:

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

bytes.isupper()

bytearray.isupper()

Повертає True, якщо в послідовності є принаймні один символ ASCII у верхньому регістрі та відсутні символи ASCII у нижньому регістрі, інакше False.

Наприклад:

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

Символи ASCII у нижньому регістрі – це значення байтів у послідовності b'abcdefghijklmnopqrstuvwxyz. Символи ASCII у верхньому регістрі – це значення байтів у послідовності b'ABCDEFGHIJKLMNOPQRSTUVWXYZ.

bytes.lower()

bytearray.lower()

Повертає копію послідовності з усіма символами ASCII у верхньому регістрі, перетвореними на їхні відповідні відповідники у нижньому регістрі.

Наприклад:

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

Символи ASCII у нижньому регістрі – це значення байтів у послідовності b'abcdefghijklmnopqrstuvwxyz. Символи ASCII у верхньому регістрі – це значення байтів у послідовності b'ABCDEFGHIJKLMNOPQRSTUVWXYZ.

Примітка

Версія bytearray цього методу не працює на місці – вона завжди створює новий об’єкт, навіть якщо не було зроблено жодних змін.

bytes.splitlines(keepends=False)

bytearray.splitlines(keepends=False)

Повертає список рядків у двійковій послідовності, розриваючи межі рядків ASCII. Цей метод використовує підхід universal newlines до розділення рядків. Розриви рядків не включаються до результуючого списку, якщо не задано keepends і воно є істинним.

Наприклад:

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

На відміну від split(), коли задано рядок розділювача sep, цей метод повертає порожній список для порожнього рядка, а розрив кінцевого рядка не призводить до додаткового рядка:

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

Повертає копію послідовності з усіма символами нижнього регістру ASCII, перетвореними на їхні відповідні відповідники у верхньому регістрі та навпаки.

Наприклад:

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

Символи ASCII у нижньому регістрі – це значення байтів у послідовності b'abcdefghijklmnopqrstuvwxyz. Символи ASCII у верхньому регістрі – це значення байтів у послідовності 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.

Примітка

Версія bytearray цього методу не працює на місці – вона завжди створює новий об’єкт, навіть якщо не було зроблено жодних змін.

bytes.title()

bytearray.title()

Повертає версію двійкової послідовності в заголовку, де слова починаються з символу ASCII у верхньому регістрі, а решта символів – у нижньому регістрі. Значення байтів без регістру залишаються незмінними.

Наприклад:

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

Символи ASCII у нижньому регістрі – це значення байтів у послідовності b'abcdefghijklmnopqrstuvwxyz. Символи ASCII у верхньому регістрі – це значення байтів у послідовності b'ABCDEFGHIJKLMNOPQRSTUVWXYZ. Усі інші значення байтів без регістру.

Алгоритм використовує просте незалежне від мови визначення слова як групи послідовних букв. Визначення працює в багатьох контекстах, але це означає, що апостроф у скороченнях і присвійних формах формує межі слів, що може бути не бажаним результатом:

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

Обхідний шлях для апострофів можна створити за допомогою регулярних виразів:

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

Примітка

Версія bytearray цього методу не працює на місці – вона завжди створює новий об’єкт, навіть якщо не було зроблено жодних змін.

bytes.upper()

bytearray.upper()

Повертає копію послідовності з усіма символами нижнього регістру ASCII, перетвореними на їхні відповідні відповідники у верхньому регістрі.

Наприклад:

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

Символи ASCII у нижньому регістрі – це значення байтів у послідовності b'abcdefghijklmnopqrstuvwxyz. Символи ASCII у верхньому регістрі – це значення байтів у послідовності b'ABCDEFGHIJKLMNOPQRSTUVWXYZ.

Примітка

Версія bytearray цього методу не працює на місці – вона завжди створює новий об’єкт, навіть якщо не було зроблено жодних змін.

bytes.zfill(width)

bytearray.zfill(width)

Поверніть копію послідовності зліва, заповнену цифрами ASCII b'0, щоб створити послідовність довжиною ширина. Початковий префікс знака (b'+'/ b'-') обробляється шляхом вставки заповнення після символу знака, а не перед ним. Для об’єктів bytes оригінальна послідовність повертається, якщо width менше або дорівнює len(seq).

Наприклад:

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

Примітка

Версія bytearray цього методу не працює на місці – вона завжди створює новий об’єкт, навіть якщо не було зроблено жодних змін.

Форматування байтів у стилі printf

Примітка

Операції форматування, описані тут, демонструють різноманітні особливості, які призводять до низки поширених помилок (наприклад, неправильне відображення кортежів і словників). Якщо значення, яке друкується, може бути кортежем або словником, оберніть його в кортеж.

Об’єкти Bytes (bytes/bytearray) мають одну унікальну вбудовану операцію: оператор % (за модулем). Це також відоме як оператор форматування або інтерполяції байтів. Враховуючи формат % значень (де format є об’єктом байтів), % специфікації перетворення у format замінюються нулем або більше елементами значень. Ефект подібний до використання sprintf() у мові C.

Якщо для format потрібен один аргумент, values може бути одним некортежним об’єктом. [5] В іншому випадку values має бути кортежем із точною кількістю елементів, указаною об’єктом format bytes, або одним об’єктом відображення (наприклад, словником).

Специфікатор перетворення містить два або більше символів і має наступні компоненти, які мають відображатися в такому порядку:

1. Символ '%', який позначає початок специфікатора.

2. Ключ відображення (необов’язковий), що складається з послідовності символів у дужках (наприклад, (якесь ім’я)).

3. Прапорці перетворення (опціонально), які впливають на результат деяких типів перетворення.

4. Мінімальна ширина поля (опціонально). Якщо вказано як '*' (зірочка), фактична ширина зчитується з наступного елемента кортежу в значеннях, а об’єкт для перетворення йде після мінімальної ширини поля та необов’язкової точності.

5. Точність (необов’язкова), подається як '.' (крапка), за якою йде точність. Якщо вказано як '*' (зірочка), фактична точність зчитується з наступного елемента кортежу в значеннях, а значення для перетворення йде після точності.

6. Модифікатор довжини (необов’язково).

7. Тип перетворення.

Коли правильний аргумент є словником (або іншим типом відображення), тоді формати в об’єкті bytes мають містити ключ відображення в дужках у цьому словнику, вставлений відразу після символу '%'. Ключ відображення вибирає значення, яке потрібно відформатувати, із відображення. Наприклад:

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

У цьому випадку у форматі не може бути специфікаторів * (оскільки вони вимагають послідовного списку параметрів).

Символи прапора перетворення:

Прапор	Значення
'#''	Перетворення значень використовуватиме «альтернативну форму» (де визначено нижче).
'0'	Перетворення буде доповнено нулем для числових значень.
'-'	Перетворене значення коригується зліва (перевизначає перетворення '0', якщо подано обидва значення).
' '	(пробіл) Пробіл слід залишити перед додатним числом (або порожнім рядком), утвореним перетворенням зі знаком.
'+'	Символ знака ('+' або '-') передуватиме перетворенню (перевизначає позначку «пробіл»).

Модифікатор довжини (h, l або L) може бути присутнім, але він ігнорується, оскільки він не є необхідним для Python - так, напр. %ld ідентичний %d.

Типи перетворення:

Перетворення	Значення	Примітки
'd''	Ціле десяткове число зі знаком.
'я''	Ціле десяткове число зі знаком.
'o'	Вісімкове значення зі знаком.	(1)
'u''	Застарілий тип – він ідентичний 'd'.	(8)
'x''	Шістнадцяткове число зі знаком (нижній регістр).	(2)
'X''	Шістнадцяткове число зі знаком (верхній регістр).	(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''	Однобайтовий (приймає цілі чи однобайтові об’єкти).
'b''	Bytes (any object that follows the buffer protocol or has __bytes__()).	(5)
's''	's'' є псевдонімом для 'b'' і має використовуватися лише для базового коду Python2/3.	(6)
'a'	Байти (перетворює будь-який об’єкт Python за допомогою repr(obj).encode('ascii', 'backslashreplace')).	(5)
'r''	'r' є псевдонімом для 'a' і має використовуватися лише для базових кодів Python2/3.	(7)
'%'	Жоден аргумент не перетворюється, результатом є символ '%' в результаті.

Примітки:

1. Альтернативна форма призводить до того, що початковий вісімковий специфікатор ('0o') буде вставлено перед першою цифрою.

2. Альтернативна форма призводить до того, що початковий '0x' або '0X' (залежно від того, використовувався формат 'x' або 'X') буде вставлено перед перша цифра.

3. Альтернативна форма призводить до того, що результат завжди містить десяткову крапку, навіть якщо за нею не йде цифра.

   Точність визначає кількість цифр після коми та за замовчуванням дорівнює 6.

4. Альтернативна форма призводить до того, що результат завжди містить десяткову кому, а кінцеві нулі не видаляються, як це було б інакше.

   Точність визначає кількість значущих цифр до та після десяткової коми та за умовчанням дорівнює 6.

5. Якщо точність N, вивід скорочується до N символів.

6. b'%s є застарілим, але не буде видалено протягом серії 3.x.

7. b'%r'' є застарілим, але не буде видалено протягом серії 3.x.

8. Дивіться PEP 237.

Примітка

Версія bytearray цього методу не працює на місці – вона завжди створює новий об’єкт, навіть якщо не було зроблено жодних змін.

Дивись також

PEP 461 - Додано форматування % до байтів і масиву байтів

Added in version 3.5.

Перегляди пам’яті

Об’єкти memoryview дозволяють коду Python отримувати доступ до внутрішніх даних об’єкта, який підтримує протокол буфера без копіювання.

class memoryview(object)

Створіть memoryview, який посилається на об’єкт. об’єкт має підтримувати протокол буфера. Вбудовані об’єкти, які підтримують протокол буфера, включають bytes і bytearray.

memoryview має поняття елемента, який є атомарною одиницею пам’яті, яка обробляється вихідним об’єктом. Для багатьох простих типів, таких як bytes і bytearray, елемент є одним байтом, але інші типи, такі як array.array, можуть мати більші елементи.

len(view) is equal to the length of tolist, which is the nested list representation of the view. If view.ndim = 1, this is equal to the number of elements in the view.

Змінено в версії 3.12: If view.ndim == 0, len(view) now raises TypeError instead of returning 1.

The itemsize attribute will give you the number of bytes in a single element.

memoryview підтримує нарізку та індексування для показу своїх даних. Одновимірне нарізання призведе до підвиду:

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

Якщо format є одним із власних специфікаторів формату з модуля struct, індексація за допомогою цілого числа або кортежу цілих чисел також підтримується та повертає один елемент із правильним типом . Одновимірні представлення пам’яті можна індексувати за допомогою цілого або одноцілого кортежу. Багатовимірні представлення пам’яті можна індексувати за допомогою кортежів з точно ndim цілих чисел, де ndim є кількістю вимірів. Нульвимірні представлення пам’яті можна індексувати за допомогою порожнього кортежу.

Ось приклад небайтового формату:

>>> import array
>>> a = array.array('l', [-11111111, 22222222, -33333333, 44444444])
>>> m = memoryview(a)
>>> m[0]
-11111111
>>> m[-1]
44444444
>>> m[::2].tolist()
[-11111111, -33333333]

Якщо основний об’єкт доступний для запису, memoryview підтримує одновимірне призначення фрагментів. Зміна розміру заборонена:

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

One-dimensional memoryviews of hashable (read-only) types with formats „B“, „b“ or „c“ are also hashable. The hash is defined as 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

Змінено в версії 3.3: One-dimensional memoryviews can now be sliced. One-dimensional memoryviews with formats „B“, „b“ or „c“ are now hashable.

Змінено в версії 3.4: memoryview тепер автоматично реєструється в collections.abc.Sequence

Змінено в версії 3.5: memoryviews тепер можна індексувати кортежем цілих чисел.

memoryview має кілька методів:

__eq__(exporter)

Memoriview і експортер PEP 3118 є рівними, якщо їхні форми еквівалентні та якщо всі відповідні значення рівні, коли відповідні коди формату операндів інтерпретуються за допомогою синтаксису struct.

Для підмножини рядків формату struct, які зараз підтримуються tolist(), v і w рівні, якщо 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

Якщо будь-який рядок формату не підтримується модулем struct, тоді об’єкти завжди порівнюватимуться як нерівні (навіть якщо рядки формату та вміст буфера ідентичні):

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

Змінено в версії 3.3: Попередні версії порівнювали необроблену пам’ять без урахування формату елемента та логічної структури масиву.

tobytes(order='C')

Повертає дані в буфері як байтовий рядок. Це еквівалентно виклику конструктора bytes у memoryview.

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

Для несуміжних масивів результат дорівнює представленню зведеного списку з усіма елементами, перетвореними на байти. tobytes() підтримує всі рядки формату, включно з тими, яких немає в синтаксисі модуля struct.

Added in version 3.8: порядок може бути {„C“, „F“, „A“}. Якщо порядок має значення «C» або «F», дані вихідного масиву перетворюються на порядок C або Fortran. Для суміжних переглядів «A» повертає точну копію фізичної пам’яті. Зокрема, зберігається порядок Fortran у пам’яті. Для несуміжних переглядів дані спочатку перетворюються на C. order=None те саме, що order=“C“.

hex([sep[, bytes_per_sep]])

Повертає рядковий об’єкт, що містить дві шістнадцяткові цифри для кожного байта в буфері.

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

Added in version 3.5.

Змінено в версії 3.8: Подібно до bytes.hex(), memoryview.hex() тепер підтримує додаткові параметри sep і bytes_per_sep для вставки роздільників між байтами в шістнадцятковому виведенні.

tolist()

Повертає дані в буфері як список елементів.

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

Змінено в версії 3.3: tolist() тепер підтримує всі односимвольні рідні формати в синтаксисі модуля struct, а також багатовимірні представлення.

toreadonly()

Повертає версію об’єкта memoryview лише для читання. Оригінальний об’єкт memoryview не змінено.

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

Вивільніть базовий буфер, відкритий об’єктом memoryview. Багато об’єктів виконують спеціальні дії, коли їх переглядають (наприклад, bytearray тимчасово забороняє зміну розміру); отже, виклик release() є зручним, щоб усунути ці обмеження (і звільнити будь-які завислі ресурси) якомога швидше.

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

Протокол керування контекстом може бути використаний для подібного ефекту, використовуючи оператор 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])

Транслюйте пам’ять у новий формат або форму. shape за умовчанням має значення [byte_length//new_itemsize], що означає, що перегляд результату буде одновимірним. Поверненим значенням є новий перегляд пам’яті, але сам буфер не копіюється. Підтримувані приведення: 1D -> C-contiguous і C-contiguous -> 1D.

The destination format is restricted to a single element native format in struct syntax. One of the formats must be a byte format („B“, „b“ or „c“). The byte length of the result must be the same as the original length. Note that all byte lengths may depend on the operating system.

Перетворення 1D/long на 1D/беззнакові байти:

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

Перетворення 1D/беззнакових байтів у 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')

Перетворити 1D/байти на 3D/ints на 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

Перетворення 1D/unsigned long на 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.

Змінено в версії 3.5: Вихідний формат більше не обмежений під час трансляції до байтового перегляду.

Також є кілька доступних атрибутів лише для читання:

obj

Основний об’єкт 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()). Це обсяг простору в байтах, який буде використовуватися масивом у безперервному представленні. Воно не обов’язково дорівнює 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

Багатовимірні масиви:

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

Bool, що вказує, чи є пам’ять лише для читання.

format

Рядок, що містить формат (у стилі модуля struct) для кожного елемента в поданні. Огляд пам’яті можна створити з експортерів із довільними рядками формату, але деякі методи (наприклад, tolist()) обмежені рідними одноелементними форматами.

Змінено в версії 3.3: формат 'B' тепер обробляється відповідно до синтаксису модуля struct. Це означає, що memoryview(b'abc')[0] == b'abc'[0] == 97.

itemsize

Розмір у байтах кожного елемента 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

Ціле число, що вказує, скільки вимірів багатовимірного масиву представляє пам’ять.

shape

Кортеж цілих чисел довжиною ndim, що надає форму пам’яті як N-вимірного масиву.

Змінено в версії 3.3: Порожній кортеж замість None, коли ndim = 0.

strides

Кортеж цілих чисел довжиною ndim, що вказує розмір у байтах для доступу до кожного елемента для кожного виміру масиву.

Змінено в версії 3.3: Порожній кортеж замість None, коли ndim = 0.

suboffsets

Використовується внутрішньо для масивів у стилі PIL. Значення лише інформаційне.

c_contiguous

Логічне значення, яке вказує, чи є пам’ять C-contiguous.

Added in version 3.3.

f_contiguous

Логічне значення, що вказує, чи є пам’ять Fortran contiguous.

Added in version 3.3.

contiguous

Bool, що вказує, чи є пам’ять contiguous.

Added in version 3.3.

Типи наборів — set, frozenset

Об’єкт set — це невпорядкована колекція окремих об’єктів hashable. Загальне використання включає тестування членства, видалення дублікатів із послідовності та обчислення математичних операцій, таких як перетин, об’єднання, різниця та симетрична різниця. (Для інших контейнерів перегляньте вбудовані класи dict, list і tuple, а також модуль collections.)

Як і інші колекції, набори підтримують x in set, len(set) і for x in set. Будучи невпорядкованою колекцією, набори не записують положення елемента або порядок вставки. Відповідно, набори не підтримують індексування, нарізку чи іншу поведінку, подібну до послідовності.

Наразі існує два вбудовані типи наборів: set і frozenset. Тип set є змінним — вміст можна змінити за допомогою таких методів, як add() і remove(). Оскільки він є змінним, він не має хеш-значення і не може використовуватися ні як ключ словника, ні як елемент іншого набору. Тип frozenset є незмінним і hashable — його вміст не можна змінити після створення; тому його можна використовувати як ключ до словника або як елемент іншого набору.

Непорожні набори (не заморожені набори) можна створити шляхом розміщення списку елементів, розділених комами, у фігурних дужках, наприклад: {'jack', 'sjoerd'}, на додаток до set конструктор.

Конструктори для обох класів працюють однаково:

class set([iterable])

class frozenset([iterable])

Повертає новий набір або заморожений об’єкт, елементи якого взяті з iterable. Елементи набору мають бути hashable. Щоб представити набори наборів, внутрішні набори мають бути об’єктами frozenset. Якщо iterable не вказано, повертається новий порожній набір.

Набори можна створювати кількома способами:

• Використовуйте список елементів, розділених комами, у фігурних дужках: {'jack', 'sjoerd'}

• Використовуйте розуміння набору: {c для c в 'abracadabra' якщо c не в 'abc'}

• Використовуйте конструктор типу: set(), set('foobar'), set(['a', 'b', 'foo'])

Екземпляри set і frozenset забезпечують такі операції:

len(s)

Повертає кількість елементів у наборі s (мощність s).

x in s

Перевірте x на членство в s.

x not in s

Перевірте x на неналежність до s.

isdisjoint(other)

Повертає True, якщо набір не має спільних елементів з other. Множини непересічні тоді і тільки тоді, коли їх перетин є порожньою множиною.

issubset(other)

set <= other

Перевірте, чи кожен елемент у наборі знаходиться в other.

set < other

Перевірте, чи набір є правильною підмножиною other, тобто set <= other і set != other.

issuperset(other)

set >= other

Перевірте, чи всі елементи в other є в наборі.

set > other

Перевірте, чи є набір правильною надмножиною other, тобто set >= other і set != other.

union(*others)

set | other | ...

Повернути новий набір з елементами з набору та всі інші.

intersection(*others)

set & other & ...

Повертає новий набір із елементами, спільними для набору та всіх інших.

difference(*others)

set - other - ...

Повертає новий набір з елементами в наборі, яких немає в інших.

symmetric_difference(other)

set ^ other

Повертає новий набір з елементами або в наборі, або в іншому, але не в обох.

copy()

Поверніть мілку копію набору.

Зауважте, версії без операторів union(), intersection(), difference(), symmetric_difference(), issubset() і issuperset() методи приймуть будь-яку ітерацію як аргумент. На відміну від цього, їхні аналоги на основі операторів вимагають, щоб їхні аргументи були наборами. Це виключає такі схильні до помилок конструкції, як set('abc') & 'cbs' на користь більш читабельного set('abc').intersection('cbs').

І set, і frozenset підтримують набір для встановлення порівнянь. Дві множини рівні тоді і тільки тоді, коли кожен елемент кожної множини міститься в іншій (кожен є підмножиною іншого). Набір менший за інший набір тоді і тільки тоді, коли перший набір є належним підмножиною другого набору (є підмножиною, але не дорівнює). Набір більший за інший набір тоді і тільки тоді, коли перший набір є належним надмножиною другого набору (є надмножиною, але не є рівним).

Примірники set порівнюються з примірниками frozenset на основі їхніх членів. Наприклад, set('abc') == frozenset('abc') повертає True, а також set('abc') у set([frozenset('abc')]).

Порівняння підмножини та рівності не узагальнюють до загальної функції впорядкування. Наприклад, будь-які дві непорожні непересічні множини не рівні і не є підмножинами одна одної, тому всі з наступного повертають False: a <b, a==b, or a> b.

Оскільки набори визначають лише часткове впорядкування (відносини підмножин), вихід методу list.sort() не визначений для списків наборів.

Елементи набору, як і ключі словника, мають бути hashable.

Бінарні операції, які поєднують екземпляри set із frozenset, повертають тип першого операнда. Наприклад: frozenset('ab') | set('bc') повертає екземпляр frozenset.

У наступній таблиці наведено операції, доступні для set, які не застосовуються до незмінних екземплярів frozenset:

update(*others)

set |= other | ...

Оновіть набір, додавши елементи з усіх інших.

intersection_update(*others)

set &= other & ...

Оновіть набір, зберігаючи лише елементи, знайдені в ньому, і всі інші.

difference_update(*others)

set -= other | ...

Оновіть набір, видаляючи елементи, знайдені в інших.

symmetric_difference_update(other)

set ^= other

Оновіть набір, зберігаючи лише елементи, знайдені в будь-якому наборі, але не в обох.

add(elem)

Додайте елемент elem до набору.

remove(elem)

Видалити елемент elem із набору. Викликає KeyError, якщо elem не міститься в наборі.

discard(elem)

Видалити елемент elem із набору, якщо він присутній.

pop()

Вилучити та повернути довільний елемент із набору. Викликає KeyError, якщо набір порожній.

clear()

Видаліть усі елементи з набору.

Зауважте, що безоператорні версії методів update(), intersection_update(), difference_update() і symmetric_difference_update() прийматимуть будь-яку ітерацію як аргумент.

Note, the elem argument to the __contains__(), remove(), and discard() methods may be a set. To support searching for an equivalent frozenset, a temporary one is created from elem.

Типи зіставлення — dict

Об’єкт mapping відображає значення hashable на довільні об’єкти. Відображення є змінними об’єктами. Зараз існує лише один стандартний тип відображення, dictionary. (Для інших контейнерів перегляньте вбудовані класи list, set і tuple, а також модуль collections.)

A dictionary’s keys are almost arbitrary values. Values that are not hashable, that is, values containing lists, dictionaries or other mutable types (that are compared by value rather than by object identity) may not be used as keys. Values that compare equal (such as 1, 1.0, and True) can be used interchangeably to index the same dictionary entry.

class dict(**kwargs)

class dict(mapping, **kwargs)

class dict(iterable, **kwargs)

Повертає новий словник, ініціалізований необов’язковим позиційним аргументом і, можливо, порожнім набором ключових аргументів.

Словники можна створювати кількома способами:

• Використовуйте розділений комами список пар ключ: значення у дужках: {'jack': 4098, 'sjoerd': 4127} або {4098: 'jack', 4127: 'sjoerd' }

• Використовуйте розуміння диктового слова: {}, {x: x ** 2 для x в діапазоні (10)}

• Використовуйте конструктор типу: 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.

Якщо надано аргументи ключового слова, аргументи ключового слова та їхні значення додаються до словника, створеного з позиційного аргументу. Якщо ключ, який додається, уже присутній, значення з аргументу ключового слова замінює значення з позиційного аргументу.

Для ілюстрації, усі наступні приклади повертають словник, що дорівнює {"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

Надання аргументів ключових слів, як у першому прикладі, працює лише для ключів, які є дійсними ідентифікаторами Python. В іншому випадку можна використовувати будь-які дійсні ключі.

Це операції, які підтримують словники (і, отже, також повинні підтримуватися спеціальні типи зіставлення):

list(d)

Повернути список усіх ключів, які використовуються у словнику d.

len(d)

Повернути кількість елементів у словнику d.

d[key]

Поверніть елемент d за допомогою ключа key. Викликає KeyError, якщо key немає на карті.

Якщо підклас dict визначає метод __missing__() і key відсутній, операція d[key] викликає цей метод із ключем key як аргументом. Потім операція d[key] повертає або викликає все, що повертається або викликається викликом __missing__(key). Жодні інші операції чи методи не викликають __missing__(). Якщо __missing__() не визначено, виникає KeyError. __missing__() має бути методом; це не може бути змінна екземпляра:

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

Наведений вище приклад показує частину реалізації collections.Counter. Інший метод __missing__ використовується collections.defaultdict.

d[key] = value

Установіть для d[key] значення value.

del d[key]

Видаліть d[key] з d. Викликає KeyError, якщо key немає на карті.

key in d

Повертає True, якщо d має ключ key, інакше False.

key not in d

Еквівалент не вводити d.

iter(d)

Повертає ітератор над ключами словника. Це ярлик для iter(d.keys()).

clear()

Видаліть усі елементи зі словника.

copy()

Поверніть мілку копію словника.

classmethod fromkeys(iterable, value=None, /)

Створіть новий словник із ключами з iterable і значеннями, встановленими на value.

fromkeys() — це метод класу, який повертає новий словник. value за замовчуванням None. Усі значення стосуються лише одного екземпляра, тому загалом не має сенсу, щоб value було змінним об’єктом, таким як порожній список. Щоб отримати різні значення, замість цього використовуйте dict comprehension.

get(key, default=None)

Повертає значення для key, якщо key є в словнику, інакше за замовчуванням. Якщо default не вказано, за замовчуванням буде None, тому цей метод ніколи не викликає KeyError.

items()

Повертає нове подання елементів словника (пари «(ключ, значення)»). Перегляньте документацію об’єктів перегляду.

keys()

Повернути новий вигляд ключів словника. Перегляньте документацію об’єктів перегляду.

pop(key[, default])

Якщо key є у словнику, видаліть його та поверніть його значення, інакше поверніть default. Якщо default не вказано, а key немає в словнику, виникає KeyError.

popitem()

Видалити та повернути пару (ключ, значення) зі словника. Пари повертаються в порядку LIFO.

popitem() корисний для деструктивного повторення словника, як це часто використовується в набір алгоритмів. Якщо словник порожній, виклик popitem() викликає KeyError.

Змінено в версії 3.7: Замовлення LIFO тепер гарантовано. У попередніх версіях popitem() повертав довільну пару ключ/значення.

reversed(d)

Повертає зворотний ітератор над ключами словника. Це ярлик для reversed(d.keys()).

Added in version 3.8.

setdefault(key, default=None)

Якщо key є в словнику, поверніть його значення. Якщо ні, вставте ключ зі значенням default і поверніть default. default за замовчуванням None.

update([other])

Оновіть словник парами ключ/значення з other, перезаписавши існуючі ключі. Повернути Жодного.

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

Повернути нове подання значень словника. Перегляньте документацію об’єктів перегляду.

Порівняння рівності між одним переглядом dict.values() та іншим завжди повертатиме False. Це також стосується порівняння dict.values() із собою:

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

d | other

Створіть новий словник із об’єднаними ключами та значеннями d та other, які мають бути словниками. Значення other мають пріоритет, коли d та other мають спільні ключі.

Added in version 3.9.

d |= other

Оновіть словник d ключами та значеннями з other, які можуть бути mapping або iterable пар ключ/значення. Значення other мають пріоритет, коли d та other мають спільні ключі.

Added in version 3.9.

Словники порівнюються рівними тоді і тільки тоді, коли вони мають однакові пари (ключ, значення) (незалежно від порядку). Порівняння порядку (“ <“, „<=“, „> =“, „>“) викликає TypeError.

Словники зберігають порядок вставки. Зауважте, що оновлення ключа не впливає на порядок. Ключі, додані після видалення, вставляються в кінці.

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

Змінено в версії 3.7: Порядок словника гарантовано буде порядком вставки. Така поведінка була деталлю реалізації CPython від 3.6.

Словники та перегляди словників є оборотними.

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

Змінено в версії 3.8: Словники тепер оборотні.

Дивись також

types.MappingProxyType можна використовувати для створення перегляду dict лише для читання.

Об’єкти перегляду словника

Об’єкти, які повертаються dict.keys(), dict.values() і dict.items(), є об’єктами перегляду. Вони забезпечують динамічний перегляд статей словника, що означає, що коли словник змінюється, перегляд відображає ці зміни.

Перегляди словників можна повторювати, щоб отримати відповідні дані та підтримувати тести членства:

len(dictview)

Повернути кількість статей у словнику.

iter(dictview)

Повертає ітератор над ключами, значеннями або елементами (представленими у вигляді кортежів (ключ, значення)) у словнику.

Ключі та значення повторюються в порядку вставки. Це дозволяє створювати пари (значення, ключ) за допомогою zip(): pairs = zip(d.values(), d.keys()). Інший спосіб створити той самий список: pairs = [(v, k) for (k, v) in d.items()].

Ітерація подання під час додавання чи видалення записів у словнику може викликати RuntimeError або не вдається виконати ітерацію по всіх записах.

Змінено в версії 3.7: Порядок словника гарантовано буде порядком вставки.

x in dictview

Повертає True, якщо x міститься в ключах, значеннях або елементах основного словника (в останньому випадку x має бути кортежем (ключ, значення)).

reversed(dictview)

Повертає зворотний ітератор над ключами, значеннями або елементами словника. Подання буде повторено в порядку, зворотному до вставки.

Змінено в версії 3.8: Перегляди словника тепер оборотні.

dictview.mapping

Повертає types.MappingProxyType, який обгортає вихідний словник, на який посилається перегляд.

Added in version 3.10.

Keys views are set-like since their entries are unique and hashable. Items views also have set-like operations since the (key, value) pairs are unique and the keys are hashable. If all values in an items view are hashable as well, then the items view can interoperate with other sets. (Values views are not treated as set-like since the entries are generally not unique.) For set-like views, all of the operations defined for the abstract base class collections.abc.Set are available (for example, ==, <, or ^). While using set operators, set-like views accept any iterable as the other operand, unlike sets which only accept sets as the input.

Приклад використання перегляду словника:

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

Типи менеджера контексту

Оператор Python with підтримує концепцію контексту виконання, визначеного менеджером контексту. Це реалізовано за допомогою пари методів, які дозволяють визначеним користувачем класам визначати контекст виконання, який вводиться перед виконанням тіла оператора та виходить, коли оператор закінчується:

contextmanager.__enter__()

Введіть контекст середовища виконання та поверніть або цей об’єкт, або інший об’єкт, пов’язаний із контекстом середовища виконання. Значення, яке повертає цей метод, прив’язується до ідентифікатора в пункті as операторів with за допомогою цього менеджера контексту.

Прикладом контекстного менеджера, який повертає сам себе, є file object. Файлові об’єкти повертаються з __enter__(), щоб дозволити використовувати open() як вираз контексту в операторі with.

Прикладом менеджера контексту, який повертає пов’язаний об’єкт, є той, який повертає decimal.localcontext(). Ці менеджери встановлюють активний десятковий контекст на копію вихідного десяткового контексту, а потім повертають копію. Це дозволяє вносити зміни до поточного десяткового контексту в тілі оператора with, не впливаючи на код поза оператором with.

contextmanager.__exit__(exc_type, exc_val, exc_tb)

Вийдіть із контексту виконання та поверніть логічний прапор, який вказує, чи має бути придушено будь-який виняток, який стався. Якщо виняток стався під час виконання тіла оператора with, аргументи містять тип винятку, значення та інформацію про відстеження. В іншому випадку всі три аргументи є Жодним.

Повернення цього методу справжнього значення призведе до того, що оператор with придушить виняток і продовжить виконання з оператором, який слідує безпосередньо за оператором with. В іншому випадку виняткова ситуація продовжує поширюватися після завершення виконання цього методу. Винятки, які виникають під час виконання цього методу, замінять будь-які винятки, які виникли в тілі оператора with.

The exception passed in should never be reraised explicitly - instead, this method should return a false value to indicate that the method completed successfully and does not want to suppress the raised exception. This allows context management code to easily detect whether or not an __exit__() method has actually failed.

Python визначає декілька контекстних менеджерів для підтримки легкої синхронізації потоків, швидкого закриття файлів чи інших об’єктів і простішого маніпулювання активним десятковим арифметичним контекстом. Конкретні типи не розглядаються спеціально за межами їх реалізації в протоколі керування контекстом. Перегляньте модуль contextlib для деяких прикладів.

generators Python і декоратор contextlib.contextmanager забезпечують зручний спосіб реалізації цих протоколів. Якщо функція-генератор прикрашена декоратором contextlib.contextmanager, вона повертатиме менеджер контексту, який реалізує необхідні методи __enter__() і __exit__(), а не ітератор, створений недекорованою функцією генератора.

Зауважте, що немає спеціального слота для жодного з цих методів у структурі типу для об’єктів Python в API Python/C. Типи розширень, які хочуть визначити ці методи, повинні надати їх як звичайний доступний метод Python. Порівняно з накладними витратами на налаштування контексту виконання, накладні витрати на пошук словника одного класу є незначними.

Типи анотацій типу — Загальний псевдонім, Об’єднання

Основними вбудованими типами для анотацій типу є Generic Alias і Union.

Загальний тип псевдоніма

Об’єкти GenericAlias зазвичай створюються індексом класу. Найчастіше вони використовуються з контейнерними класами, такими як list або dict. Наприклад, list[int] є об’єктом GenericAlias, створеним шляхом підписання класу list з аргументом int. Об’єкти GenericAlias призначені насамперед для використання з анотаціями типу.

Примітка

Як правило, індекс класу можливий, лише якщо клас реалізує спеціальний метод __class_getitem__().

Об’єкт GenericAlias діє як проксі для generic type, реалізуючи параметризовані генерики.

Для класу-контейнера аргумент(и), що надаються підписці класу, може вказувати тип(и) елементів, які містить об’єкт. Наприклад, set[bytes] можна використовувати в анотаціях типу для позначення set, у якому всі елементи мають тип bytes.

Для класу, який визначає __class_getitem__(), але не є контейнером, аргумент(и), що надаються до підписки класу, часто вказуватиме тип(и) повернення одного або кількох методів, визначених для об’єкта . Наприклад, регулярні вирази можна використовувати як для типу даних str, так і для типу даних bytes:

• Якщо x = re.search('foo', 'foo'), x буде об’єктом re.Match, де повертаються значення x.group(0 ) і x[0] будуть мати тип str. Ми можемо представити цей тип об’єктів в анотаціях типу за допомогою GenericAlias re.Match[str].

• Якщо y = re.search(b'bar', b'bar') (зверніть увагу на b для bytes), y також буде екземпляром re.Match, але повертані значення y.group(0) і y[0] будуть мати тип bytes. В анотаціях типів ми б представили цю різноманітність об’єктів re.Match за допомогою re.Match[bytes].

Об’єкти GenericAlias є екземплярами класу types.GenericAlias, який також можна використовувати для безпосереднього створення об’єктів GenericAlias.

T[X, Y, ...]

Створює Generic Alias, що представляє тип T, параметризований типами X, Y тощо залежно від T, що використовується. Наприклад, функція, яка очікує list, що містить елементи float:

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

Інший приклад для об’єктів mapping з використанням dict, який є загальним типом, який очікує двох параметрів типу, що представляють тип ключа та тип значення. У цьому прикладі функція очікує dict з ключами типу str і значеннями типу int:

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

Вбудовані функції isinstance() і issubclass() не приймають типи GenericAlias для свого другого аргументу:

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

Середовище виконання Python не вимагає анотацій типу. Це поширюється на загальні типи та їхні параметри типу. Під час створення об’єкта-контейнера з GenericAlias елементи в контейнері не перевіряються на їх тип. Наприклад, наступний код не рекомендується, але працюватиме без помилок:

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

Крім того, параметризовані генерики стирають параметри типу під час створення об’єкта:

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

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

Виклик repr() або str() у загальному показує параметризований тип:

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

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

Метод __getitem__() загальних контейнерів викличе виняток, щоб заборонити такі помилки, як dict[str][str]:

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

Однак такі вирази дійсні, коли використовуються змінні типу. Індекс має містити стільки елементів, скільки елементів змінних типу в об’єкті GenericAlias __args__.

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

Стандартні загальні класи

Наступні стандартні бібліотечні класи підтримують параметризовані генерики. Цей список не є вичерпним.

• tuple

• list

• dict

• set

• frozenset

• type

• collections.deque

• collections.defaultdict

• collections.OrderedDict

• collections.Counter

• collections.ChainMap

• collections.abc.Awaitable

• collections.abc.Coroutine

• collections.abc.AsyncIterable

• collections.abc.AsyncIterator

• collections.abc.AsyncGenerator

• collections.abc.Iterable

• collections.abc.Iterator

• collections.abc.Generator

• collections.abc.Reversible

• collections.abc.Container

• collections.abc.Collection

• collections.abc.Callable

• collections.abc.Set

• collections.abc.MutableSet

• collections.abc.Mapping

• collections.abc.MutableMapping

• collections.abc.Sequence

• collections.abc.MutableSequence

• collections.abc.ByteString

• collections.abc.MappingView

• collections.abc.KeysView

• collections.abc.ItemsView

• collections.abc.ValuesView

• contextlib.AbstractContextManager

• contextlib.AbstractAsyncContextManager

• dataclasses.Field

• functools.cached_property

• functools.partialmethod

• os.PathLike

• queue.LifoQueue

• queue.Queue

• queue.PriorityQueue

• queue.SimpleQueue

• re.Патерн

• re.Match

• полиця.BsdDbShelf

• полиця.DbfilenameShelf

• полиця.Полиця

• types.MappingProxyType

• weakref.WeakKeyDictionary

• weakref.WeakMethod

• weakref.WeakSet

• weakref.WeakValueDictionary

Спеціальні атрибути об’єктів GenericAlias

Усі параметризовані генерики реалізують спеціальні атрибути лише для читання.

genericalias.__origin__

Цей атрибут вказує на непараметризований загальний клас:

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

genericalias.__args__

Цей атрибут є tuple (можливо, довжиною 1) загальних типів, переданих до оригінального __class_getitem__() загального класу:

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

genericalias.__parameters__

Цей атрибут є ліниво обчисленим кортежем (можливо, порожнім) унікальних змінних типу, знайдених у __args__:

>>> from typing import TypeVar

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

Примітка

Об’єкт GenericAlias з параметрами typing.ParamSpec може не мати правильних __parameters__ після заміни, тому що typing.ParamSpec призначений насамперед для статичної перевірки типу.

genericalias.__unpacked__

A boolean that is true if the alias has been unpacked using the * operator (see TypeVarTuple).

Added in version 3.11.

Дивись також

PEP 484 - підказки типу

Представляємо структуру Python для анотацій типів.

PEP 585 - Універсальні підказки типів у стандартних колекціях

Представляємо можливість нативної параметризації класів стандартної бібліотеки, якщо вони реалізують спеціальний метод класу __class_getitem__().

Узагальнення, визначені користувачем узагальнення і typing.Generic

Документація про те, як реалізувати загальні класи, які можна параметризувати під час виконання та розуміти статичними засобами перевірки типів.

Added in version 3.9.

Тип союзу

Об’єкт об’єднання містить значення операції | (порозрядної або) на кількох об’єктах типу. Ці типи призначені насамперед для анотацій типу. Вираз типу об’єднання забезпечує чіткіший синтаксис підказки типу порівняно з typing.Union.

X | Y | ...

Визначає об’єкт об’єднання, який містить типи X, Y і так далі. X | Y означає X або Y. Це еквівалентно typing.Union[X, Y]. Наприклад, наступна функція очікує аргумент типу int або float:

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

Примітка

The | operand cannot be used at runtime to define unions where one or more members is a forward reference. For example, int | "Foo", where "Foo" is a reference to a class not yet defined, will fail at runtime. For unions which include forward references, present the whole expression as a string, e.g. "int | Foo".

union_object == other

Об’єкти об’єднання можна перевірити на рівність з іншими об’єктами об’єднання. Подробиці:

• Союзи союзів сплощені:

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

• Зайві типи видаляються:

  int | str | int == int | str
  

• Під час порівняння об’єднань порядок ігнорується:

  int | str == str | int
  

• Він сумісний з typing.Union:

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

• Необов’язкові типи можуть бути написані як об’єднання з None:

  str | None == typing.Optional[str]
  

isinstance(obj, union_object)

issubclass(obj, union_object)

Виклики isinstance() і issubclass() також підтримуються з об’єктом об’єднання:

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

However, parameterized generics in union objects cannot be checked:

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

Доступ до відкритого користувачем типу для об’єкта union можна отримати з types.UnionType і використовувати для перевірки isinstance(). Об’єкт не може бути створений із типу:

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

Примітка

The __or__() method for type objects was added to support the syntax X | Y. If a metaclass implements __or__(), the Union may override it:

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

Дивись також

PEP 604 – PEP пропонує X | Синтаксис Y і тип Union.

Added in version 3.10.

Інші вбудовані типи

Інтерпретатор підтримує кілька інших видів об’єктів. Більшість із них підтримує лише одну або дві операції.

Модулі

Єдиною спеціальною операцією над модулем є доступ до атрибутів: m.name, де m — це модуль, а name отримує доступ до імені, визначеного в таблиці символів m. Модулю можна призначити атрибути. (Зауважте, що оператор import не є, строго кажучи, операцією над об’єктом модуля; import foo не вимагає існування об’єкта модуля з назвою foo, скоріше для цього потрібен (зовнішній) визначення для модуля з назвою foo десь.)

Спеціальним атрибутом кожного модуля є __dict__. Це словник, що містить таблицю символів модуля. Зміна цього словника фактично змінить таблицю символів модуля, але пряме призначення атрибуту __dict__ неможливо (ви можете написати m.__dict__['a'] = 1, що визначає m.a буде 1, але ви не можете написати m.__dict__ = {}). Не рекомендується безпосередньо змінювати __dict__.

Модулі, вбудовані в інтерпретатор, записуються так: <module 'sys' (built-in)>. Якщо завантажуються з файлу, вони записуються як <module 'os' from '/usr/local/lib/pythonX.Y/os.pyc'>.

Класи та екземпляри класів

Перегляньте Об’єкти, значення та типи і Визначення класів для них.

Функції

Функціональні об’єкти створюються визначеннями функцій. Єдина операція над об’єктом-функцією – це викликати його: func(список-аргументів).

Насправді існує два види функціональних об’єктів: вбудовані функції та функції, визначені користувачем. Обидва підтримують однакову операцію (виклик функції), але реалізація різна, отже, різні типи об’єктів.

Перегляньте Визначення функцій для отримання додаткової інформації.

методи

Methods are functions that are called using the attribute notation. There are two flavors: built-in methods (such as append() on lists) and class instance method. Built-in methods are described with the types that support them.

If you access a method (a function defined in a class namespace) through an instance, you get a special object: a bound method (also called instance method) object. When called, it will add the self argument to the argument list. Bound methods have two special read-only attributes: m.__self__ is the object on which the method operates, and m.__func__ is the function implementing the method. Calling m(arg-1, arg-2, ..., arg-n) is completely equivalent to calling m.__func__(m.__self__, arg-1, arg-2, ..., arg-n).

Like function objects, bound method objects support getting arbitrary attributes. However, since method attributes are actually stored on the underlying function object (method.__func__), setting method attributes on bound methods is disallowed. Attempting to set an attribute on a method results in an AttributeError being raised. In order to set a method attribute, you need to explicitly set it on the underlying function object:

>>> class C:
...     def method(self):
...         pass
...
>>> c = C()
>>> c.method.whoami = 'my name is method'  # can't set on the method
Traceback (most recent call last):
  File "<stdin>", line 1, in <module>
AttributeError: 'method' object has no attribute 'whoami'
>>> c.method.__func__.whoami = 'my name is method'
>>> c.method.whoami
'my name is method'

See Методи екземплярів for more information.

Об’єкти коду

Code objects are used by the implementation to represent «pseudo-compiled» executable Python code such as a function body. They differ from function objects because they don’t contain a reference to their global execution environment. Code objects are returned by the built-in compile() function and can be extracted from function objects through their __code__ attribute. See also the code module.

Accessing __code__ raises an auditing event object.__getattr__ with arguments obj and "__code__".

Об’єкт коду можна виконати або оцінити, передавши його (замість вихідного рядка) у вбудовані функції exec() або eval().

Перегляньте Стандартна ієрархія типів для отримання додаткової інформації.

Об’єкти типу

Об’єкти типу представляють різні типи об’єктів. Доступ до типу об’єкта здійснюється за допомогою вбудованої функції type(). Над типами немає спеціальних операцій. Стандартний модуль types визначає імена для всіх стандартних вбудованих типів.

Типи записуються так: <class 'int'>.

Нульовий об’єкт

Цей об’єкт повертають функції, які явно не повертають значення. Він не підтримує ніяких спеціальних операцій. Існує рівно один нульовий об’єкт із назвою None (вбудована назва). type(None)() створює той самий синглтон.

Він записується як None.

Об’єкт «Еліпсис».

Цей об’єкт зазвичай використовується для нарізки (див. Нарізки). Він не підтримує ніяких спеціальних операцій. Існує рівно один об’єкт з крапкою, який називається Ellipsis (вбудована назва). type(Ellipsis)() виробляє Ellipsis синглтон.

Він записується як Еліпсис або ....

Об’єкт NotImplemented

This object is returned from comparisons and binary operations when they are asked to operate on types they don’t support. See Порівняння for more information. There is exactly one NotImplemented object. type(NotImplemented)() produces the singleton instance.

It is written as NotImplemented.

Внутрішні об’єкти

See Стандартна ієрархія типів for this information. It describes stack frame objects, traceback objects, and slice objects.

Спеціальні атрибути

Реалізація додає кілька спеціальних атрибутів лише для читання до кількох типів об’єктів, де вони актуальні. Деякі з них не повідомляються вбудованою функцією dir().

definition.__name__

Ім’я класу, функції, методу, дескриптора або екземпляра генератора.

definition.__qualname__

qualified name класу, функції, методу, дескриптора або екземпляра генератора.

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.

Integer string conversion length limitation

CPython has a global limit for converting between int and str to mitigate denial of service attacks. This limit only applies to decimal or other non-power-of-two number bases. Hexadecimal, octal, and binary conversions are unlimited. The limit can be configured.

The int type in CPython is an arbitrary length number stored in binary form (commonly known as a «bignum»). There exists no algorithm that can convert a string to a binary integer or a binary integer to a string in linear time, unless the base is a power of 2. Even the best known algorithms for base 10 have sub-quadratic complexity. Converting a large value such as int('1' * 500_000) can take over a second on a fast CPU.

Limiting conversion size offers a practical way to avoid CVE 2020-10735.

The limit is applied to the number of digit characters in the input or output string when a non-linear conversion algorithm would be involved. Underscores and the sign are not counted towards the limit.

When an operation would exceed the limit, a ValueError is raised:

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

The default limit is 4300 digits as provided in sys.int_info.default_max_str_digits. The lowest limit that can be configured is 640 digits as provided in sys.int_info.str_digits_check_threshold.

Verification:

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

Affected APIs

The limitation only applies to potentially slow conversions between int and str or bytes:

• int(string) with default base 10.

• int(string, base) for all bases that are not a power of 2.

• str(integer).

• repr(integer).

• any other string conversion to base 10, for example f"{integer}", "{}".format(integer), or b"%d" % integer.

The limitations do not apply to functions with a linear algorithm:

• int(string, base) with base 2, 4, 8, 16, or 32.

• int.from_bytes() and int.to_bytes().

• hex(), oct(), bin().

• Міні-мова специфікації формату for hex, octal, and binary numbers.

• str to float.

• str to decimal.Decimal.

Configuring the limit

Before Python starts up you can use an environment variable or an interpreter command line flag to configure the limit:

• PYTHONINTMAXSTRDIGITS, e.g. PYTHONINTMAXSTRDIGITS=640 python3 to set the limit to 640 or PYTHONINTMAXSTRDIGITS=0 python3 to disable the limitation.

• -X int_max_str_digits, e.g. python3 -X int_max_str_digits=640

• sys.flags.int_max_str_digits contains the value of PYTHONINTMAXSTRDIGITS or -X int_max_str_digits. If both the env var and the -X option are set, the -X option takes precedence. A value of -1 indicates that both were unset, thus a value of sys.int_info.default_max_str_digits was used during initialization.

From code, you can inspect the current limit and set a new one using these sys APIs:

• sys.get_int_max_str_digits() and sys.set_int_max_str_digits() are a getter and setter for the interpreter-wide limit. Subinterpreters have their own limit.

Information about the default and minimum can be found in sys.int_info:

• sys.int_info.default_max_str_digits is the compiled-in default limit.

• sys.int_info.str_digits_check_threshold is the lowest accepted value for the limit (other than 0 which disables it).

Added in version 3.11.

Застереження

Setting a low limit can lead to problems. While rare, code exists that contains integer constants in decimal in their source that exceed the minimum threshold. A consequence of setting the limit is that Python source code containing decimal integer literals longer than the limit will encounter an error during parsing, usually at startup time or import time or even at installation time - anytime an up to date .pyc does not already exist for the code. A workaround for source that contains such large constants is to convert them to 0x hexadecimal form as it has no limit.

Test your application thoroughly if you use a low limit. Ensure your tests run with the limit set early via the environment or flag so that it applies during startup and even during any installation step that may invoke Python to precompile .py sources to .pyc files.

Recommended configuration

The default sys.int_info.default_max_str_digits is expected to be reasonable for most applications. If your application requires a different limit, set it from your main entry point using Python version agnostic code as these APIs were added in security patch releases in versions before 3.12.

Приклад:

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

If you need to disable it entirely, set it to 0.

Виноски

[1]

Додаткову інформацію про ці спеціальні методи можна знайти в довідковому посібнику Python (Базове налаштування).

[2]

Як наслідок, список [1, 2] вважається рівним [1.0, 2.0], і аналогічно для кортежів.

[3]

Мабуть, оскільки аналізатор не може визначити тип операндів.

[4] (1,2,3,4)

Регістр символів — це символи загальної категорії, які мають одну з таких властивостей: «Lu» (літера, верхній регістр), «Ll» (літера, нижній регістр) або «Lt» (літера, регістр заголовка).

[5] (1,2)

Щоб відформатувати лише кортеж, ви повинні надати одиночний кортеж, єдиним елементом якого є кортеж, який потрібно відформатувати.