Built-in TypesВстроенные типы

В следующих разделах описываются стандартные типы, встроенные в интерпретатор.

Основные встроенные типы: числовые, последовательности, отображения, классы, экземпляры и исключения.

Некоторые классы коллекций являются изменяемыми. Методы, которые добавляют, удаляют или переупорядочивают элементы на месте и не возвращают конкретный элемент, никогда не возвращают сам экземпляр коллекции, а None.

Некоторые операции поддерживаются несколькими типами объектов; в частности, практически все объекты можно сравнивать на равенство, проверять на истинность и преобразовывать в строку (с помощью функции repr() или немного отличающейся функции str()). Последняя функция неявно используется, когда объект выводится функцией print().

Truth Value TestingПроверка истинности

Любой объект можно проверить на истинность для использования в условии if или while или в качестве операнда логических операций ниже.

По умолчанию объект считается истинным, если его класс не определяет метод __bool__(), возвращающий False, или метод __len__(), возвращающий ноль при вызове с этим объектом. [1] Если один из методов при вызове вызывает исключение, исключение распространяется, и объект не имеет значения истинности (например, NotImplemented). Вот большинство встроенных объектов, считающихся ложными:

• константы, определенные как ложные: 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. Это оператор короткого замыкания, поэтому второй аргумент вычисляется, только если первый равен false.

2. Это оператор короткого замыкания, поэтому второй аргумент вычисляется, только если первый равен true.

3. not имеет более низкий приоритет, чем небулевы операторы, поэтому not a == b интерпретируется как not (a == b), а a == not b является синтаксической ошибкой.

ComparisonsСравнения

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

В этой таблице приведены операции сравнения:

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

Если не указано иное, объекты разных типов никогда не сравниваются как равные. Оператор == всегда определён, но для некоторых типов объектов (например, объектов классов) он эквивалентен is. Операторы <, <=, > и >= определены только там, где они имеют смысл; например, они возбуждают исключение TypeError, если один из аргументов является комплексным числом.

Неидентичные экземпляры класса обычно сравниваются как неравные, если только класс не определяет метод __eq__().

Экземпляры класса не могут быть упорядочены относительно других экземпляров того же класса или объектов других типов, если класс не определяет достаточное количество методов __lt__(), __le__(), __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' к числовому литералу даёт мнимое число (комплексное число с нулевой действительной частью), которое можно добавить к целому числу или числу с плавающей запятой, чтобы получить комплексное число с действительной и мнимой частями.

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

Python полностью поддерживает смешанную арифметику: когда бинарный арифметический оператор имеет операнды разных встроенных числовых типов, операнд с «более узким» типом расширяется до типа другого операнда:

• Если оба аргумента являются комплексными числами, преобразование не выполняется;

• если хотя бы один аргумент является комплексным числом или числом с плавающей запятой, другой преобразуется в число с плавающей запятой;

• в противном случае оба должны быть целыми числами, и преобразование не требуется.

Арифметика с комплексными и действительными операндами определяется обычными математическими формулами, например:

x + complex(u, v) = complex(x + u, v)
x * complex(u, v) = complex(x * u, x * v)

Сравнение чисел разных типов ведёт себя так, как если бы сравнивались точные значения этих чисел. [2]

Все числовые типы (кроме комплексных) поддерживают следующие операции (о приоритетах операций см. Приоритет операторов):

Операция	Результат	Примечания	Полная документация
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).

   Смотрите стандарт Unicode для полного списка кодовых точек со свойством 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 .

Bitwise Operations on Integer TypesПобитовые операции над целочисленными типами

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

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

В этой таблице перечислены побитовые операции, отсортированные по возрастанию приоритета:

Операция	Результат	Примечания
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()) или более) даёт тот же результат, что и при бесконечном числе знаковых битов.

Additional Methods on Integer TypesДополнительные методы целочисленных типов

Тип 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)       # двоичное представление:  bin(-37) --> '-0b100101'
    s = s.lstrip('-0b') # удалить ведущие нули и знак минуса
    return len(s)       # len('100101') --> 6

Добавлено в версии 3.1.

int.bit_count()¶

Возвращает количество единиц в двоичном представлении абсолютного значения целого числа. Это также известно как число единичных битов (population count). Пример:

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

Эквивалентно:

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

Добавлено в версии 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, length=1, byteorder='big', signed=False):
    if byteorder == 'little':
        order = range(length)
    elif byteorder == 'big':
        order = reversed(range(length))
    else:
        raise ValueError("byteorder must be either 'little' or 'big'")

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

Добавлено в версии 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", самый значимый байт находится в конце массива байтов. Чтобы запросить собственный порядок байтов хост-системы, используйте sys.byteorder в качестве значения порядка байтов.

Аргумент 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

Добавлено в версии 3.2.

Изменено в версии 3.11: Добавлено значение аргумента по умолчанию для byteorder.

int.as_integer_ratio()¶

Возвращает пару целых чисел, отношение которых равно исходному целому числу и имеет положительный знаменатель. Целочисленное отношение целых чисел (целых) всегда представляет собой само целое число в качестве числителя и 1 в качестве знаменателя.

Добавлено в версии 3.8.

int.is_integer()¶

Возвращает True. Существует для совместимости с утиной типизацией с float.is_integer().

Добавлено в версии 3.12.

Additional Methods on FloatДополнительные методы float

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

classmethod float.from_number(x)¶

Метод класса для возврата числа с плавающей запятой, построенного из числа x.

Если аргумент является целым числом или числом с плавающей запятой, возвращается число с плавающей запятой с тем же значением (в пределах точности чисел с плавающей запятой Python). Если аргумент выходит за пределы диапазона Python float, будет возбуждено OverflowError.

Для обычного объекта Python x, float.from_number(x) делегирует вызов x.__float__(). Если __float__() не определён, то используется __index__().

Добавлено в версии 3.14.

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]

где необязательный sign может быть либо +, либо -, integer и fraction – строки шестнадцатеричных цифр, а exponent – десятичное целое число с необязательным ведущим знаком. Регистр не имеет значения, и должна быть хотя бы одна шестнадцатеричная цифра либо в целой части, либо в дробной. Этот синтаксис похож на синтаксис, указанный в разделе 6.4.4.2 стандарта C99, а также на синтаксис, используемый в Java 1.5 и более поздних версиях. В частности, вывод float.hex() может использоваться как шестнадцатеричный литерал с плавающей запятой в коде C или Java, а шестнадцатеричные строки, созданные символом формата %a в C или Double.toHexString в Java, принимаются float.fromhex().

Обратите внимание, что показатель степени записывается в десятичном, а не в шестнадцатеричном виде, и что он задаёт степень двойки, на которую умножается коэффициент. Например, шестнадцатеричная строка 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'

Additional Methods on ComplexДополнительные методы для комплексных чисел

Тип complex реализует numbers.Complex абстрактный базовый класс. complex также имеет следующие дополнительные методы.

classmethod complex.from_number(x)¶

Метод класса для преобразования числа в комплексное число.

Для обычного объекта Python x функция complex.from_number(x) делегирует вызов x.__complex__(). Если __complex__() не определён, используется __float__(). Если __float__() не определён, используется __index__().

Добавлено в версии 3.14.

Hashing of numeric typesХеширование числовых типов

Для чисел x и y, возможно разных типов, требуется, чтобы hash(x) == hash(y) выполнялось всякий раз, когда x == y (см. документацию метода __hash__() для подробностей). Ради простоты реализации и эффективности для различных числовых типов (включая int, float, decimal.Decimal и fractions.Fraction) хеш Python для числовых типов основан на единой математической функции, определённой для любого рационального числа, и, следовательно, применим ко всем экземплярам int и fractions.Fraction, а также ко всем конечным экземплярам float и decimal.Decimal. По существу, эта функция задаётся приведением по модулю P для фиксированного простого числа P. Значение P доступно в Python как атрибут modulus объекта sys.hash_info.

Особенность реализации CPython: В настоящее время используется простое число P = 2**31 - 1 на машинах с 32-битным long (C) и P = 2**61 - 1 на машинах с 64-битным long (C).

Вот правила подробно:

• Если x = m / n – неотрицательное рациональное число и n не делится на P, определите hash(x) как m * invmod(n, P) % P, где invmod(n, P) даёт обратное к n по модулю P.

• Если x = m / n – неотрицательное рациональное число и n делится на P (но 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 так, чтобы результат лежал в range(-2**(sys.hash_info.width - 1), 2**(sys.hash_info.width - 1)). Снова, если результат равен -1, он заменяется на -2.

Чтобы прояснить приведённые выше правила, вот пример кода Python, эквивалентного встроенной функции hash, для вычисления хеша рационального числа, 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
    # Удалить общие множители P. (Необязательно, если m и n уже взаимно просты.)
    while m % P == n % P == 0:
        m, n = m // P, n // P

    if n % P == 0:
        hash_value = sys.hash_info.inf
    else:
        # Малая теорема Ферма: pow(n, P-1, P) равно 1, поэтому
        # pow(n, P-2, P) даёт обратное к n по модулю 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):
    """Вычислить хеш числа с плавающей запятой 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):
    """Вычислить хеш комплексного числа z."""

    hash_value = hash_float(z.real) + sys.hash_info.imag * hash_float(z.imag)
    # выполнить знаковое приведение по модулю 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

Логический тип – bool

Логические значения представляют истинностные значения. Тип bool имеет ровно две константы: True и False.

Встроенная функция bool() преобразует любое значение в логическое, если это значение можно интерпретировать как истинностное (см. раздел Проверка истинности значения выше).

Для логических операций используйте логические операторы and, or и not. При применении побитовых операторов &, |, ^ к двум логическим значениям они возвращают bool, эквивалентный логическим операциям «и», «или», «исключающее или». Однако логические операторы and, or и != следует предпочитать &, | и ^.

Устарело с версии 3.12: Использование оператора побитового инвертирования ~ является устаревшим и вызовет ошибку в Python 3.16.

bool является подклассом int (см. Числовые типы – int, float, complex). Во многих числовых контекстах False и True ведут себя как целые числа 0 и 1 соответственно. Однако полагаться на это не рекомендуется; вместо этого явно преобразуйте с помощью int().

Iterator TypesТипы итераторов

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

Для поддержки итерируемости контейнерные объекты должны определить один метод:

container.__iter__()¶

Возвращает объект итератора. Объект должен поддерживать протокол итератора, описанный ниже. Если контейнер поддерживает разные типы итерации, можно добавить дополнительные методы для явного запроса итераторов для этих типов итерации. (Примером объекта, поддерживающего несколько форм итерации, может служить древовидная структура, которая поддерживает обход как в ширину, так и в глубину.) Этот метод соответствует слоту tp_iter структуры типа для объектов Python в Python/C API.

Сами объекты итератора должны поддерживать следующие два метода, которые вместе образуют протокол итератора:

iterator.__iter__()¶

Возвращает сам объект итератора. Это необходимо, чтобы как контейнеры, так и итераторы можно было использовать с операторами for и in. Этот метод соответствует слоту tp_iter структуры типа для объектов Python в Python/C API.

iterator.__next__()¶

Возвращает следующий элемент из итератора. Если элементов больше нет, возбуждает исключение StopIteration. Этот метод соответствует слоту tp_iternext структуры типа для объектов Python в Python/C API.

Python определяет несколько объектов-итераторов для поддержки итерации по общим и конкретным типам последовательностей, словарям и другим более специализированным формам. Конкретные типы не важны, кроме их реализации протокола итератора.

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

Generator TypesТипы генераторов

Генераторы Python предоставляют удобный способ реализации протокола итератора. Если метод __iter__() объекта-контейнера реализован как генератор, он автоматически вернёт объект-итератор (технически – объект-генератор), предоставляющий методы __iter__() и __next__(). Дополнительную информацию о генераторах можно найти в документации по выражению yield.

Типы последовательностей – list, tuple, range

Существуют три базовых типа последовательностей: списки, кортежи и объекты range. Дополнительные типы последовательностей, предназначенные для обработки двоичных данных и текстовых строк, описаны в соответствующих разделах.

Common Sequence OperationsОбщие операции с последовательностями

Большинство типов последовательностей, как изменяемых, так и неизменяемых, поддерживают операции, приведённые в следующей таблице. ABC collections.abc.Sequence предоставляется для упрощения корректной реализации этих операций в пользовательских типах последовательностей.

В таблице перечислены операции с последовательностями в порядке возрастания приоритета. В таблице s и t – последовательности одного типа, n, i, j и k – целые числа, а x – произвольный объект, удовлетворяющий любым ограничениям по типу и значению, налагаемым s.

Операции in и not in имеют тот же приоритет, что и операции сравнения. Операции + (конкатенация) и * (повторение) имеют тот же приоритет, что и соответствующие числовые операции. [3]

Операция	Результат	Примечания
x in s	True, если элемент s равен x, иначе False	(1)
x not in 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)(8)
s[i:j]	срез s от i до j	(3)(4)
s[i:j:k]	срез s от i до j с шагом k	(3)(5)
len(s)	длина s
min(s)	наименьший элемент s
max(s)	наибольший элемент 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 изменяет этот единственный список. Таким образом можно создать список из разных списков:

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

   Дополнительные пояснения доступны в FAQ: Как создать многомерный список?.

3. Если i или j отрицательны, индекс отсчитывается от конца последовательности s: используется len(s) + i или len(s) + j. Но обратите внимание, что -0 по-прежнему 0.

4. Срез s от i до j определяется как последовательность элементов с индексом k, таким что i <= k < j.

   • Если i опущено или None, используется 0.

   • Если j опущено или None, используется len(s).

   • Если i или j меньше -len(s), используется 0.

   • Если i или j больше len(s), используется 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. Возникает IndexError, если i находится вне диапазона последовательности.

Методы последовательностей

Типы последовательностей также поддерживают следующие методы:

sequence.count(value, /)¶

Возвращает общее количество вхождений value в sequence.

sequence.index(value[, start[, stop]])¶

Возвращает индекс первого вхождения value в sequence.

Вызывает ValueError, если value не найдено в sequence.

Аргументы start и stop позволяют эффективно искать подпоследовательности, начиная с start и заканчивая stop. Это примерно эквивалентно start + sequence[start:stop].index(value), только без копирования данных.

Предостережение

Не все типы последовательностей поддерживают передачу аргументов start и stop.

Immutable Sequence TypesНеизменяемые типы последовательностей

Единственная операция, которую неизменяемые типы последовательностей обычно реализуют и которая не реализована изменяемыми типами последовательностей – это поддержка встроенной функции hash().

Эта поддержка позволяет использовать неизменяемые последовательности, например экземпляры tuple, в качестве ключей dict и хранить их в экземплярах set и frozenset.

Попытка вычислить хеш от неизменяемой последовательности, содержащей нехешируемые значения, приводит к TypeError.

Mutable Sequence TypesИзменяемые типы последовательностей

Операции в следующей таблице определены для изменяемых типов последовательностей. ABC collections.abc.MutableSequence предоставляется для упрощения корректной реализации этих операций в пользовательских типах последовательностей.

В таблице s – это экземпляр изменяемого типа последовательности, t – любой итерируемый объект, а x – произвольный объект, удовлетворяющий любым ограничениям по типу и значению, накладываемым s (например, bytearray принимает только целые числа, удовлетворяющие ограничению значения 0 <= x <= 255).

Операция	Результат	Примечания
s[i] = x	элемент i последовательности s заменяется на x
del s[i]	удаляет элемент i из последовательности s
s[i:j] = t	срез s от i до j заменяется содержимым итерируемого объекта t
del s[i:j]	удаляет элементы 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 += t	расширяет s содержимым t (в основном аналогично s[len(s):len(s)] = t)
s *= n	обновляет s, повторяя его содержимое n раз	(2)

Примечания:

1. Если k не равно 1, t должна иметь ту же длину, что и заменяемый срез.

2. Значение n – целое число или объект, реализующий __index__(). Нулевые и отрицательные значения n очищают последовательность. Элементы последовательности не копируются; на них создаются множественные ссылки, как описано для s * n в разделе Общие операции с последовательностями.

Методы изменяемых последовательностей

Изменяемые типы последовательностей также поддерживают следующие методы:

sequence.append(value, /)¶

Добавляет значение в конец последовательности. Это эквивалентно записи seq[len(seq):len(seq)] = [value].

sequence.clear()¶

Добавлено в версии 3.3.

Удаляет все элементы из последовательности. Это эквивалентно записи del sequence[:].

sequence.copy()¶

Добавлено в версии 3.3.

Создаёт поверхностную копию последовательности. Это эквивалентно записи sequence[:].

Подсказка

Метод copy() не является частью MutableSequence ABC, но большинство конкретных изменяемых типов последовательностей предоставляют его.

sequence.extend(iterable, /)¶

Расширяет последовательность содержимым итерируемого объекта. В основном это то же самое, что запись seq[len(seq):len(seq)] = iterable.

sequence.insert(index, value, /)¶

Вставляет значение в последовательность по указанному индексу. Это эквивалентно записи sequence[index:index] = [value].

sequence.pop(index=-1, /)¶

Извлекает элемент по индексу и удаляет его из последовательности. По умолчанию удаляется и возвращается последний элемент последовательности.

sequence.remove(value, /)¶

Удаляет первый элемент из последовательности, где sequence[i] == value.

Возбуждает ValueError, если значение не найдено в последовательности.

sequence.reverse()¶

Изменяет порядок элементов последовательности на обратный на месте. Этот метод экономит память при обращении большой последовательности. Чтобы напомнить пользователям, что он работает с побочным эффектом, он возвращает None.

ListsСписки

Списки – это изменяемые последовательности, обычно используемые для хранения наборов однородных элементов (точная степень сходства которых зависит от приложения).

class list(iterable=(), /)¶

Списки могут быть созданы несколькими способами:

• С помощью пары квадратных скобок для обозначения пустого списка: []

• С помощью квадратных скобок, разделяя элементы запятыми: [a], [a, b, c]

• С помощью спискового включения: [x for x in iterable]

• С помощью конструктора типа: list() или list(iterable)

Конструктор создаёт список, элементы которого совпадают с элементами итерируемого объекта и расположены в том же порядке. Итерируемый объект может быть последовательностью, контейнером, поддерживающим итерацию, или объектом-итератором. Если итерируемый объект уже является списком, создаётся и возвращается его копия, аналогично iterable[:]. Например, list('abc') возвращает ['a', 'b', 'c'], а list( (1, 2, 3) ) возвращает [1, 2, 3]. Если аргумент не указан, конструктор создаёт новый пустой список, [].

Многие другие операции также создают списки, включая встроенную функцию sorted().

Списки реализуют все общие и изменяемые операции с последовательностями. Списки также предоставляют следующий дополнительный метод:

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

Этот метод сортирует список на месте, используя только < сравнения между элементами. Исключения не подавляются: если любая операция сравнения завершится ошибкой, вся сортировка завершится ошибкой (и список, вероятно, останется в частично изменённом состоянии).

sort() принимает два аргумента, которые могут быть переданы только по ключевым словам (аргументы, передаваемые только по ключевым словам):

key задаёт функцию одного аргумента, которая используется для извлечения ключа сравнения из каждого элемента списка (например, key=str.lower). Ключ, соответствующий каждому элементу списка, вычисляется один раз и затем используется для всего процесса сортировки. Значение по умолчанию None означает, что элементы списка сортируются напрямую без вычисления отдельного ключа.

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

reverse – это логическое значение. Если установлено в True, то элементы списка сортируются так, как если бы каждое сравнение было обращено.

Этот метод изменяет последовательность на месте для экономии места при сортировке большой последовательности. Чтобы напомнить пользователям, что он работает с побочным эффектом, он не возвращает отсортированную последовательность (используйте sorted() для явного запроса нового экземпляра отсортированного списка).

Метод sort() гарантированно стабилен. Сортировка стабильна, если она гарантирует неизменность относительного порядка элементов, которые сравниваются как равные – это полезно при многоэтапной сортировке (например, сначала по отделу, затем по уровню зарплаты).

Примеры сортировки и краткое руководство по сортировке см. в разделе Методы сортировки.

Деталь реализации CPython: Во время сортировки списка результат попыток изменить список или даже просмотреть его не определён. Реализация Python на C делает так, что список кажется пустым на время сортировки, и возбуждает ValueError, если может определить, что список был изменён во время сортировки.

Смотрите также

За подробной информацией о гарантиях потокобезопасности для объектов list обращайтесь к Thread safety for list objects.

TuplesКортежи

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

class tuple(iterable=(), /)¶

Кортежи могут быть созданы несколькими способами:

• С помощью пары круглых скобок для обозначения пустого кортежа: ()

• С помощью завершающей запятой для кортежа из одного элемента: a, или (a,)

• Разделяя элементы запятыми: a, b, c или (a, b, c)

• С помощью встроенной функции tuple(): tuple() или tuple(iterable)

Конструктор создаёт кортеж, элементы которого совпадают с элементами итерируемого объекта и расположены в том же порядке. Итерируемый объект может быть последовательностью, контейнером, поддерживающим итерацию, или объектом-итератором. Если итерируемый объект уже является кортежем, он возвращается без изменений. Например, tuple('abc') возвращает ('a', 'b', 'c'), а tuple( [1, 2, 3] ) возвращает (1, 2, 3). Если аргумент не указан, конструктор создаёт новый пустой кортеж, ().

Обратите внимание, что кортеж создаётся именно запятой, а не круглыми скобками. Скобки необязательны, за исключением пустого кортежа или случаев, когда они необходимы для устранения синтаксической неоднозначности. Например, f(a, b, c) – это вызов функции с тремя аргументами, а f((a, b, c)) – вызов функции с кортежем из трёх элементов в качестве единственного аргумента.

Кортежи реализуют все обычные операции последовательностей.

Для разнородных коллекций данных, где доступ по имени понятнее, чем доступ по индексу, collections.namedtuple() может быть более подходящим выбором, чем простой объект кортежа.

RangesДиапазоны

Тип range представляет неизменяемую последовательность чисел и обычно используется для циклического повторения определённое количество раз в циклах for.

class range(stop, /)¶

class range(start, stop, step=1, /)

Аргументы конструктора range должны быть целыми числами (либо встроенный int, либо любой объект, реализующий специальный метод __index__()). Если аргумент step опущен, по умолчанию используется 1. Если аргумент start опущен, по умолчанию используется 0. Если step равен нулю, возбуждается ValueError.

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

Для отрицательного step содержимое диапазона по-прежнему определяется формулой 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 и предоставляют такие возможности, как проверка принадлежности, поиск индекса элемента, срезы и поддержка отрицательных индексов (см. Последовательные типы – 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) == range(2, 1, 3) или range(0, 3, 2) == range(0, 4, 2).)

Изменено в версии 3.2: Реализует абстрактный базовый класс Sequence. Поддержка срезов и отрицательных индексов. Проверка принадлежности объектов int за константное время вместо перебора всех элементов.

Изменено в версии 3.3: Определены операторы ‘==’ и ‘!=’ для сравнения объектов диапазона на основе последовательности значений, которые они задают (вместо сравнения на основе идентичности объектов).

Добавлены атрибуты start, stop и step.

Смотрите также

• Рецепт linspace показывает, как реализовать ленивую версию диапазона, подходящую для работы с числами с плавающей запятой.

Text and Binary Sequence Type Methods SummaryСводка методов текстовых и бинарных последовательностей

В следующей таблице приведены методы текстовых и бинарных последовательностей, сгруппированные по категориям.

Категория	методы str				методы bytes и bytearray
Форматирование	str.format()
	str.format_map()
	f-строки
	Форматирование строк в стиле printf				Форматирование байтов в стиле printf
Поиск и замена	str.find()	str.rfind()			bytes.find()	bytes.rfind()
	str.index()	str.rindex()			bytes.index()	bytes.rindex()
	str.startswith()				bytes.startswith()
	str.endswith()				bytes.endswith()
	str.count()				bytes.count()
	str.replace()				bytes.replace()
Разделение и объединение	str.split()		str.rsplit()		bytes.split()		bytes.rsplit()
	str.splitlines()				bytes.splitlines()
	str.partition()				bytes.partition()
	str.rpartition()				bytes.rpartition()
	str.join()				bytes.join()
Классификация строк	str.isalpha()				bytes.isalpha()
	str.isdecimal()
	str.isdigit()				bytes.isdigit()
	str.isnumeric()
	str.isalnum()				bytes.isalnum()
	str.isidentifier()
	str.islower()				bytes.islower()
	str.isupper()				bytes.isupper()
	str.istitle()				bytes.istitle()
	str.isspace()				bytes.isspace()
	str.isprintable()
Изменение регистра	str.lower()				bytes.lower()
	str.upper()				bytes.upper()
	str.casefold()
	str.capitalize()				bytes.capitalize()
	str.title()				bytes.title()
	str.swapcase()				bytes.swapcase()
Дополнение и удаление пробелов	str.ljust()		str.rjust()		bytes.ljust()		bytes.rjust()
	str.center()				bytes.center()
	str.expandtabs()				bytes.expandtabs()
	str.strip()				bytes.strip()
	str.lstrip()			str.rstrip()	bytes.lstrip()			bytes.rstrip()
Преобразование и кодирование	str.translate()				bytes.translate()
	str.maketrans()				bytes.maketrans()
	str.encode()
					bytes.decode()

Тип текстовой последовательности – str

Текстовые данные в Python обрабатываются с помощью объектов str, или строк. Строки являются неизменяемыми последовательностями кодовых точек Unicode. Строковые литералы записываются различными способами:

• Одинарные кавычки: 'allows embedded "double" quotes'

• Двойные кавычки: "allows embedded 'single' quotes"

• Тройные кавычки: '''Three single quotes''', """Three double quotes"""

Строки в тройных кавычках могут занимать несколько строк – все сопутствующие пробельные символы будут включены в строковый литерал.

Строковые литералы, являющиеся частью одного выражения и разделённые только пробельными символами, будут неявно преобразованы в один строковый литерал. То есть ("spam " "eggs") == "spam eggs".

Смотрите Строковые и байтовые литералы для получения дополнительной информации о различных формах строковых литералов, включая поддерживаемые управляющие последовательности, и префикс r («сырой»), который отключает обработку большинства управляющих последовательностей.

Строки также могут быть созданы из других объектов с помощью конструктора str.

Поскольку отдельного типа «символ» не существует, индексация строки возвращает строку длины 1. То есть для непустой строки s, s[0] == s[0:1].

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

Изменено в версии 3.3: Для обратной совместимости с серией Python 2 префикс u снова разрешён для строковых литералов. Он не влияет на значение строковых литералов и не может комбинироваться с префиксом r.

class str(*, encoding='utf-8', errors='strict')¶

class str(object)

class str(object, encoding, errors='strict')

class str(object, *, errors)

Возвращает строковое представление object. Если object не указан, возвращает пустую строку. В противном случае поведение str() зависит от того, указаны ли encoding или errors, как показано ниже.

Если не указаны ни encoding, ни errors, str(object) возвращает type(object).__str__(object), что является «неформальным» или хорошо выводимым строковым представлением object. Для строковых объектов это сама строка. Если object не имеет метода __str__(), то str() возвращает repr(object).

Если указаны хотя бы один из encoding или errors, object должен быть байтово-подобным объектом (например, bytes или bytearray). В этом случае, если object является объектом bytes (или bytearray), то str(bytes, encoding, errors) эквивалентно bytes.decode(encoding, errors). В противном случае байтовый объект, лежащий в основе буферного объекта, получается перед вызовом bytes.decode(). Смотрите Типы двоичных последовательностей – bytes, bytearray, memoryview и Протокол буфера для получения информации о буферных объектах.

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

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

Для получения дополнительной информации о классе str и его методах смотрите Тип текстовой последовательности – str и раздел Методы строк ниже. Для вывода форматированных строк смотрите разделы f-строки и Синтаксис строк форматирования. Кроме того, смотрите раздел Службы обработки текста.

String MethodsМетоды строк

Строки реализуют все общие операции последовательностей, а также дополнительные методы, описанные ниже.

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

Раздел Службы обработки текста стандартной библиотеки охватывает ряд других модулей, предоставляющих различные утилиты для работы с текстом (включая поддержку регулярных выражений в модуле re).

str.capitalize()¶

Возвращает копию строки, в которой первый символ переведён в верхний регистр, а остальные – в нижний.

Изменено в версии 3.8: Теперь первый символ преобразуется в заглавный, а не просто в верхний регистр. Это означает, что у таких символов, как диграфы, будет заглавной только первая буква, а не весь символ целиком.

str.casefold()¶

Возвращает копию строки, приведённую к регистру, пригодному для сравнения без учёта регистра. Такие строки могут использоваться для сравнения без учёта регистра.

Приведение к регистру (casefolding) похоже на преобразование в нижний регистр, но выполняется более агрессивно, поскольку предназначено для удаления всех различий по регистру в строке. Например, немецкая строчная буква 'ß' эквивалентна "ss". Поскольку она уже в нижнем регистре, lower() не изменит 'ß'; casefold() преобразует её в "ss". Например:

>>> 'straße'.lower()
'straße'
>>> 'straße'.casefold()
'strasse'

Алгоритм приведения к регистру описан в разделе 3.13.3 «Приведение к регистру по умолчанию» стандарта Unicode.

Добавлено в версии 3.3.

str.center(width, fillchar=' ', /)¶

Возвращает строку, выровненную по центру в строке длины width. Заполнение выполняется с помощью указанного fillchar (по умолчанию – пробел ASCII). Исходная строка возвращается, если width меньше или равно len(s). Например:

>>> 'Python'.center(10)
'  Python  '
>>> 'Python'.center(10, '-')
'--Python--'
>>> 'Python'.center(4)
'Python'

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

Возвращает количество неперекрывающихся вхождений подстроки sub в диапазоне [start, end]. Необязательные аргументы start и end интерпретируются как в записи среза.

Если sub пуста, возвращается количество пустых строк между символами, равное длине строки плюс один. Например:

>>> 'spam, spam, spam'.count('spam')
3
>>> 'spam, spam, spam'.count('spam', 5)
2
>>> 'spam, spam, spam'.count('spam', 5, 10)
1
>>> 'spam, spam, spam'.count('eggs')
0
>>> 'spam, spam, spam'.count('')
17

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

Возвращает строку, закодированную в bytes.

Параметр encoding по умолчанию равен 'utf-8'; возможные значения см. в Стандартные кодировки.

Параметр errors управляет обработкой ошибок кодирования. Если указано 'strict' (по умолчанию), возбуждается исключение UnicodeError. Другие возможные значения: 'ignore', 'replace', 'xmlcharrefreplace', 'backslashreplace', а также любые другие имена, зарегистрированные через codecs.register_error(). Подробнее см. Обработчики ошибок.

По соображениям производительности значение errors не проверяется на корректность, пока ошибка кодирования не произойдет на самом деле, не будет включён Режим разработки Python или не будет использоваться отладочная сборка. Например:

>>> encoded_str_to_bytes = 'Python'.encode()
>>> type(encoded_str_to_bytes)
<class 'bytes'>
>>> encoded_str_to_bytes
b'Python'

Изменено в версии 3.1: Добавлена поддержка именованных аргументов.

Изменено в версии 3.9: Значение аргумента errors теперь проверяется в Режиме разработки Python и в отладочном режиме.

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

Возвращает True, если строка заканчивается указанным suffix, иначе возвращает False. suffix также может быть кортежем искомых суффиксов. С необязательным start проверка начинается с этой позиции. С необязательным end сравнение прекращается на этой позиции. Использование start и end эквивалентно str[start:end].endswith(suffix). Например:

>>> 'Python'.endswith('on')
True
>>> 'a tuple of suffixes'.endswith(('at', 'in'))
False
>>> 'a tuple of suffixes'.endswith(('at', 'es'))
True
>>> 'Python is amazing'.endswith('is', 0, 9)
True

Смотрите также startswith() и removesuffix().

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'
>>> print('01\t012\n0123\t01234'.expandtabs(4))
01  012
0123    01234

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

Возвращает наименьший индекс в строке, где подстрока sub найдена в срезе s[start:end]. Необязательные аргументы start и end интерпретируются как в записи среза. Возвращает -1, если sub не найдена. Например:

>>> 'spam, spam, spam'.find('sp')
0
>>> 'spam, spam, spam'.find('sp', 5)
6

Смотрите также rfind() и index().

Примечание

Метод 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'
>>> "The sum of {a} + {b} is {answer}".format(answer=1+2, a=1, b=2)
'The sum of 1 + 2 is 3'
>>> "{1} expects the {0} Inquisition!".format("Spanish", "Nobody")
'Nobody expects the Spanish Inquisition!'

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

Примечание

При форматировании числа (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'

Добавлено в версии 3.2.

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

Как find(), но возбуждает ValueError, если подстрока не найдена. Например:

>>> 'spam, spam, spam'.index('spam')
0
>>> 'spam, spam, spam'.index('eggs')
Traceback (most recent call last):
  File "<python-input-0>", line 1, in <module>
    'spam, spam, spam'.index('eggs')
    ~~~~~~~~~~~~~~~~~~~~~~~~^^^^^^^^
ValueError: substring not found

См. также rindex().

str.isalnum()¶

Возвращает True, если все символы в строке являются буквенно-цифровыми и есть хотя бы один символ, иначе False. Символ c является буквенно-цифровым, если одна из следующих функций возвращает True: c.isalpha(), c.isdecimal(), c.isdigit() или c.isnumeric(). Например:

>>> 'abc123'.isalnum()
True
>>> 'abc123!@#'.isalnum()
False
>>> ''.isalnum()
False
>>> ' '.isalnum()
False

str.isalpha()¶

Возвращает True, если все символы в строке являются буквенными и есть хотя бы один символ, иначе False. Буквенными считаются символы, определенные в базе данных символов Unicode как «Letter», т.е. те, у которых общая категория является одной из «Lm», «Lt», «Lu», «Ll» или «Lo». Обратите внимание, что это отличается от свойства Alphabetic, определенного в разделе 4.10 «Letters, Alphabetic, and Ideographic» стандарта Unicode. Например:

>>> 'Letters and spaces'.isalpha()
False
>>> 'LettersOnly'.isalpha()
True
>>> 'µ'.isalpha()  # не-ASCII символы также могут считаться буквенными
True

Смотрите Свойства Unicode.

str.isascii()¶

Возвращает True, если строка пуста или все символы в строке являются ASCII, иначе False. Символы ASCII имеют кодовые точки в диапазоне U+0000-U+007F. Например:

>>> 'ASCII characters'.isascii()
True
>>> 'µ'.isascii()
False

Добавлено в версии 3.7.

str.isdecimal()¶

Возвращает True, если все символы в строке являются десятичными цифрами и есть хотя бы один символ, иначе False. Десятичные цифры – это символы, которые можно использовать для построения чисел с основанием 10, например U+0660, ARABIC-INDIC DIGIT ZERO. Формально десятичный символ – это символ общей категории Unicode «Nd». Например:

>>> '0123456789'.isdecimal()
True
>>> '٠١٢٣٤٥٦٧٨٩'.isdecimal()  # арабско-индийские цифры от нуля до девяти
True
>>> 'alphabetic'.isdecimal()
False

str.isdigit()¶

Возвращает True, если все символы в строке являются цифрами и есть хотя бы один символ, иначе False. Цифры включают десятичные цифры и цифры, требующие специальной обработки, такие как совместимые надстрочные цифры. Это охватывает цифры, которые нельзя использовать для построения чисел с основанием 10, например числа кхарошти. Формально цифра – это символ со значением свойства Numeric_Type=Digit или Numeric_Type=Decimal.

str.isidentifier()¶

Возвращает True, если строка является допустимым идентификатором согласно определению языка, раздел Имена (идентификаторы и ключевые слова).

keyword.iskeyword() можно использовать для проверки, является ли строка s зарезервированным идентификатором, таким как def и 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, VULGAR FRACTION ONE FIFTH. Формально числовыми являются символы со значением свойства Numeric_Type=Digit, Numeric_Type=Decimal или Numeric_Type=Numeric. Например:

>>> '0123456789'.isnumeric()
True
>>> '٠١٢٣٤٥٦٧٨٩'.isnumeric()  # арабско-индийские цифры от нуля до девяти
True
>>> '⅕'.isnumeric()  # Обыкновенная дробь одна пятая
True
>>> '²'.isdecimal(), '²'.isdigit(),  '²'.isnumeric()
(False, True, True)

Смотрите также isdecimal() и isdigit(). Числовые символы являются надмножеством десятичных цифр.

str.isprintable()¶

Возвращает True, если все символы в строке являются печатными, False, если она содержит хотя бы один непечатный символ.

Здесь «печатный» означает, что символ подходит для использования repr() в своем выводе; «непечатный» означает, что repr() для встроенных типов будет экранировать символ шестнадцатеричным кодом. Это не влияет на обработку строк, записываемых в sys.stdout или sys.stderr.

Печатные символы – это те, которые в базе данных символов Unicode (см. unicodedata) имеют общую категорию из группы Letter, Mark, Number, Punctuation или Symbol (L, M, N, P или S); плюс пробел ASCII 0x20. Непечатные символы – это те, которые находятся в группе Separator или Other (Z или C), за исключением пробела ASCII.

Например:

>>> ''.isprintable(), ' '.isprintable()
(True, True)
>>> '\t'.isprintable(), '\n'.isprintable()
(False, False)

См. также isspace().

str.isspace()¶

Возвращает True, если в строке есть только пробельные символы и есть хотя бы один символ, иначе False.

Например:

>>> ''.isspace()
False
>>> ' '.isspace()
True
>>> '\t\n'.isspace() # Табуляция и разрыв строки
True
>>> '\u3000'.isspace() # Идеографический пробел
True

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

См. также isprintable().

str.istitle()¶

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

Например:

>>> 'Spam, Spam, Spam'.istitle()
True
>>> 'spam, spam, spam'.istitle()
False
>>> 'SPAM, SPAM, SPAM'.istitle()
False

См. также title().

str.isupper()¶

Возвращает True, если все символы с регистром [4] в строке являются заглавными и есть хотя бы один символ с регистром; в противном случае False.

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

str.join(iterable, /)¶

Возвращает строку, которая является конкатенацией строк в iterable. Если в iterable есть какие-либо нестроковые значения, включая объекты bytes, будет возбуждено TypeError. Разделителем между элементами служит строка, предоставляющая этот метод. Например:

>>> ', '.join(['spam', 'spam', 'spam'])
'spam, spam, spam'
>>> '-'.join('Python')
'P-y-t-h-o-n'

См. также split().

str.ljust(width, fillchar=' ', /)¶

Возвращает строку, выровненную по левому краю в строке длины width. Заполнение выполняется с использованием указанного fillchar (по умолчанию пробел ASCII). Исходная строка возвращается, если width меньше или равно len(s).

Например:

>>> 'Python'.ljust(10)
'Python    '
>>> 'Python'.ljust(10, '.')
'Python....'
>>> 'Monty Python'.ljust(10, '.')
'Monty Python'

См. также rjust().

str.lower()¶

Возвращает копию строки, в которой все символы с регистром [4] преобразованы в строчные. Например:

>>> 'Lower Method Example'.lower()
'lower method example'

Используемый алгоритм приведения к нижнему регистру описан в разделе 3.13.2 ‘Default Case Conversion’ стандарта Unicode.

str.lstrip(chars=None, /)¶

Возвращает копию строки с удаленными начальными символами. Аргумент 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(dict, /)¶

static str.maketrans(from, to, remove='', /)

Этот статический метод возвращает таблицу перевода, пригодную для использования в str.translate().

Если передан только один аргумент, он должен быть словарём, отображающим кодовые точки Unicode (целые числа) или символы (строки длины 1) в кодовые точки Unicode, строки (произвольной длины) или None. Ключи-символы при этом будут преобразованы в кодовые точки.

Если передано два аргумента, они должны быть строками одинаковой длины; в результирующем словаре каждый символ из from будет отображаться на символ на той же позиции в to. Если есть третий аргумент, он должен быть строкой, символы которой будут отображаться на None в результате.

Изменено в версии 3.15: dict теперь может быть frozendict.

str.partition(sep, /)¶

Разделяет строку по первому вхождению sep и возвращает кортеж из трёх элементов, содержащий часть до разделителя, сам разделитель и часть после разделителя. Если разделитель не найден, возвращает кортеж из трёх элементов, содержащий саму строку, а затем две пустые строки.

Например:

>>> 'Monty Python'.partition(' ')
('Monty', ' ', 'Python')
>>> "Monty Python's Flying Circus".partition(' ')
('Monty', ' ', "Python's Flying Circus")
>>> 'Monty Python'.partition('-')
('Monty Python', '', '')

См. также rpartition().

str.removeprefix(prefix, /)¶

Если строка начинается с prefix, возвращает string[len(prefix):]. В противном случае возвращает копию исходной строки:

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

Добавлено в версии 3.9.

Смотрите также removesuffix() и startswith().

str.removesuffix(suffix, /)¶

Если строка заканчивается строкой suffix и этот suffix не пуст, возвращает string[:-len(suffix)]. В противном случае возвращает копию исходной строки:

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

Добавлено в версии 3.9.

Смотрите также removeprefix() и endswith().

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

Возвращает копию строки, в которой все вхождения подстроки old заменены на new. Если указан count, заменяются только первые count вхождений. Если count не указан или равен -1, заменяются все вхождения. Например:

>>> 'spam, spam, spam'.replace('spam', 'eggs')
'eggs, eggs, eggs'
>>> 'spam, spam, spam'.replace('spam', 'eggs', 1)
'eggs, spam, spam'

Изменено в версии 3.13: count теперь поддерживается как именованный аргумент.

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

Возвращает наибольший индекс в строке, на котором найдена подстрока sub, так что sub содержится в s[start:end]. Необязательные аргументы start и end интерпретируются как в записи среза. Возвращает -1 в случае неудачи. Например:

>>> 'spam, spam, spam'.rfind('sp')
12
>>> 'spam, spam, spam'.rfind('sp', 0, 10)
6

Смотрите также find() и rindex().

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

Как rfind(), но возбуждает ValueError, когда подстрока sub не найдена. Например:

>>> 'spam, spam, spam'.rindex('spam')
12
>>> 'spam, spam, spam'.rindex('eggs')
Traceback (most recent call last):
  File "<stdin-0>", line 1, in <module>
    'spam, spam, spam'.rindex('eggs')
    ~~~~~~~~~~~~~~~~~~~~~~~~~^^^^^^^^
ValueError: substring not found

Смотрите также index() и find().

str.rjust(width, fillchar=' ', /)¶

Возвращает строку, выровненную по правому краю в строке длины width. Заполнение выполняется с использованием указанного fillchar (по умолчанию пробел ASCII). Исходная строка возвращается, если width меньше или равно len(s).

Например:

>>> 'Python'.rjust(10)
'    Python'
>>> 'Python'.rjust(10, '.')
'....Python'
>>> 'Monty Python'.rjust(10, '.')
'Monty Python'

Смотрите также ljust() и zfill().

str.rpartition(sep, /)¶

Разделяет строку по последнему вхождению sep и возвращает кортеж из трёх элементов, содержащий часть до разделителя, сам разделитель и часть после разделителя. Если разделитель не найден, возвращает кортеж из трёх элементов, содержащий две пустые строки, за которыми следует сама строка.

Например:

>>> 'Monty Python'.rpartition(' ')
('Monty', ' ', 'Python')
>>> "Monty Python's Flying Circus".rpartition(' ')
("Monty Python's Flying", ' ', 'Circus')
>>> 'Monty Python'.rpartition('-')
('', '', 'Monty Python')

См. также partition().

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

Возвращает список слов в строке, используя sep в качестве строки-разделителя. Если указан maxsplit, выполняется не более maxsplit разбиений, причём самые правые. Если sep не указан или равен None, в качестве разделителя используется любая строка из пробельных символов. За исключением разбиения справа, rsplit() ведёт себя как split(), который подробно описан ниже.

str.rstrip(chars=None, /)¶

Возвращает копию строки с удалёнными завершающими символами. Аргумент chars – это строка, задающая набор удаляемых символов. Если он опущен или равен None, аргумент chars по умолчанию удаляет пробельные символы. Аргумент chars не является суффиксом; удаляются все комбинации его значений. Например:

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

См. removesuffix() для метода, который удаляет одну строку-суффикс, а не все символы из набора. Например:

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

См. также strip().

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

Возвращает список слов в строке, используя sep в качестве строки-разделителя. Если указан maxsplit, выполняется не более maxsplit разбиений (таким образом, список будет содержать не более maxsplit+1 элементов). Если maxsplit не указан или равен -1, то количество разбиений не ограничено (выполняются все возможные разбиения).

Если указан sep, последовательные разделители не группируются вместе и считаются разделяющими пустые строки (например, '1,,2'.split(',') возвращает ['1', '', '2']). Аргумент sep может состоять из нескольких символов как единый разделитель (чтобы разбить по нескольким разделителям, используйте re.split()). Разбиение пустой строки с указанным разделителем возвращает [''].

Например:

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

Если sep не указан или равен None и maxsplit равен 0, учитываются только начальные последовательности пробельных символов.

Например:

>>> "".split(None, 0)
[]
>>> "   ".split(None, 0)
[]
>>> "   foo   ".split(maxsplit=0)
['foo   ']

См. также join().

str.splitlines(keepends=False)¶

Возвращает список строк в строке, разбивая по границам строк. Символы конца строки не включаются в результирующий список, если только keepends не задан и не равен true.

Этот метод разбивает по следующим границам строк. В частности, эти границы являются надмножеством универсальных символов новой строки.

Представление	Описание
\n	Перевод строки
\r	Возврат каретки
\r\n	Возврат каретки + перевод строки
\v or \x0b	Табуляция строк
\f or \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. Префикс также может быть кортежем префиксов для поиска. С необязательным start проверка строки начинается с указанной позиции. С необязательным end сравнение строки прекращается на указанной позиции.

Например:

>>> 'Python'.startswith('Py')
True
>>> 'a tuple of prefixes'.startswith(('at', 'a'))
True
>>> 'Python is amazing'.startswith('is', 7)
True

Смотрите также endswith() и removeprefix().

str.strip(chars=None, /)¶

Возвращает копию строки, из которой удалены начальные и конечные символы. Аргумент 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'

См. также rstrip().

str.swapcase()¶

Возвращает копию строки, в которой все заглавные символы преобразованы в строчные и наоборот. Например:

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

Обратите внимание, что s.swapcase().swapcase() == s не обязательно верно. Например:

>>> 'straße'.swapcase().swapcase()
'strasse'

Смотрите также str.lower() и str.upper().

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

См. также istitle().

str.translate(table, /)¶

Возвращает копию строки, в которой каждый символ преобразован через заданную таблицу перевода. Таблица должна быть объектом, поддерживающим индексацию через __getitem__(), обычно это отображение (mapping) или последовательность (sequence). При индексации по порядковому номеру Unicode (целое число) объект таблицы может делать следующее: возвращать порядковый номер Unicode или строку, чтобы сопоставить символ с одним или несколькими другими символами; возвращать None, чтобы удалить символ из результирующей строки; или возбуждать исключение LookupError, чтобы оставить символ без изменений.

Для создания таблицы перевода из сопоставлений символов в различных форматах можно использовать str.maketrans().

В следующем примере используется отображение для замены 'a' на 'X', 'b' на 'Y' и удаления 'c':

>>> 'abc123'.translate({ord('a'): 'X', ord('b'): 'Y', ord('c'): None})
'XY123'

Смотрите также модуль codecs для более гибкого подхода к настраиваемым сопоставлениям символов.

str.upper()¶

Возвращает копию строки, в которой все буквенные символы [4] преобразованы в верхний регистр. Обратите внимание, что s.upper().isupper() может быть False, если s содержит символы без регистра или если категория Unicode результирующего символа (символов) не «Lu» (Letter, uppercase), а, например, «Lt» (Letter, titlecase).

Используемый алгоритм приведения к верхнему регистру описан в разделе 3.13.2 «Default Case Conversion» стандарта Unicode.

str.zfill(width, /)¶

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

Например:

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

См. также rjust().

Formatted String Literalsf-strings) (Литералы форматированных строк (f-строки)

Добавлено в версии 3.6.

Изменено в версии 3.7: В выражениях внутри f-строк можно использовать символы await и async for.

Изменено в версии 3.8: Добавлен спецификатор отладки (=)

Изменено в версии 3.12: Многие ограничения на выражения внутри f-строк были сняты. В частности, теперь разрешены вложенные строки, комментарии и обратные слеши.

f-строка (формально – литерал форматированной строки) – это строковый литерал с префиксом f или F. Такой литерал позволяет встраивать результаты произвольных выражений Python в поля подстановки, которые ограничены фигурными скобками ({}). Каждое поле подстановки должно содержать выражение, за которым может следовать:

• спецификатор отладки – знак равенства (=);

• спецификатор преобразования – !s, !r или !a; и/или

• спецификатор формата с префиксом в виде двоеточия (:).

См. раздел «Лексический анализ» об f-строках для подробностей о синтаксисе этих полей.

Debug specifierСпецификатор отладки

Добавлено в версии 3.8.

Если спецификатор отладки – знак равенства (=) – появляется после выражения поля подстановки, результирующая f-строка будет содержать исходный код выражения, знак равенства и значение выражения. Это часто удобно для отладки:

>>> number = 14.3
>>> f'{number=}'
'number=14.3'

Пробелы до, внутри и после выражения, а также пробелы после знака равенства, значимы – они сохраняются в результате:

>>> f'{ number  -  4  = }'
' number  -  4  = 10.3'

Conversion specifierСпецификатор преобразования

По умолчанию значение выражения поля подстановки преобразуется в строку с помощью str():

>>> from fractions import Fraction
>>> one_third = Fraction(1, 3)
>>> f'{one_third}'
'1/3'

Когда используется спецификатор отладки, но не указан спецификатор формата, преобразование по умолчанию вместо этого использует repr():

>>> f'{one_third = }'
'one_third = Fraction(1, 3)'

Преобразование можно указать явно с помощью одного из этих спецификаторов:

• !s для str()

• !r для repr()

• !a для ascii()

Например:

>>> str(one_third)
'1/3'
>>> repr(one_third)
'Fraction(1, 3)'

>>> f'{one_third!s} is {one_third!r}'
'1/3 is Fraction(1, 3)'

>>> string = "¡kočka 😸!"
>>> ascii(string)
"'\\xa1ko\\u010dka \\U0001f638!'"

>>> f'{string = !a}'
"string = '\\xa1ko\\u010dka \\U0001f638!'"

Format specifierСпецификатор формата

После того как выражение вычислено и, возможно, преобразовано с помощью явного спецификатора преобразования, оно форматируется с помощью функции format(). Если поле подстановки содержит спецификатор формата, введённый двоеточием (:), спецификатор передаётся в format() в качестве второго аргумента. Затем результат format() используется как окончательное значение для поля подстановки. Например:

>>> from fractions import Fraction
>>> one_third = Fraction(1, 3)
>>> f'{one_third:.6f}'
'0.333333'
>>> f'{one_third:_^+10}'
'___+1/3___'
>>> >>> f'{one_third!r:_^20}'
'___Fraction(1, 3)___'
>>> f'{one_third = :~>10}~'
'one_third = ~~~~~~~1/3~'

Template String Literalst-strings) (Шаблонные строковые литералы (t-строки)

T-строка (формально шаблонный строковый литерал) – это строковый литерал с префиксом t или T.

Эти строки следуют тем же правилам синтаксиса и вычисления, что и форматированные строковые литералы, со следующими отличиями:

• Вместо вычисления в объект str, шаблонные строковые литералы вычисляются в объект string.templatelib.Template.

• Протокол format() не используется. Вместо этого спецификатор формата и преобразования (если есть) передаются новому объекту Interpolation, который создаётся для каждого вычисленного выражения. Код, обрабатывающий результирующий объект Template, решает, как обрабатывать спецификаторы формата и преобразования.

• Спецификаторы формата, содержащие вложенные поля подстановки, вычисляются жадно, до передачи объекту Interpolation. Например, интерполяция вида {amount:.{precision}f} вычислит внутреннее выражение {precision}, чтобы определить значение атрибута format_spec. Если бы precision было 2, результирующий спецификатор формата был бы '.2f'.

• Когда в выражении интерполяции указан знак равенства '=', текст выражения добавляется к строковому литералу, который предшествует соответствующей интерполяции. Это включает знак равенства и любые окружающие пробелы. Экземпляр Interpolation для выражения будет создан как обычно, за исключением того, что conversion будет установлено в 'r' (repr()) по умолчанию. Если указаны явное преобразование или спецификатор формата, это переопределит поведение по умолчанию.

Форматирование строк в стиле printf

Примечание

Описанные здесь операции форматирования имеют множество особенностей, которые приводят к ряду распространённых ошибок (например, к некорректному отображению кортежей и словарей).

Использование форматированных строковых литералов, интерфейса str.format() или string.Template может помочь избежать этих ошибок. Каждая из этих альтернатив имеет свои компромиссы и преимущества с точки зрения простоты, гибкости и/или расширяемости.

У строковых объектов есть одна уникальная встроенная операция: оператор % (модуло). Он также известен как оператор форматирования или интерполяции строк. При задании format % values (где format – строка), спецификации преобразования % в format заменяются нулём или более элементами из values. Эффект аналогичен использованию функции sprintf() в языке C. Например:

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

Если format требует один аргумент, values может быть одним объектом, не являющимся кортежем. [5] В противном случае values должен быть кортежем с точным количеством элементов, указанным в форматной строке, или одним отображающим объектом (например, словарём).

Спецификатор преобразования содержит два или более символов и имеет следующие компоненты, которые должны располагаться в таком порядке:

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

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

3. Флаги преобразования (необязательно), которые влияют на результат некоторых типов преобразования.

4. Минимальная ширина поля (необязательно). Если указана как '*' (звёздочка), фактическая ширина читается из следующего элемента кортежа в values, а преобразуемый объект идёт после минимальной ширины поля и необязательной точности.

5. Точность (необязательно), задаётся как '.' (точка), за которой следует точность. Если указана как '*' (звёздочка), фактическая точность читается из следующего элемента кортежа в values, а преобразуемое значение идёт после точности.

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'	Знаковое целое десятичное.
'i'	Знаковое целое десятичное.
'o'	Знаковое восьмеричное значение.	(1)
'u'	Устаревший тип – идентичен 'd'.	(6)
'x'	Знаковое шестнадцатеричное (нижний регистр).	(2)
'X'	Знаковое шестнадцатеричное (верхний регистр).	(2)
'e'	Экспоненциальный формат с плавающей точкой (нижний регистр).	(3)
'E'	Экспоненциальный формат с плавающей точкой (верхний регистр).	(3)
'f'	Десятичный формат с плавающей точкой.	(3)
'F'	Десятичный формат с плавающей точкой.	(3)
'g'	Формат с плавающей точкой. Использует экспоненциальный формат в нижнем регистре, если показатель степени меньше -4 или не меньше точности, в противном случае десятичный формат.	(4)
'G'	Формат с плавающей точкой. Использует экспоненциальный формат в верхнем регистре, если показатель степени меньше -4 или не меньше точности, в противном случае десятичный формат.	(4)
'c'	Одиночный символ (принимает целое число или строку из одного символа).
'r'	Строка (преобразует любой объект Python с помощью repr()).	(5)
's'	Строка (преобразует любой объект Python с помощью str()).	(5)
'a'	Строка (преобразует любой объект Python с помощью ascii()).	(5)
'%'	Никакой аргумент не преобразуется, в результате появляется символ '%'.

Для форматов с плавающей точкой результат должен быть корректно округлён до заданной точности p цифр после десятичной точки. Режим округления соответствует таковому у встроенной функции round().

Примечания:

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 ObjectsОбъекты bytes

Объекты bytes – это неизменяемые последовательности отдельных байтов. Поскольку многие основные двоичные протоколы основаны на текстовой кодировке ASCII, объекты bytes предоставляют несколько методов, которые действительны только при работе с данными, совместимыми с ASCII, и тесно связаны со строковыми объектами и другими способами.

class bytes(source=b'')¶

class bytes(source, encoding, errors='strict')

Во-первых, синтаксис литералов bytes в основном такой же, как для строковых литералов, за исключением того, что добавляется префикс b:

• Одинарные кавычки: b'still allows embedded "double" quotes'

• Двойные кавычки: b"still allows embedded 'single' quotes"

• Тройные кавычки: b'''3 single quotes''', b"""3 double quotes"""

В литералах bytes допускаются только символы ASCII (независимо от объявленной кодировки исходного кода). Любые двоичные значения больше 127 должны вводиться в литералы bytes с помощью соответствующей управляющей последовательности.

Как и строковые литералы, литералы bytes также могут использовать префикс r для отключения обработки управляющих последовательностей. См. Строковые литералы и литералы bytes для получения дополнительной информации о различных формах литералов bytes, включая поддерживаемые управляющие последовательности.

Хотя литералы bytes и их представления основаны на тексте ASCII, объекты bytes на самом деле ведут себя как неизменяемые последовательности целых чисел, причем каждое значение в последовательности ограничено так, что 0 <= x < 256 (попытки нарушить это ограничение вызовут исключение ValueError). Это сделано намеренно, чтобы подчеркнуть, что хотя многие двоичные форматы содержат элементы на основе ASCII и могут быть полезно обработаны некоторыми текстовыми алгоритмами, в общем случае это не так для произвольных двоичных данных (слепое применение алгоритмов обработки текста к двоичным форматам данных, несовместимым с ASCII, обычно приводит к повреждению данных).

В дополнение к литеральным формам, объекты bytes могут быть созданы несколькими другими способами:

• Объект 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 в строке, а не только пробелы.

Изменено в версии 3.14: bytes.fromhex() теперь принимает ASCII bytes и байтоподобные объекты в качестве входных данных.

Существует обратная функция преобразования для превращения объекта bytes в его шестнадцатеричное представление.

hex(*, bytes_per_sep=1)¶

hex(sep, bytes_per_sep=1)

Возвращает строковый объект, содержащий по две шестнадцатеричные цифры для каждого байта в экземпляре.

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

Если вы хотите сделать шестнадцатеричную строку более читаемой, вы можете указать параметр-разделитель из одного символа sep для включения в вывод. По умолчанию этот разделитель будет вставляться между каждым байтом. Второй необязательный параметр bytes_per_sep управляет интервалом. Положительные значения вычисляют позицию разделителя справа, отрицательные – слева.

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

Добавлено в версии 3.5.

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

Поскольку объекты bytes являются последовательностями целых чисел (аналогично кортежу), для объекта bytes b, b[0] будет целым числом, а b[0:1] – объектом bytes длины 1. (Это отличается от текстовых строк, где и индексирование, и срез дают строку длины 1.)

Представление объектов bytes использует литеральный формат (b'...'), поскольку он часто полезнее, чем, например, bytes([46, 46, 46]). Вы всегда можете преобразовать объект bytes в список целых чисел с помощью list(b).

Bytearray ObjectsОбъекты bytearray

Объекты bytearray являются изменяемым аналогом объектов bytes.

class bytearray(source=b'')¶

class bytearray(source, encoding, errors='strict')

Для объектов bytearray не существует специального литерального синтаксиса; вместо этого они всегда создаются вызовом конструктора:

• Создание пустого экземпляра: bytearray()

• Создание экземпляра, заполненного нулями, заданной длины: bytearray(10)

• Из итерируемого объекта целых чисел: bytearray(range(20))

• Копирование существующих двоичных данных через протокол буфера: bytearray(b'Hi!')

Поскольку объекты bytearray изменяемы, они поддерживают операции с изменяемыми последовательностями в дополнение к общим операциям с bytes и bytearray, описанным в Операции с bytes и bytearray.

Также см. встроенную функцию bytearray.

Поскольку 2 шестнадцатеричные цифры соответствуют ровно одному байту, шестнадцатеричные числа являются часто используемым форматом для описания двоичных данных. Соответственно, тип bytearray имеет дополнительный метод класса для чтения данных в этом формате:

classmethod fromhex(string, /)¶

Этот метод класса bytearray возвращает объект bytearray, декодируя заданный строковый объект. Строка должна содержать по две шестнадцатеричные цифры на байт, при этом пробельные символы ASCII игнорируются.

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

Изменено в версии 3.7: bytearray.fromhex() теперь пропускает все пробельные символы ASCII в строке, а не только пробелы.

Изменено в версии 3.14: bytearray.fromhex() теперь принимает ASCII bytes и байтоподобные объекты в качестве входных данных.

Существует обратная функция преобразования для превращения объекта bytearray в его шестнадцатеричное представление.

hex(*, bytes_per_sep=1)¶

hex(sep, bytes_per_sep=1)

Возвращает строковый объект, содержащий по две шестнадцатеричные цифры для каждого байта в экземпляре.

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

Добавлено в версии 3.5.

Изменено в версии 3.8: Аналогично bytes.hex(), bytearray.hex() теперь поддерживает необязательные параметры sep и bytes_per_sep для вставки разделителей между байтами в шестнадцатеричном выводе.

resize(size, /)¶

Изменяет размер bytearray, чтобы он содержал size байт. size должен быть больше или равен 0.

Если bytearray нужно уменьшить, байты за пределами size усекаются.

Если bytearray нужно увеличить, все новые байты за пределами size будут установлены в нулевые байты.

Это эквивалентно:

>>> def resize(ba, size):
...     if len(ba) > size:
...         del ba[size:]
...     else:
...         ba += b'\0' * (size - len(ba))

Примеры:

>>> shrink = bytearray(b'abc')
>>> shrink.resize(1)
>>> (shrink, len(shrink))
(bytearray(b'a'), 1)
>>> grow = bytearray(b'abc')
>>> grow.resize(5)
>>> (grow, len(grow))
(bytearray(b'abc\x00\x00'), 5)

Добавлено в версии 3.14.

take_bytes(n=None, /)¶

Удаляет первые n байт из bytearray и возвращает их как неизменяемый bytes. По умолчанию (если n равен None) возвращает все байты и очищает bytearray.

Если n отрицательно, индексировать с конца и взять первые len() плюс n байт. Если n выходит за границы, возбуждает IndexError.

Если взять меньше полной длины, в bytearray останутся байты, что требует копирования. Если оставшиеся байты нужно отбросить, используйте resize() или del для усечения, затем take_bytes() без указания размера.

Особенность реализации CPython: Взятие всех байт – это операция без копирования.

Добавлено в версии 3.15: См. запись What’s New о распространённых шаблонах кода, которые можно оптимизировать с помощью bytearray.take_bytes().

Поскольку объекты bytearray являются последовательностями целых чисел (аналогично списку), для объекта bytearray b, b[0] будет целым числом, в то время как b[0:1] будет объектом bytearray длины 1. (Это отличается от текстовых строк, где и индексация, и срез дают строку длины 1).

Представление объектов bytearray использует литеральный формат bytes (bytearray(b'...')), поскольку он часто более удобен, чем, например, bytearray([46, 46, 46]). Вы всегда можете преобразовать объект bytearray в список целых чисел с помощью list(b).

Смотрите также

Подробную информацию о гарантиях потокобезопасности для объектов bytearray см. в Потокобезопасность объектов bytearray.

Bytes and Bytearray OperationsОперации с bytes и bytearray

Объекты bytes и bytearray поддерживают общие операции над последовательностями. Они взаимодействуют не только с операндами того же типа, но и с любым байтоподобным объектом. Благодаря этой гибкости их можно свободно смешивать в операциях без возникновения ошибок. Однако тип возвращаемого результата может зависеть от порядка операндов.

Примечание

Методы объектов bytes и bytearray не принимают строки в качестве аргументов, как и методы строк не принимают bytes в качестве аргументов. Например, необходимо писать:

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

и:

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

Некоторые операции с bytes и bytearray предполагают использование двоичных форматов, совместимых с ASCII, и поэтому их следует избегать при работе с произвольными двоичными данными. Эти ограничения описаны ниже.

Примечание

Использование этих операций на основе ASCII для управления двоичными данными, которые не хранятся в формате на основе ASCII, может привести к повреждению данных.

Следующие методы объектов bytes и bytearray можно использовать с произвольными двоичными данными.

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

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

Возвращает количество неперекрывающихся вхождений подпоследовательности sub в диапазоне [start, end]. Необязательные аргументы start и end интерпретируются как в нотации срезов.

Искомая подпоследовательность может быть любым байтоподобным объектом или целым числом в диапазоне от 0 до 255.

Если sub пусто, возвращает количество пустых срезов между символами, которое равно длине объекта bytes плюс один.

Изменено в версии 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'

prefix может быть любым байтоподобным объектом.

Примечание

Версия этого метода для bytearray не изменяет объект на месте - он всегда создаёт новый объект, даже если никаких изменений не было внесено.

Добавлено в версии 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'

Суффикс может быть любым байтоподобным объектом.

Примечание

Версия этого метода для bytearray не работает на месте – она всегда создает новый объект, даже если изменения не были внесены.

Добавлено в версии 3.9.

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

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

Возвращает байты, декодированные в str.

encoding по умолчанию равен 'utf-8'; возможные значения см. в Стандартные кодировки.

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 Error Handlers for details.

Из соображений производительности значение errors не проверяется на корректность, пока не произойдет ошибка декодирования, не будет включен Режим разработки Python или не будет использована отладочная сборка.

Примечание

Передача аргумента encoding в str позволяет декодировать любой байтоподобный объект напрямую, без необходимости создавать временный объект bytes или bytearray.

Изменено в версии 3.1: Добавлена поддержка именованных аргументов.

Изменено в версии 3.9: Значение аргумента errors теперь проверяется в Режиме разработки Python и в режиме отладки.

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

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

Возвращает True, если двоичные данные заканчиваются указанным суффиксом, иначе возвращает False. suffix также может быть кортежем суффиксов для поиска. С необязательным start проверка начинается с этой позиции. С необязательным end сравнение заканчивается на этой позиции.

Искомый суффикс (или суффиксы) может быть любым байтоподобным объектом.

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

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

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

Искомая подпоследовательность может быть любым байтоподобным объектом или целым числом в диапазоне от 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, когда подпоследовательность не найдена.

Искомая подпоследовательность может быть любым байтоподобным объектом или целым числом в диапазоне от 0 до 255.

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

bytes.join(iterable, /)¶

bytearray.join(iterable, /)¶

Возвращает объект bytes или bytearray, являющийся конкатенацией последовательностей двоичных данных из iterable. Исключение TypeError будет возбуждено, если в iterable есть значения, не являющиеся байтоподобными объектами, включая объекты str. Разделителем между элементами служит содержимое объекта bytes или bytearray, предоставляющего этот метод.

static bytes.maketrans(from, to, /)¶

static bytearray.maketrans(from, to, /)¶

Этот статический метод возвращает таблицу перевода, пригодную для bytes.translate(), которая сопоставляет каждый символ в from с символом на той же позиции в to; from и to должны быть объектами, подобными bytes и иметь одинаковую длину.

Добавлено в версии 3.1.

bytes.partition(sep, /)¶

bytearray.partition(sep, /)¶

Разделяет последовательность по первому вхождению sep и возвращает кортеж из трёх элементов: часть до разделителя, сам разделитель или его копию bytearray и часть после разделителя. Если разделитель не найден, возвращает кортеж из трёх элементов, содержащий копию исходной последовательности, а затем два пустых объекта bytes или bytearray.

Разделитель для поиска может быть любым объектом, подобным bytes.

bytes.replace(old, new, /, count=-1)¶

bytearray.replace(old, new, /, count=-1)¶

Возвращает копию последовательности, в которой все вхождения подпоследовательности old заменены на new. Если задан count, заменяются только первые count вхождений. Если count не указан или -1, заменяются все вхождения.

Подпоследовательность для поиска и её замена могут быть любым объектом, подобным bytes.

Примечание

Версия этого метода для bytearray не работает на месте – она всегда создаёт новый объект, даже если изменения не вносились.

Изменено в версии 3.15: count теперь поддерживается как именованный аргумент.

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

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

Возвращает наибольший индекс в последовательности, где найдена подпоследовательность sub, такой, что sub содержится в s[start:end]. Необязательные аргументы start и end интерпретируются как в срезах. Возвращает -1 в случае неудачи.

Подпоследовательность для поиска может быть любым объектом, подобным bytes или целым числом в диапазоне от 0 до 255.

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

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

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

Как rfind(), но вызывает ValueError, когда подпоследовательность sub не найдена.

Подпоследовательность для поиска может быть любым объектом, подобным bytes или целым числом в диапазоне от 0 до 255.

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

bytes.rpartition(sep, /)¶

bytearray.rpartition(sep, /)¶

Разделяет последовательность по последнему вхождению sep и возвращает кортеж из трёх элементов: часть до разделителя, сам разделитель или его копию bytearray и часть после разделителя. Если разделитель не найден, возвращает кортеж из трёх элементов, содержащий два пустых объекта bytes или bytearray, а затем копию исходной последовательности.

Разделитель для поиска может быть любым объектом, подобным bytes.

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

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

Возвращает True, если двоичные данные начинаются с указанного prefix, иначе возвращает False. prefix также может быть кортежем префиксов для поиска. С необязательным start проверка начинается с этой позиции. С необязательным end сравнение прекращается на этой позиции.

Префикс(ы) для поиска может быть любым объектом, подобным bytes.

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=b' ', /)¶

bytearray.center(width, fillbyte=b' ', /)¶

Возвращает копию объекта, выровненную по центру в последовательности длины width. Заполнение выполняется с помощью указанного fillbyte (по умолчанию – пробел ASCII). Для объектов bytes исходная последовательность возвращается, если width меньше или равно len(s).

Примечание

Версия этого метода для bytearray не изменяет объект на месте – всегда создаётся новый объект, даже если никаких изменений не было.

bytes.ljust(width, fillbyte=b' ', /)¶

bytearray.ljust(width, fillbyte=b' ', /)¶

Возвращает копию объекта, выровненную по левому краю в последовательности длины width. Заполнение выполняется с помощью указанного fillbyte (по умолчанию – пробел ASCII). Для объектов bytes исходная последовательность возвращается, если width меньше или равно len(s).

Примечание

Версия этого метода для bytearray не изменяет объект на месте – всегда создаётся новый объект, даже если никаких изменений не было.

bytes.lstrip(bytes=None, /)¶

bytearray.lstrip(bytes=None, /)¶

Возвращает копию последовательности с удалёнными указанными начальными байтами. Аргумент bytes – это двоичная последовательность, задающая набор значений байтов, которые нужно удалить. Если он опущен или равен None, аргумент bytes по умолчанию удаляет пробельные символы ASCII. Аргумент bytes не является префиксом; удаляются все комбинации его значений:

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

Двоичная последовательность значений байтов для удаления может быть любым байтоподобным объектом. См. removeprefix() для метода, который удаляет одну строку-префикс, а не весь набор символов. Например:

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

Примечание

Версия этого метода для bytearray не изменяет объект на месте – всегда создаётся новый объект, даже если никаких изменений не было.

bytes.rjust(width, fillbyte=b' ', /)¶

bytearray.rjust(width, fillbyte=b' ', /)¶

Возвращает копию объекта, выровненную по правому краю в последовательности длины width. Заполнение выполняется с помощью указанного 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(bytes=None, /)¶

bytearray.rstrip(bytes=None, /)¶

Возвращает копию последовательности с удалёнными указанными конечными байтами. Аргумент bytes – это двоичная последовательность, задающая набор значений байтов, которые нужно удалить. Если он опущен или равен None, аргумент bytes по умолчанию удаляет пробельные символы ASCII. Аргумент bytes не является суффиксом; удаляются все комбинации его значений:

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

Двоичная последовательность значений байтов для удаления может быть любым байтоподобным объектом. См. 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, то количество разделений не ограничено (выполняются все возможные разделения).

Если указан sep, следующие друг за другом разделители не объединяются, а считаются разделителями пустых подпоследовательностей (например, b'1,,2'.split(b',') возвращает [b'1', b'', b'2']). Аргумент sep может представлять собой многобайтовую последовательность в качестве единого разделителя. Разделение пустой последовательности с указанным разделителем возвращает [b''] или [bytearray(b'')] в зависимости от типа разделяемого объекта. Аргумент sep может быть любым объектом, подобным байтам.

Например:

>>> 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(bytes=None, /)¶

bytearray.strip(bytes=None, /)¶

Возвращает копию последовательности с удалёнными указанными начальными и конечными байтами. Аргумент bytes – это двоичная последовательность, задающая набор удаляемых значений байтов. Если он опущен или равен None, аргумент bytes по умолчанию удаляет пробельные символы ASCII. Аргумент bytes является не префиксом или суффиксом, а скорее удаляются все комбинации его значений:

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

Двоичная последовательность удаляемых значений байтов может быть любым объектом, подобным байтам.

Примечание

Версия этого метода для bytearray не работает на месте – он всегда создаёт новый объект, даже если никаких изменений не было.

Следующие методы объектов bytes и bytearray предполагают использование двоичных форматов, совместимых с ASCII, и не должны применяться к произвольным двоичным данным. Обратите внимание, что все методы bytearray в этом разделе не работают на месте, а создают новые объекты.

bytes.capitalize()¶

bytearray.capitalize()¶

Возвращает копию последовательности, в которой каждый байт интерпретируется как символ ASCII, причём первый байт переводится в верхний регистр, а остальные – в нижний. Не-ASCII значения байтов передаются без изменений.

Примечание

Версия этого метода для bytearray не работает на месте – он всегда создаёт новый объект, даже если никаких изменений не было.

bytes.expandtabs(tabsize=8)¶

bytearray.expandtabs(tabsize=8)¶

Возвращает копию последовательности, в которой все символы табуляции ASCII заменяются одним или несколькими пробелами ASCII в зависимости от текущей позиции и заданного размера табуляции. Позиции табуляции находятся через каждые tabsize байтов (по умолчанию 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.

Добавлено в версии 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'.

Примечание

The bytearray version of this method does not operate in place - it always produces a new object, even if no changes were made.

bytes.splitlines(keepends=False)¶

bytearray.splitlines(keepends=False)¶

Возвращает список строк в двоичной последовательности, разбивая по границам строк ASCII. Этот метод использует подход универсальных символов новой строки для разделения строк. Разрывы строк не включаются в результирующий список, если только 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'.

В отличие от str.swapcase(), для двоичных версий всегда выполняется bin.swapcase().swapcase() == bin. Преобразования регистра симметричны в ASCII, хотя это обычно неверно для произвольных кодовых точек Unicode.

Примечание

Версия этого метода для 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' до длины width. Начальный знак (b'+'/b'-') обрабатывается так: вставка заполнения после знака, а не перед ним. Для объектов bytes возвращается исходная последовательность, если width меньше или равно len(seq).

Например:

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

Примечание

Версия этого метода для bytearray не работает на месте – она всегда создаёт новый объект, даже если никаких изменений не было сделано.

printf-стиль форматирования байтов

Примечание

Описанные здесь операции форматирования имеют ряд особенностей, которые приводят к распространённым ошибкам (например, неправильное отображение кортежей и словарей). Если выводимое значение может быть кортежем или словарём, заключите его в кортеж.

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

Если format требует один аргумент, values может быть одним объектом, не являющимся кортежем. [5] В противном случае values должен быть кортежем, содержащим ровно столько элементов, сколько указано в объекте format bytes, или одним отображающим объектом (например, словарём).

Спецификатор преобразования содержит два или более символа и имеет следующие компоненты, которые должны располагаться в указанном порядке:

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

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

3. Флаги преобразования (необязательно), которые влияют на результат некоторых типов преобразования.

4. Минимальная ширина поля (необязательно). Если задана как '*' (звёздочка), фактическая ширина берётся из следующего элемента кортежа в values, а преобразуемый объект идёт после минимальной ширины поля и необязательной точности.

5. Точность (необязательно), задаётся как '.' (точка), после которой указывается точность. Если задана как '*' (звёздочка), фактическая точность берётся из следующего элемента кортежа в values, а преобразуемое значение идёт после точности.

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'	Знаковое десятичное целое.
'i'	Знаковое десятичное целое.
'o'	Знаковое восьмеричное значение.	(1)
'u'	Устаревший тип – идентичен 'd'.	(8)
'x'	Знаковое шестнадцатеричное (строчные буквы).	(2)
'X'	Знаковое шестнадцатеричное (заглавные буквы).	(2)
'e'	Экспоненциальный формат с плавающей точкой (строчные буквы).	(3)
'E'	Экспоненциальный формат с плавающей точкой (заглавные буквы).	(3)
'f'	Десятичный формат с плавающей точкой.	(3)
'F'	Десятичный формат с плавающей точкой.	(3)
'g'	Формат с плавающей точкой. Использует экспоненциальный формат со строчными буквами, если показатель степени меньше -4 или не меньше точности, в противном случае – десятичный формат.	(4)
'G'	Формат с плавающей точкой. Использует экспоненциальный формат с заглавными буквами, если показатель степени меньше -4 или не меньше точности, в противном случае – десятичный формат.	(4)
'c'	Один байт (принимает целое число или объекты из одного байта).
'b'	Байты (любой объект, поддерживающий протокол буфера или имеющий __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 – Добавление %-форматирования для bytes и bytearray

Добавлено в версии 3.5.

Memory ViewsПредставления памяти

Объекты memoryview позволяют коду Python получать доступ к внутренним данным объекта, поддерживающего протокол буфера, без копирования.

class memoryview(object)¶

Создаёт memoryview, ссылающийся на object. object должен поддерживать протокол буфера. Встроенные объекты, поддерживающие протокол буфера, включают bytes и bytearray.

memoryview имеет понятие элемента, который является атомарной единицей памяти, обрабатываемой исходным object. Для многих простых типов, таких как bytes и bytearray, элемент – это один байт, но другие типы, такие как array.array, могут иметь элементы большего размера.

len(view) равно длине tolist(), который является вложенным представлением списка представления. Если view.ndim = 1, это равно количеству элементов в представлении.

Изменено в версии 3.12: Если view.ndim == 0, len(view) теперь вызывает исключение TypeError вместо возврата 1.

Атрибут itemsize возвращает количество байтов в одном элементе.

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, также поддерживается индексация целым числом или кортежем целых чисел, которая возвращает один элемент правильного типа. Одномерные memoryviews можно индексировать целым числом или кортежем из одного целого числа. Многомерные memoryviews можно индексировать кортежами из ровно ndim целых чисел, где ndim – это количество измерений. Нулевые memoryviews можно индексировать пустым кортежем.

Вот пример с небайтовым форматом:

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

Одномерные memoryviews хешируемых (только для чтения) типов с форматами 'B', 'b' или 'c' также являются хешируемыми. Хеш определяется как 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: Теперь можно выполнять срезы одномерных memoryviews. Одномерные memoryviews с форматами 'B', 'b' или 'c' теперь хешируемы.

Изменено в версии 3.4: memoryview теперь автоматически регистрируется с помощью collections.abc.Sequence

Изменено в версии 3.5: memoryviews теперь можно индексировать кортежем целых чисел.

Изменено в версии 3.14: memoryview теперь является обобщённым типом.

memoryview имеет несколько методов:

__eq__(exporter)¶

memoryview и экспортёр 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

Обратите внимание, что, как и для чисел с плавающей запятой, для объектов memoryview v is w не подразумевает v == w.

Изменено в версии 3.3: Предыдущие версии сравнивали сырую память, игнорируя формат элемента и логическую структуру массива.

tobytes(order='C')¶

Возвращает данные из буфера в виде байтовой строки. Это эквивалентно вызову конструктора bytes для memoryview.

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

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

Добавлено в версии 3.8: order может быть {‘C’, ‘F’, ‘A’}. Когда order равен ‘C’ или ‘F’, данные исходного массива преобразуются в порядок C или Fortran. Для сплошных представлений ‘A’ возвращает точную копию физической памяти. В частности, порядок Fortran в памяти сохраняется. Для несплошных представлений данные сначала преобразуются в C. order=None то же самое, что order=’C’.

hex(*, bytes_per_sep=1)¶

hex(sep, bytes_per_sep=1)

Возвращает строковый объект, содержащий две шестнадцатеричные цифры для каждого байта в буфере.

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

Добавлено в версии 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]

Добавлено в версии 3.8.

release()¶

Освобождает базовый буфер, предоставляемый объектом memoryview. Многие объекты предпринимают специальные действия, когда на них удерживается представление (например, bytearray временно запрещает изменение размера); поэтому вызов release() удобен для снятия этих ограничений (и освобождения любых зависших ресурсов) как можно скорее.

После вызова этого метода любая дальнейшая операция с представлением вызывает исключение ValueError (кроме самого release(), который может быть вызван несколько раз):

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

Добавлено в версии 3.2.

cast(format, /)¶

cast(format, shape, /)

Преобразует memoryview в новый формат или форму. shape по умолчанию равен [byte_length//new_itemsize], что означает, что результирующее представление будет одномерным. Возвращаемое значение – новый memoryview, но сам буфер не копируется. Поддерживаются преобразования 1D -> C-contiguous и C-contiguous -> 1D.

Целевой формат ограничен одномерным собственным форматом в синтаксисе struct. Один из форматов должен быть байтовым форматом ('B', 'b' или 'c'). Длина в байтах результата должна быть такой же, как исходная длина. Обратите внимание, что все длины в байтах могут зависеть от операционной системы.

Преобразование 1D/long в 1D/unsigned bytes:

>>> import array
>>> a = array.array('l', [1,2,3])
>>> x = memoryview(a)
>>> x.format
'l'
>>> x.itemsize
8
>>> len(x)
3
>>> x.nbytes
24
>>> y = x.cast('B')
>>> y.format
'B'
>>> y.itemsize
1
>>> len(y)
24
>>> y.nbytes
24

Преобразование 1D/unsigned bytes в 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/bytes в 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]]

Добавлено в версии 3.3.

Изменено в версии 3.5: Исходный формат больше не ограничен при преобразовании в байтовое представление.

count(value, /)¶

Подсчитывает количество вхождений value.

Добавлено в версии 3.14.

index(value, start=0, stop=sys.maxsize, /)¶

Возвращает индекс первого вхождения value (начиная с индекса start и до индекса stop).

Возбуждает исключение ValueError, если value не найден.

Добавлено в версии 3.14.

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

obj¶

Базовый объект memoryview:

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

Добавлено в версии 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

Добавлено в версии 3.3.

readonly¶

Логическое значение, указывающее, доступна ли память только для чтения.

format¶

Строка, содержащая формат (в стиле модуля struct) для каждого элемента в представлении. Memoryview может быть создан из экспортеров с произвольными строками формата, но некоторые методы (например, 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-непрерывной.

Добавлено в версии 3.3.

f_contiguous¶

Логическое значение, указывающее, является ли память Fortran непрерывной.

Добавлено в версии 3.3.

contiguous¶

Логическое значение, указывающее, является ли память непрерывной.

Добавлено в версии 3.3.

Для получения информации о потокобезопасности объектов memoryview в сборке со свободными потоками обратитесь к Thread safety for memoryview objects.

Типы множеств – set, frozenset

Объект set (множество) – это неупорядоченная коллекция различных хэшируемых объектов. Обычно используется для проверки принадлежности, удаления дубликатов из последовательности и выполнения математических операций, таких как пересечение, объединение, разность и симметрическая разность. (Другие контейнеры см. во встроенных классах dict, list и tuple, а также в модуле collections.)

Как и другие коллекции, множества поддерживают x in set, len(set) и for x in set. Будучи неупорядоченной коллекцией, множества не запоминают положение элемента или порядок вставки. Соответственно, множества не поддерживают индексирование, срезы или другое поведение, подобное последовательностям.

В настоящее время существуют два встроенных типа множеств: set и frozenset. Тип set является изменяемым – его содержимое можно изменять с помощью таких методов, как add() и remove(). Поскольку он изменяем, у него нет хэш-значения, и он не может использоваться ни как ключ словаря, ни как элемент другого множества. Тип frozenset является неизменяемым и хэшируемым – его содержимое не может быть изменено после создания; поэтому он может использоваться как ключ словаря или как элемент другого множества.

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

Конструкторы обоих классов работают одинаково:

class set(iterable=(), /)¶

class frozenset(iterable=(), /)¶

Возвращает новый объект set или frozenset, элементы которого берутся из iterable. Элементы множества должны быть хешируемыми. Для представления множеств множеств внутренние множества должны быть объектами frozenset. Если iterable не указан, возвращается новое пустое множество.

Множества можно создать несколькими способами:

• Используйте список элементов, разделённых запятыми, в фигурных скобках: {'jack', 'sjoerd'}

• Используйте генератор множества: {c for c in 'abracadabra' if c not in '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.

frozenset.isdisjoint(other, /)¶

set.isdisjoint(other, /)¶

Возвращает True, если множество не имеет общих элементов с other. Множества являются непересекающимися тогда и только тогда, когда их пересечение является пустым множеством.

frozenset.issubset(other, /)¶

set.issubset(other, /)¶

set <= other

Проверяет, содержится ли каждый элемент множества в other.

set < other

Проверяет, является ли множество собственным подмножеством other, то есть set <= other and set != other.

frozenset.issuperset(other, /)¶

set.issuperset(other, /)¶

set >= other

Проверяет, содержится ли каждый элемент из other в множестве.

set > other

Проверяет, является ли множество собственным надмножеством other, то есть set >= other and set != other.

frozenset.union(*others)¶

set.union(*others)¶

set | other | ...

Возвращает новое множество, содержащее элементы данного множества и всех остальных.

frozenset.intersection(*others)¶

set.intersection(*others)¶

set & other & ...

Возвращает новое множество с элементами, общими для данного множества и всех остальных.

frozenset.difference(*others)¶

set.difference(*others)¶

set - other - ...

Возвращает новое множество с элементами из исходного множества, которых нет в остальных.

frozenset.symmetric_difference(other, /)¶

set.symmetric_difference(other, /)¶

set ^ other

Возвращает новое множество с элементами, которые есть либо в исходном множестве, либо в other, но не в обоих.

frozenset.copy()¶

set.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') in set([frozenset('abc')]).

Сравнения на подмножество и равенство не обобщаются до функции полного порядка. Например, любые два непустых непересекающихся множества не равны и не являются подмножествами друг друга, поэтому все из следующих возвращают False: a<b, a==b или a>b.

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

Элементы множества, как и ключи словаря, должны быть хешируемыми.

Бинарные операции, в которых смешиваются экземпляры set с frozenset, возвращают тип первого операнда. Например: frozenset('ab') | set('bc') возвращает экземпляр frozenset.

В следующей таблице перечислены операции, доступные для set, которые не применимы к неизменяемым экземплярам frozenset:

set.update(*others)¶

set |= other | ...

Обновляет множество, добавляя элементы из всех остальных.

set.intersection_update(*others)¶

set &= other & ...

Обновляет множество, оставляя только те элементы, которые есть в нём и во всех остальных.

set.difference_update(*others)¶

set -= other | ...

Обновляет множество, удаляя элементы, которые есть в других.

set.symmetric_difference_update(other, /)¶

set ^= other

Обновляет множество, оставляя только элементы, которые присутствуют в одном из множеств, но не в обоих.

set.add(elem, /)¶

Добавляет элемент elem в множество.

set.remove(elem, /)¶

Удаляет элемент elem из множества. Возбуждает KeyError, если elem не содержится в множестве.

set.discard(elem, /)¶

Удаляет элемент elem из множества, если он присутствует.

set.pop()¶

Удаляет и возвращает произвольный элемент из множества. Возбуждает KeyError, если множество пусто.

set.clear()¶

Удаляет все элементы из множества.

Примечание: неоператорные версии методов update(), intersection_update(), difference_update() и symmetric_difference_update() принимают в качестве аргумента любой итерируемый объект.

Примечание: аргумент elem методов __contains__(), remove() и discard() может быть множеством. Для поддержки поиска эквивалентного frozenset создаётся временный frozenset из elem.

Смотрите также

За подробной информацией о гарантиях потокобезопасности для объектов set обращайтесь к Потокобезопасность объектов множества.

Типы отображений – dict, frozendict

Объект mapping сопоставляет хешируемые значения произвольным объектам. В настоящее время существует два стандартных типа отображений: dictionary и frozendict. (Другие контейнеры см. во встроенных классах list, set и tuple, а также в модуле collections.)

Ключи словаря – это почти произвольные значения. Значения, не являющиеся хешируемыми, т.е. значения, содержащие списки, словари или другие изменяемые типы (которые сравниваются по значению, а не по идентичности объекта), не могут использоваться в качестве ключей. Значения, которые равны при сравнении (например, 1, 1.0 и True), могут использоваться взаимозаменяемо для обращения к одной и той же записи словаря.

class dict(**kwargs)¶

class dict(mapping, /, **kwargs)

class dict(iterable, /, **kwargs)

Возвращает новый словарь, инициализированный из необязательного позиционного аргумента и, возможно, пустого набора именованных аргументов.

Словари могут быть созданы несколькими способами:

• Используйте разделённый запятыми список пар key: value в фигурных скобках: {'jack': 4098, 'sjoerd': 4127} или {4098: 'jack', 4127: 'sjoerd'}

• Используйте словарное включение: {}, {x: x ** 2 for x in range(10)}

• Используйте конструктор типа: dict(), dict([('foo', 100), ('bar', 200)]), dict(foo=100, bar=200)

Если позиционный аргумент не указан, создаётся пустой словарь. Если позиционный аргумент указан и определяет метод keys(), словарь создаётся путём вызова __getitem__() для аргумента с каждым возвращённым ключом из этого метода. В противном случае позиционный аргумент должен быть объектом iterable. Каждый элемент итерируемого объекта сам должен быть итерируемым с ровно двумя элементами. Первый элемент каждого элемента становится ключом в новом словаре, а второй – соответствующим значением. Если ключ встречается более одного раза, последнее значение для этого ключа становится соответствующим значением в новом словаре.

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

Словари сравниваются как равные тогда и только тогда, когда они содержат одинаковые пары (key, value) (независимо от порядка). Операции сравнения порядка (‘<’, ‘<=’, ‘>=’, ‘>’) возбуждают TypeError. Для иллюстрации создания словарей и равенства следующие примеры все возвращают словарь, равный {"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. В противном случае можно использовать любые допустимые ключи.

Словари сохраняют порядок вставки. Обратите внимание, что обновление ключа не влияет на порядок. Ключи, добавленные после удаления, вставляются в конец.

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

Вот операции, которые поддерживают словари (а значит, должны поддерживать и пользовательские типы отображений):

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

Эквивалентно not key in d.

iter(d)

Возвращает итератор по ключам словаря. Это сокращение для iter(d.keys()).

clear()¶

Удаляет все элементы из словаря.

copy()¶

Возвращает поверхностную копию словаря.

classmethod fromkeys(iterable, value=None, /)¶

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

fromkeys() – это метод класса, который возвращает новый словарь. value по умолчанию равен None. Все значения ссылаются на один и тот же экземпляр, поэтому обычно не имеет смысла делать value изменяемым объектом, например пустым списком. Чтобы получить разные значения, используйте вместо этого словарное включение.

get(key, default=None, /)¶

Возвращает значение для key, если key есть в словаре, иначе default. Если default не задан, по умолчанию используется None, поэтому этот метод никогда не возбуждает KeyError.

items()¶

Возвращает новое представление элементов словаря (пары (key, value)). См. документацию по объектам представлений.

keys()¶

Возвращает новое представление ключей словаря. См. документацию по объектам представлений.

pop(key, /)¶

pop(key, default, /)

Если ключ находится в словаре, удалить его и вернуть его значение, иначе вернуть default. Если default не указан и ключ отсутствует в словаре, возбуждается KeyError.

popitem()¶

Удаляет и возвращает пару (key, value) из словаря. Пары возвращаются в порядке LIFO.

popitem() полезен для разрушающего перебора словаря, как это часто используется в алгоритмах над множествами. Если словарь пуст, вызов popitem() возбуждает KeyError.

Изменено в версии 3.7: Порядок LIFO теперь гарантирован. В предыдущих версиях popitem() возвращал произвольную пару ключ/значение.

reversed(d)

Возвращает обратный итератор по ключам словаря. Это сокращение для reversed(d.keys()).

Добавлено в версии 3.8.

setdefault(key, default=None, /)¶

Если ключ находится в словаре, вернуть его значение. Если нет, вставить ключ со значением default и вернуть default. default по умолчанию равен None.

update(**kwargs)¶

update(mapping, /, **kwargs)

update(iterable, /, **kwargs)

Обновляет словарь парами ключ/значение из mapping или iterable и kwargs, перезаписывая существующие ключи. Возвращает None.

update() принимает либо другой объект с методом keys() (в этом случае __getitem__() вызывается для каждого ключа, возвращаемого методом), либо итерируемый объект пар ключ/значение (в виде кортежей или других итерируемых объектов длины два). Если указаны именованные аргументы, словарь затем обновляется этими парами ключ/значение: 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 содержат одинаковые ключи.

Добавлено в версии 3.9.

d |= other

Обновляет словарь d ключами и значениями из other, который может быть либо mapping (отображением), либо iterable (итерируемым объектом) пар ключ/значение. Значения other имеют приоритет, когда d и other содержат одинаковые ключи.

Добавлено в версии 3.9.

Словари и представления словарей являются обратимыми.

>>> 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: Словари теперь являются обратимыми.

Смотрите также

frozendict и types.MappingProxyType можно использовать для создания представления только для чтения dict.

Смотрите также

Подробную информацию о гарантиях потокобезопасности для объектов dict см. в Потокобезопасность объектов dict.

Dictionary view objectsОбъекты представлений словаря

Объекты, возвращаемые dict.keys(), dict.values() и dict.items(), являются объектами представлений. Они обеспечивают динамическое представление записей словаря, что означает: при изменении словаря представление отражает эти изменения.

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

len(dictview)

Возвращает количество записей в словаре.

iter(dictview)

Возвращает итератор по ключам, значениям или элементам (представленным в виде кортежей (key, value)) словаря.

Ключи и значения перебираются в порядке вставки. Это позволяет создавать пары (value, key) с помощью 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 должен быть кортежем (key, value)).

reversed(dictview)

Возвращает реверсивный итератор по ключам, значениям или элементам словаря. Представление будет перебираться в обратном порядке вставки.

Изменено в версии 3.8: Представления словаря теперь поддерживают обратную итерацию.

dictview.mapping

Возвращает types.MappingProxyType, обёртывающий исходный словарь, на который ссылается представление.

Добавлено в версии 3.10.

Представления ключей ведут себя как множества, поскольку их элементы уникальны и хэшируемы. Представления элементов также поддерживают операции над множествами, поскольку пары (ключ, значение) уникальны, а ключи хэшируемы. Если все значения в представлении элементов также хэшируемы, то представление элементов может взаимодействовать с другими множествами. (Представления значений не считаются подобными множествам, так как их элементы обычно не уникальны.) Для представлений, подобных множествам, доступны все операции, определённые для абстрактного базового класса collections.abc.Set (например, ==, < или ^). При использовании операторов множеств такие представления принимают любой итерируемый объект в качестве другого операнда, в отличие от множеств, которые принимают только множества.

Пример использования представлений словаря:

>>> dishes = {'eggs': 2, 'sausage': 1, 'bacon': 1, 'spam': 500}
>>> keys = dishes.keys()
>>> values = dishes.values()

>>> # итерация
>>> n = 0
>>> for val in values:
...     n += val
...
>>> print(n)
504

>>> # ключи и значения перебираются в одном порядке (порядок вставки)
>>> list(keys)
['eggs', 'sausage', 'bacon', 'spam']
>>> list(values)
[2, 1, 1, 500]

>>> # объекты представления динамические и отражают изменения словаря
>>> del dishes['eggs']
>>> del dishes['sausage']
>>> list(keys)
['bacon', 'spam']

>>> # операции над множествами
>>> keys & {'eggs', 'bacon', 'salad'}
{'bacon'}
>>> keys ^ {'sausage', 'juice'} == {'juice', 'sausage', 'bacon', 'spam'}
True
>>> keys | ['juice', 'juice', 'juice'] == {'bacon', 'spam', 'juice'}
True

>>> # получить прокси только для чтения для исходного словаря
>>> values.mapping
mappingproxy({'bacon': 1, 'spam': 500})
>>> values.mapping['spam']
500

Frozen dictionariesЗамороженные словари

class frozendict(**kwargs)¶

class frozendict(mapping, /, **kwargs)

class frozendict(iterable, /, **kwargs)

Возвращает новый замороженный словарь, инициализированный из необязательного позиционного аргумента и, возможно, пустого набора именованных аргументов.

frozendict имеет API, аналогичный dict API, со следующими отличиями:

• dict содержит больше методов, чем frozendict:

  • __delitem__()

  • __setitem__()

  • clear()

  • pop()

  • popitem()

  • setdefault()

  • update()

• frozendict может быть хэширован с помощью hash(frozendict), если все ключи и значения могут быть хэшированы.

• frozendict |= other не изменяет frozendict на месте, а создаёт новый замороженный словарь.

frozendict не является подклассом dict, а наследует напрямую от object.

Добавлено в версии 3.15.

Context Manager TypesТипы менеджеров контекста

Инструкция with в Python поддерживает концепцию контекста выполнения, определяемого менеджером контекста. Это реализовано с помощью пары методов, которые позволяют пользовательским классам определять контекст выполнения, который входит до выполнения тела инструкции и выходит по окончании инструкции:

contextmanager.__enter__()¶

Входит в контекст выполнения и возвращает либо этот объект, либо другой объект, связанный с контекстом выполнения. Значение, возвращаемое этим методом, связывается с идентификатором в предложении as инструкции with, использующей этот менеджер контекста.

Примером менеджера контекста, возвращающего самого себя, является файловый объект. Файловые объекты возвращают себя из __enter__(), чтобы open() можно было использовать как контекстное выражение в инструкции with.

Примером менеджера контекста, возвращающего связанный объект, является тот, который возвращается decimal.localcontext(). Эти менеджеры устанавливают активный десятичный контекст как копию исходного десятичного контекста, а затем возвращают копию. Это позволяет вносить изменения в текущий десятичный контекст в теле инструкции with, не влияя на код за пределами инструкции with.

contextmanager.__exit__(exc_type, exc_val, exc_tb)¶

Выходит из контекста выполнения и возвращает логический флаг, указывающий, следует ли подавить возникшее исключение. Если при выполнении тела инструкции with возникло исключение, аргументы содержат тип исключения, значение и информацию о трассировке. В противном случае все три аргумента равны None.

Возврат истинного значения из этого метода приведёт к тому, что инструкция with подавит исключение и продолжит выполнение с инструкции, следующей сразу за инструкцией with. В противном случае исключение продолжит распространяться после завершения выполнения этого метода.

Если этот метод вызывает исключение при обработке предыдущего исключения из блока with, новое исключение возбуждается, а исходное исключение сохраняется в его атрибуте __context__.

Переданное исключение никогда не должно возбуждаться явно; вместо этого метод должен возвращать ложное значение, указывающее, что метод успешно завершён и не хочет подавлять возникшее исключение. Это позволяет коду управления контекстом легко определить, действительно ли метод __exit__() завершился ошибкой.

В Python определено несколько менеджеров контекста для поддержки простой синхронизации потоков, быстрого закрытия файлов или других объектов и более простого управления активным контекстом десятичной арифметики. Конкретные типы не обрабатываются особым образом, помимо реализации протокола управления контекстом. См. модуль contextlib для примеров.

Генераторы Python и декоратор contextlib.contextmanager предоставляют удобный способ реализации этих протоколов. Если функция-генератор декорирована декоратором contextlib.contextmanager, она вернёт менеджер контекста, реализующий необходимые методы __enter__() и __exit__(), а не итератор, создаваемый недекорированной функцией-генератором.

Обратите внимание, что в структуре типа для объектов Python в Python/C API нет специального слота для любого из этих методов. Расширяемые типы, желающие определить эти методы, должны предоставить их как обычный метод, доступный из Python. По сравнению с накладными расходами на настройку контекста выполнения, накладные расходы на один поиск в словаре класса незначительны.

Типы аннотаций типов – Generic Alias, Union

Основными встроенными типами для аннотаций типов являются Generic Alias и Union.

Generic Alias TypeТип Generic Alias

Объекты GenericAlias обычно создаются путём индексирования класса. Чаще всего они используются с классами-контейнерами, такими как list или dict. Например, list[int] – это объект GenericAlias, созданный индексированием класса list с аргументом int. Объекты GenericAlias предназначены в первую очередь для использования с аннотациями типов.

Примечание

Обычно индексировать класс можно только в том случае, если класс реализует специальный метод __class_getitem__().

Объект GenericAlias действует как прокси для универсального типа, реализуя параметризованные универсальные шаблоны.

Для класса-контейнера аргумент(ы), передаваемые при индексировании класса, могут указывать тип(ы) элементов, содержащихся в объекте. Например, set[bytes] можно использовать в аннотациях типов для обозначения set, в котором все элементы имеют тип bytes.

Для класса, который определяет __class_getitem__(), но не является контейнером, аргумент(ы), передаваемые при индексировании класса, часто указывают тип(ы) возвращаемого значения одного или нескольких методов, определённых для объекта. Например, regular expressions можно использовать как с типом данных 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, ...]

Создаёт GenericAlias, представляющий тип 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]

Standard Generic ClassesСтандартные универсальные классы

Следующие классы стандартной библиотеки поддерживают параметризованные универсальные шаблоны. Этот список не является исчерпывающим.

• tuple

• list

• dict

• set

• frozendict

• frozenset

• type

• asyncio.Future

• asyncio.Task

• collections.deque

• collections.defaultdict

• collections.OrderedDict

• collections.Counter

• collections.ChainMap

• collections.abc.Awaitable

• collections.abc.Coroutine

• collections.abc.AsyncIterable

• collections.abc.AsyncIterator

• collections.abc.AsyncGenerator

• collections.abc.Iterable

• collections.abc.Iterator

• collections.abc.Generator

• collections.abc.Reversible

• collections.abc.Container

• collections.abc.Collection

• collections.abc.Callable

• collections.abc.Set

• collections.abc.MutableSet

• collections.abc.Mapping

• collections.abc.MutableMapping

• collections.abc.Sequence

• collections.abc.MutableSequence

• collections.abc.ByteString

• collections.abc.MappingView

• collections.abc.KeysView

• collections.abc.ItemsView

• collections.abc.ValuesView

• contextlib.AbstractContextManager

• contextlib.AbstractAsyncContextManager

• dataclasses.Field

• functools.cached_property

• functools.partialmethod

• os.PathLike

• queue.LifoQueue

• queue.Queue

• queue.PriorityQueue

• queue.SimpleQueue

• re.Pattern

• re.Match

• shelve.BsdDbShelf

• shelve.DbfilenameShelf

• shelve.Shelf

• types.MappingProxyType

• weakref.WeakKeyDictionary

• weakref.WeakMethod

• weakref.WeakSet

• weakref.WeakValueDictionary

Специальные атрибуты объектов 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__¶

Логическое значение, истинное, если псевдоним был распакован с помощью оператора * (см. TypeVarTuple).

Добавлено в версии 3.11.

Смотрите также

PEP 484 - Аннотации типов

Представление фреймворка Python для аннотаций типов.

PEP 585 - Обобщённые типы с аннотациями в стандартных коллекциях

Вводит возможность нативной параметризации классов стандартной библиотеки при условии, что они реализуют специальный метод класса __class_getitem__().

Обобщённые типы, пользовательские обобщённые типы и typing.Generic

Документация по реализации обобщённых классов, которые могут быть параметризованы во время выполнения и понятны статическим анализаторам типов.

Добавлено в версии 3.9.

Union TypeТип объединения

Объект объединения содержит значение операции | (побитовое ИЛИ) над несколькими объектами типов. Эти типы предназначены в первую очередь для аннотаций типов. Выражение типа объединения обеспечивает более чистый синтаксис аннотаций по сравнению с индексированием 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

Примечание

Операнд | не может использоваться во время выполнения для определения объединений, где один или несколько членов являются упреждающими ссылками. Например, int | "Foo", где "Foo" – ссылка на ещё не определённый класс, завершится ошибкой во время выполнения. Для объединений, содержащих упреждающие ссылки, представляйте всё выражение в виде строки, например "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]
  type(int | str) is typing.Union
  

• Необязательные типы можно записать как объединение с None:

  str | None == typing.Optional[str]
  

isinstance(obj, union_object)

issubclass(obj, union_object)

Вызовы isinstance() и issubclass() также поддерживаются для объекта объединения:

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

Однако параметризованные обобщённые типы в объектах объединения не могут быть проверены:

>>> isinstance(1, int | list[int])  # короткое замыкание вычислений
True
>>> isinstance([1], int | list[int])
Traceback (most recent call last):
  ...
TypeError: isinstance() argument 2 cannot be a parameterized generic

Тип объекта объединения, доступный пользователю, можно получить из typing.Union и использовать для проверок isinstance():

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

Примечание

Метод __or__() для объектов типов был добавлен для поддержки синтаксиса X | Y. Если метакласс реализует __or__(), Union может переопределить его:

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

Добавлено в версии 3.10.

Изменено в версии 3.14: Объекты Union теперь являются экземплярами typing.Union. Ранее они были экземплярами types.UnionType, который остаётся псевдонимом typing.Union.

Other Built-in TypesДругие встроенные типы

Интерпретатор поддерживает несколько других видов объектов. Большинство из них поддерживают только одну или две операции.

ModulesМодули

Единственная специальная операция над модулем – доступ к атрибуту: 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'>.

Classes and Class InstancesКлассы и экземпляры классов

См. Объекты, значения и типы и Определения классов.

FunctionsФункции

Объекты-функции создаются определениями функций. Единственная операция над объектом-функцией – это вызов: func(argument-list).

На самом деле существует две разновидности объектов-функций: встроенные функции и функции, определённые пользователем. Обе поддерживают одну и ту же операцию (вызов функции), но реализация различается, отсюда разные типы объектов.

См. Определения функций для получения дополнительной информации.

MethodsМетоды

Методы – это функции, которые вызываются с использованием точечной записи. Существует две разновидности: встроенные методы (такие как append() для списков) и методы экземпляров классов. Встроенные методы описаны вместе с типами, которые их поддерживают.

Если обратиться к методу (функции, определённой в пространстве имён класса) через экземпляр, получается специальный объект: связанный метод (также называемый метод экземпляра). При вызове он добавляет аргумент self в список аргументов. Связанные методы имеют два специальных атрибута только для чтения: m.__self__ – это объект, над которым метод выполняется, а m.__func__ – функция, реализующая метод. Вызов m(arg-1, arg-2, ..., arg-n) полностью эквивалентен вызову m.__func__(m.__self__, arg-1, arg-2, ..., arg-n).

Как и объекты-функции, объекты связанных методов поддерживают получение произвольных атрибутов. Однако, поскольку атрибуты метода на самом деле хранятся в базовом объекте функции (method.__func__), установка атрибутов метода на связанных методах запрещена. Попытка установить атрибут метода приводит к возбуждению AttributeError. Чтобы установить атрибут метода, нужно явно установить его в базовом объекте функции:

>>> class C:
...     def method(self):
...         pass
...
>>> c = C()
>>> c.method.whoami = 'my name is 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'

См. Методы экземпляра для получения дополнительной информации.

Code ObjectsОбъекты кода

Объекты кода используются реализацией для представления «псевдокомпилированного» исполняемого кода Python, например тела функции. Они отличаются от объектов-функций тем, что не содержат ссылки на глобальное окружение выполнения. Объекты кода возвращаются встроенной функцией compile() и могут быть извлечены из объектов-функций через их атрибут __code__. См. также модуль code.

Доступ к __code__ вызывает событие аудита object.__getattr__ с аргументами obj и "__code__".

Объект кода может быть выполнен или вычислен путём передачи его (вместо исходной строки) встроенным функциям exec() или eval().

См. Стандартная иерархия типов для получения дополнительной информации.

Type ObjectsОбъекты типов

Объекты типов представляют различные типы объектов. Тип объекта получается встроенной функцией type(). Над типами не определено специальных операций. Стандартный модуль types определяет имена для всех стандартных встроенных типов.

Типы записываются так: <class 'int'>.

The Null ObjectNull-объект

Этот объект возвращается функциями, которые не возвращают явно значение. Он не поддерживает специальных операций. Существует ровно один нулевой объект с именем None (встроенное имя). type(None)() создаёт тот же синглтон.

Он записывается как None.

The Ellipsis ObjectОбъект Ellipsis

Этот объект обычно используется для обозначения пропуска чего-либо. Он не поддерживает специальных операций. Существует ровно один объект многоточия с именем Ellipsis (встроенное имя). type(Ellipsis)() создаёт Ellipsis синглтон.

Он записывается как Ellipsis или ....

В типичном использовании объект ... как Ellipsis встречается в нескольких разных местах, например:

• В аннотациях типов, таких как вызываемые аргументы или элементы кортежей.

• В качестве тела функции вместо оператора pass.

• В сторонних библиотеках, таких как срезы и шаги в Numpy.

Python также использует многоточие в случаях, когда это не объекты Ellipsis, например:

• ELLIPSIS в doctest, как обозначение пропущенного содержимого.

• Стандартное приглашение Python интерактивной оболочки, когда ввод неполный.

Наконец, в документации Python многоточие часто используется в обычном английском смысле для обозначения пропущенного содержимого даже в примерах кода, где оно также используется как Ellipsis.

The NotImplemented ObjectОбъект NotImplemented

Этот объект возвращается из сравнений и бинарных операций, когда их просят работать с типами, которые они не поддерживают. См. Сравнения для получения дополнительной информации. Существует ровно один объект NotImplemented. type(NotImplemented)() создаёт экземпляр-одиночку.

Он записывается как NotImplemented.

Internal ObjectsВнутренние объекты

См. Стандартная иерархия типов для этой информации. В ней описываются объекты кадров стека, объекты трассировки и объекты срезов.

Special AttributesСпециальные атрибуты

Реализация добавляет несколько специальных атрибутов только для чтения к некоторым типам объектов, где это уместно. Некоторые из них не сообщаются встроенной функцией dir().

definition.__name__¶

Имя класса, функции, метода, дескриптора или экземпляра генератора.

definition.__qualname__¶

Квалифицированное имя класса, функции, метода, дескриптора или экземпляра генератора.

Добавлено в версии 3.3.

definition.__module__¶

Имя модуля, в котором был определён класс или функция.

definition.__doc__¶

Строка документации класса или функции, или None, если не определена.

definition.__type_params__¶

Параметры типа обобщённых классов, функций и псевдонимов типов. Для классов и функций, которые не являются обобщёнными, это будет пустой кортеж.

Добавлено в версии 3.12.

Integer string conversion length limitationОграничение длины преобразования целого числа в строку

CPython имеет глобальное ограничение на преобразование между int и str для смягчения атак типа «отказ в обслуживании». Это ограничение применяется только к десятичной или другим системам счисления, не являющимся степенями двойки. Преобразования в шестнадцатеричную, восьмеричную и двоичную системы не ограничены. Ограничение можно настроить.

Тип int в CPython представляет собой число произвольной длины, хранящееся в двоичной форме (обычно известное как «длинное целое»). Не существует алгоритма, который мог бы преобразовать строку в двоичное целое или двоичное целое в строку за линейное время, если только основание не является степенью двойки. Даже лучшие известные алгоритмы для основания 10 имеют субквадратичную сложность. Преобразование большого значения, такого как int('1' * 500_000), может занять более секунды на быстром процессоре.

Ограничение размера преобразования даёт практический способ избежать CVE 2020-10735.

Ограничение применяется к количеству цифровых символов во входной или выходной строке, когда задействован нелинейный алгоритм преобразования. Символы подчёркивания и знак не учитываются в ограничении.

Когда операция превышает ограничение, возникает исключение ValueError:

>>> import sys
>>> sys.set_int_max_str_digits(4300)  # Иллюстративно, это значение по умолчанию.
>>> _ = 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  # Шестнадцатеричное представление не ограничено.

Ограничение по умолчанию составляет 4300 цифр, как указано в sys.int_info.default_max_str_digits. Минимальное настраиваемое ограничение составляет 640 цифр, как указано в sys.int_info.str_digits_check_threshold.

Проверка:

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

Добавлено в версии 3.11.

Affected APIsЗатронутые API

Ограничение применяется только к потенциально медленным преобразованиям между int и str или bytes:

• int(string) с основанием 10 по умолчанию.

• int(string, base) для всех оснований, не являющихся степенью 2.

• str(integer).

• repr(integer).

• любое другое преобразование строки в основание 10, например f"{integer}", "{}".format(integer) или b"%d" % integer.

Ограничения не применяются к функциям с линейным алгоритмом:

• int(string, base) с основанием 2, 4, 8, 16 или 32.

• int.from_bytes() и int.to_bytes().

• hex(), oct(), bin().

• Мини-язык спецификации формата для шестнадцатеричных, восьмеричных и двоичных чисел.

• str в float.

• str в decimal.Decimal.

Configuring the limitНастройка предела

До запуска Python можно использовать переменную окружения или флаг командной строки интерпретатора для настройки предела:

• PYTHONINTMAXSTRDIGITS, например PYTHONINTMAXSTRDIGITS=640 python3, чтобы установить предел 640, или PYTHONINTMAXSTRDIGITS=0 python3, чтобы отключить ограничение.

• -X int_max_str_digits, например python3 -X int_max_str_digits=640

• sys.flags.int_max_str_digits содержит значение PYTHONINTMAXSTRDIGITS или -X int_max_str_digits. Если заданы и переменная окружения, и опция -X, то опция -X имеет преимущество. Значение -1 указывает, что обе не заданы, поэтому при инициализации использовалось значение sys.int_info.default_max_str_digits.

Из кода можно проверить текущий предел и установить новый с помощью следующих sys API:

• sys.get_int_max_str_digits() и sys.set_int_max_str_digits() – это геттер и сеттер для общеинтерпретаторского предела. Подинтерпретаторы имеют собственный предел.

Информацию о значении по умолчанию и минимальном значении можно найти в sys.int_info:

• sys.int_info.default_max_str_digits – это скомпилированный предел по умолчанию.

• sys.int_info.str_digits_check_threshold – это наименьшее допустимое значение предела (кроме 0, который отключает его).

Добавлено в версии 3.11.

Предостережение

Установка низкого предела может привести к проблемам. Хотя это редкость, существует код, который содержит в исходниках целочисленные константы в десятичной системе, превышающие минимальный порог. Следствием установки предела является то, что исходный код Python, содержащий десятичные целочисленные литералы длиннее предела, приведёт к ошибке при разборе, обычно во время запуска или импорта, или даже во время установки – всякий раз, когда актуальный файл .pyc уже не существует для этого кода. Обходной путь для исходного кода, содержащего такие большие константы, – преобразовать их в 0x шестнадцатеричную форму, так как для неё нет предела.

Тщательно тестируйте своё приложение, если вы используете низкий предел. Убедитесь, что ваши тесты запускаются с установленным пределом на раннем этапе через переменную окружения или флаг, чтобы он применялся во время запуска и даже на любом этапе установки, который может вызвать Python для предварительной компиляции .py исходников в файлы .pyc.

Recommended configurationРекомендуемая конфигурация

Ожидается, что sys.int_info.default_max_str_digits по умолчанию будет приемлемым для большинства приложений. Если вашему приложению требуется другой предел, установите его из основной точки входа, используя код, не зависящий от версии Python, так как эти API были добавлены в выпусках исправлений безопасности в версиях до 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)

Если вам нужно полностью отключить его, установите значение 0.

Сноски

[1]

Дополнительную информацию об этих специальных методах можно найти в справочном руководстве Python (Базовая настройка).

[2]

Как следствие, список [1, 2] считается равным [1.0, 2.0], и аналогично для кортежей.

[3]

Они должны иметь, так как синтаксический анализатор не может определить тип операндов.

[4] (1,2,3,4)

Символы, имеющие регистр, – это те, у которых общее свойство категории является одним из «Lu» (буква прописная), «Ll» (буква строчная) или «Lt» (буква заглавная).

[5] (1,2)

Чтобы отформатировать только кортеж, следует предоставить одноэлементный кортеж, единственным элементом которого является форматируемый кортеж.