Встроенные типы

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

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

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

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

Проверка истинности ценности

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

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

• константы, определенные как ложные: None и False.

• ноль любого числового типа: 0, 0.0, 0j, Decimal(0), Fraction(0, 1)

• пустые последовательности и коллекции: '', (), [], {}, set(), range(0)

Операции и встроенные функции, имеющие булевский результат, всегда возвращают 0 или False для false и 1 или True для 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. Это оператор короткого замыкания, поэтому он оценивает второй аргумент только в том случае, если первый истинен.

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

Сравнения

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

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

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

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

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

Экземпляры класса не могут быть упорядочены относительно других экземпляров того же класса или других типов объектов, если в классе не определено достаточное количество методов __lt__(), __le__(), __gt__() и __ge__() (в общем случае достаточно __lt__() и __eq__(), если вы хотите использовать обычные значения операторов сравнения).

Поведение операторов is и is not нельзя настроить; кроме того, они могут быть применены к любым двум объектам и никогда не вызовут исключения.

Еще две операции с тем же синтаксическим приоритетом, in и not in, поддерживаются типами, которые являются iterable или реализуют метод __contains__().

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

Существует три различных числовых типа: integers, floating point numbers и complex numbers. Кроме того, булевы числа являются подтипом целых чисел. Целые числа имеют неограниченную точность. Числа с плавающей точкой обычно реализуются с помощью double в языке C; информацию о точности и внутреннем представлении чисел с плавающей точкой для машины, на которой выполняется ваша программа, можно найти в sys.float_info. Комплексные числа имеют действительную и мнимую части, каждая из которых является числом с плавающей точкой. Чтобы извлечь эти части из комплексного числа z, используйте z.real и z.imag. (В стандартную библиотеку входят дополнительные числовые типы fractions.Fraction для рациональных чисел и decimal.Decimal для чисел с плавающей точкой с задаваемой пользователем точностью).

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

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

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

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

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

Примечания:

1. Также называется целочисленным делением. Для операндов типа int результат имеет тип int. Для операндов типа float результат имеет тип float. В общем случае результатом является целое число, хотя тип результата не обязательно int. Результат всегда округляется в сторону минус бесконечности: 1//2 - это 0, (-1)//2 - это -1, 1//(-2) - это -1, а (-1)//(-2) - это 0.

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

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

4. float также принимает строки «nan» и «inf» с необязательным префиксом «+» или «-» для обозначения «не числа» (NaN) и положительной или отрицательной бесконечности.

5. Python определяет pow(0, 0) и 0 ** 0 как 1, как это принято в языках программирования.

6. В числовые литералы принимаются цифры от 0 до 9 или любой эквивалент Unicode (кодовые точки со свойством Nd).

   Полный список точек кода со свойством Nd см. в разделе the Unicode Standard.

Все типы numbers.Real (int и float) также включают следующие операции:

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

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

Побитовые операции над целочисленными типами

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

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

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

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

Примечания:

1. Отрицательные значения сдвига недопустимы и приводят к появлению ValueError.

2. Сдвиг влево на n бит эквивалентен умножению на pow(2, n).

3. Сдвиг вправо на n бит эквивалентен полу делению на pow(2, n).

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

Дополнительные методы для целочисленных типов

Тип int реализует numbers.Integral abstract base class. Кроме того, он предоставляет еще несколько методов:

int.bit_length()

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

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

Точнее, если x ненулевое, то x.bit_length() - единственное положительное целое число k такое, что 2**(k-1) <= abs(x) < 2**k. Эквивалентно, если abs(x) достаточно мало, чтобы иметь правильно округленный логарифм, то k = 1 + int(log(abs(x), 2)). Если x равен нулю, то x.bit_length() возвращает 0.

Эквивалент:

def bit_length(self):
    s = bin(self)       # binary representation:  bin(-37) --> '-0b100101'
    s = s.lstrip('-0b') # remove leading zeros and minus sign
    return len(s)       # len('100101') --> 6

Added in version 3.1.

int.bit_count()

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

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

Эквивалент:

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

Added in version 3.10.

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

Возвращает массив байтов, представляющих целое число.

>>> (1024).to_bytes(2, byteorder='big')
b'\x04\x00'
>>> (1024).to_bytes(10, byteorder='big')
b'\x00\x00\x00\x00\x00\x00\x00\x00\x04\x00'
>>> (-1024).to_bytes(10, byteorder='big', signed=True)
b'\xff\xff\xff\xff\xff\xff\xff\xff\xfc\x00'
>>> x = 1000
>>> x.to_bytes((x.bit_length() + 7) // 8, byteorder='little')
b'\xe8\x03'

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

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

Аргумент signed определяет, будет ли для представления целого числа использоваться дополнение двойки. Если значение signed равно False и задано отрицательное целое число, то будет выдано сообщение OverflowError. По умолчанию значение signed равно False.

Значения по умолчанию можно использовать для удобного преобразования целого числа в однобайтовый объект:

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

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

Эквивалент:

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

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

Added in version 3.2.

Изменено в версии 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 должен быть либо bytes-like object, либо итерируемым числом, производящим байты.

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

Added in version 3.2.

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

int.as_integer_ratio()

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

Added in version 3.8.

int.is_integer()

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

Added in version 3.12.

Дополнительные методы на поплавке

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

float.as_integer_ratio()

Возвращает пару целых чисел, отношение которых в точности равно исходному float. Отношение выражается в наименьших членах и имеет положительный знаменатель. Вызывает 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)

Метод класса, возвращающий float, представленный шестнадцатеричной строкой 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().

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

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

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

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

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

Для чисел 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-битным C longs и P = 2**61 - 1 на машинах с 64-битным C longs.

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

• Если 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, эквивалентного встроенному хэшу, для вычисления хэша рационального числа float или complex:

import sys, math

def hash_fraction(m, n):
    """Compute the hash of a rational number m / n.

    Assumes m and n are integers, with n positive.
    Equivalent to hash(fractions.Fraction(m, n)).

    """
    P = sys.hash_info.modulus
    # Remove common factors of P.  (Unnecessary if m and n already coprime.)
    while m % P == n % P == 0:
        m, n = m // P, n // P

    if n % P == 0:
        hash_value = sys.hash_info.inf
    else:
        # Fermat's Little Theorem: pow(n, P-1, P) is 1, so
        # pow(n, P-2, P) gives the inverse of n modulo P.
        hash_value = (abs(m) % P) * pow(n, P - 2, P) % P
    if m < 0:
        hash_value = -hash_value
    if hash_value == -1:
        hash_value = -2
    return hash_value

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

    if math.isnan(x):
        return object.__hash__(x)
    elif math.isinf(x):
        return sys.hash_info.inf if x > 0 else -sys.hash_info.inf
    else:
        return hash_fraction(*x.as_integer_ratio())

def hash_complex(z):
    """Compute the hash of a complex number z."""

    hash_value = hash_float(z.real) + sys.hash_info.imag * hash_float(z.imag)
    # do a signed reduction modulo 2**sys.hash_info.width
    M = 2**(sys.hash_info.width - 1)
    hash_value = (hash_value & (M - 1)) - (hash_value & M)
    if hash_value == -1:
        hash_value = -2
    return hash_value

Булевский тип - bool

Булевые числа представляют собой истинностные значения. Тип bool имеет ровно два константных экземпляра: True и False.

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

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

Не рекомендуется, начиная с версии 3.12: Использование оператора побитовой инверсии ~ устарело и приведет к ошибке в Python 3.14.

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

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

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

Для объектов-контейнеров необходимо определить один метод, чтобы обеспечить поддержку iterable:

container.__iter__()

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

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

iterator.__iter__()

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

iterator.__next__()

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

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

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

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

Контейнеры Python generatorобеспечивают удобный способ реализации протокола итераторов. Если метод __iter__() объекта-контейнера реализован как генератор, он автоматически возвращает объект-итератор (технически, объект-генератор), снабжающий его методами __iter__() и __next__(). Более подробную информацию о генераторах можно найти в the documentation for the yield expression.

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

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

Общие операции последовательности

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

В этой таблице перечислены операции над последовательностями, отсортированные по возрастанию приоритета. В таблице 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)
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
s.index(x[, i[, j]])	индекс первого вхождения x в s (на или после индекса i и до индекса j)	(8)
s.count(x)	общее количество вхождений x в s

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

Прямые и обратные итераторы над мутирующими последовательностями обращаются к значениям с помощью индекса. Этот индекс будет продолжать двигаться вперед (или назад), даже если базовая последовательность будет изменена. Итератор завершается только тогда, когда встречается IndexError или StopIteration (или когда индекс падает ниже нуля).

Примечания:

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

   >>> "gg" in "eggs"
   True
   

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

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

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

   >>> 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 или j больше len(s), используйте len(s). Если i опущено или None, используйте 0. Если j опущено или None, используйте len(s). Если i больше или равно j, то срез пуст.

5. Ломтик s от i до j с шагом k определяется как последовательность элементов с индексом x = i + n*k таких, что 0 <= n < (j-i)/k. Другими словами, индексы i, i+k, i+2*k, i+3*k и так далее, останавливаясь при достижении j (но никогда не включая j). Когда k положительно, i и j сокращаются до len(s), если они больше. Когда k отрицательно, i и j уменьшаются до len(s) - 1, если они больше. Если i или j опущены или None, они становятся «конечными» значениями (какой конец - зависит от знака k). Обратите внимание, что k не может быть нулем. Если k равно None, оно рассматривается как 1.

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

   • Если конкатенировать объекты str, можно построить список и использовать str.join() в конце или записать в экземпляр io.StringIO и получить его значение после завершения работы

   • При конкатенации объектов bytes можно аналогичным образом использовать bytes.join() или io.BytesIO, а можно выполнить конкатенацию in-place с помощью объекта bytearray. Объекты bytearray являются мутабельными и имеют эффективный механизм общего размещения

   • Если конкатенировать объекты tuple, вместо них следует расширить list

   • для других типов изучите документацию по соответствующему классу

7. Некоторые типы последовательностей (например, range) поддерживают только те последовательности элементов, которые следуют определенным шаблонам, и, следовательно, не поддерживают объединение или повторение последовательностей.

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

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

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

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

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

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

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

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

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

Примечания:

1. t должен иметь ту же длину, что и заменяемый им фрагмент.

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

3. remove() повышает ValueError, если x не найден в s.

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

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

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

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

Списки

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

class list([iterable])

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

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

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

• Использование списочного понимания: [x for x in iterable]

• Использование конструктора типов: list() или list(iterable).

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

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

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

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

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

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

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

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

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

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

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

Примеры сортировки и краткое руководство по сортировке смотрите в Техника сортировки.

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

Кортежи

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

class tuple([iterable])

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

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

• Использование запятой в конце для кортежа синглтонов: a, или (a,).

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

• С помощью встроенного tuple(): tuple() или tuple(iterable)

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

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

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

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

Диапазоны

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

class range(stop)

class range(start, stop[, step])

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

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

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

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

Диапазоны, содержащие абсолютные значения, превышающие sys.maxsize, разрешены, но некоторые характеристики (например, len()) могут привести к появлению OverflowError.

Примеры диапазонов:

>>> list(range(10))
[0, 1, 2, 3, 4, 5, 6, 7, 8, 9]
>>> list(range(1, 11))
[1, 2, 3, 4, 5, 6, 7, 8, 9, 10]
>>> list(range(0, 30, 5))
[0, 5, 10, 15, 20, 25]
>>> list(range(0, 10, 3))
[0, 3, 6, 9]
>>> list(range(0, -10, -1))
[0, -1, -2, -3, -4, -5, -6, -7, -8, -9]
>>> list(range(0))
[]
>>> list(range(1, 0))
[]

Диапазоны реализуют все операции с последовательностями common, кроме конкатенации и повторения (из-за того, что объекты диапазона могут представлять только последовательности, которые следуют строгому шаблону, а повторение и конкатенация обычно нарушают этот шаблон).

start

Значение параметра start (или 0, если параметр не был предоставлен)

stop

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

step

Значение параметра step (или 1, если параметр не был задан)

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

Объекты диапазона реализуют collections.abc.Sequence ABC и предоставляют такие возможности, как проверка на вместимость, поиск индекса элемента, нарезка и поддержка отрицательных индексов (см. Типы последовательностей — list, tuple, range):

>>> r = range(0, 20, 2)
>>> r
range(0, 20, 2)
>>> 11 in r
False
>>> 10 in r
True
>>> r.index(10)
5
>>> r[5]
10
>>> r[:5]
range(0, 10, 2)
>>> r[-1]
18

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

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

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

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

См.также

• В linspace recipe показано, как реализовать ленивую версию диапазона, подходящую для приложений с плавающей запятой.

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

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

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

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

• Тройное цитирование: '''Three single quotes''', """Three double quotes"""

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

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

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

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

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

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

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

class str(object='')

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

Возвращает string версию объекта. Если object не указан, возвращается пустая строка. В противном случае поведение str() зависит от того, задано ли кодирование или ошибки, как показано ниже.

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

Если задано хотя бы одно из encoding или errors, то object должен быть объектом bytes-like 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-струны и Синтаксис строки форматирования. Кроме того, см. раздел Услуги по обработке текста.

Строковые методы

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

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

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

str.capitalize()

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

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

str.casefold()

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

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

Алгоритм раскладывания по падежам - described in section 3.13 „Default Case Folding“ of the Unicode Standard.

Added in version 3.3.

str.center(width[, fillchar])

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

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

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

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

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

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

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

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

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

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

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

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

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

str.expandtabs(tabsize=8)

Возвращает копию строки, в которой все символы табуляции заменены одним или несколькими пробелами, в зависимости от текущего столбца и заданного размера табуляции. Позиции табуляции возникают через каждые tabsize символов (по умолчанию 8, что дает позиции табуляции в столбцах 0, 8, 16 и так далее). Чтобы расширить строку, текущий столбец устанавливается в ноль, и строка просматривается символ за символом. Если символ является табуляцией (\t), в результат вставляется один или несколько символов пробела до тех пор, пока текущий столбец не станет равным следующей позиции табуляции. (Если символ является новой строкой (\n) или возвратом (\r), то он копируется, а текущий столбец обнуляется. Любой другой символ копируется без изменений, а текущий столбец увеличивается на единицу, независимо от того, как этот символ будет представлен при печати.

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

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

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

Примечание

Метод find() следует использовать только в том случае, если вам нужно знать позицию sub. Чтобы проверить, является ли sub подстрокой или нет, используйте оператор in:

>>> 'Py' in 'Python'
True

str.format(*args, **kwargs)

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

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

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

Примечание

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

Изменено в версии 3.7: При форматировании числа с типом n функция в некоторых случаях временно устанавливает локаль LC_CTYPE на локаль LC_NUMERIC.

str.format_map(mapping, /)

Аналогично str.format(**mapping), за исключением того, что mapping используется напрямую, а не копируется в dict. Это полезно, если, например, mapping является подклассом dict:

>>> class Default(dict):
...     def __missing__(self, key):
...         return key
...
>>> '{name} was born in {country}'.format_map(Default(name='Guido'))
'Guido was born in country'

Added in version 3.2.

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

Аналогично find(), но повышает значение ValueError, если подстрока не найдена.

str.isalnum()

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

str.isalpha()

Возвращает True, если все символы в строке алфавитные и в ней есть хотя бы один символ, False в противном случае. Алфавитные символы - это символы, определенные в базе данных символов Unicode как «Letter», т. е. те, для которых свойство общей категории является одним из «Lm», «Lt», «Lu», «Ll» или «Lo». Обратите внимание, что это отличается от Alphabetic property defined in the section 4.10 „Letters, Alphabetic, and Ideographic“ of the Unicode Standard.

str.isascii()

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

Added in version 3.7.

str.isdecimal()

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

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 numeric value, например U+2155, VULGAR FRACTION ONE FIFTH. Формально числовыми считаются символы со значением свойства Numeric_Type=Digit, Numeric_Type=Decimal или Numeric_Type=Numeric.

str.isprintable()

Возвращает True, если все символы в строке являются печатными или строка пуста, False в противном случае. Непечатаемые символы - это символы, определенные в базе данных символов Unicode как «Other» или «Separator», за исключением ASCII-пробела (0x20), который считается печатаемым. (Обратите внимание, что печатаемые символы в данном контексте - это те, которые не должны экранироваться при вызове repr() в строке. Это никак не влияет на обработку строк, записанных в sys.stdout или sys.stderr).

str.isspace()

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

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

str.istitle()

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

str.isupper()

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

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

str.join(iterable)

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

str.ljust(width[, fillchar])

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

str.lower()

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

Используемый алгоритм перевода строчных букв - described in section 3.13 „Default Case Folding“ of the Unicode Standard.

str.lstrip([chars])

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

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

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

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

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

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

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

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

str.partition(sep)

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

str.removeprefix(prefix, /)

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

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

Added in version 3.9.

str.removesuffix(suffix, /)

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

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

Added in version 3.9.

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

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

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

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

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

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

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

str.rjust(width[, fillchar])

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

str.rpartition(sep)

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

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

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

str.rstrip([chars])

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

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

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

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

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

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

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

Например:

>>> '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, применяется другой алгоритм разбиения: последовательные пробельные символы рассматриваются как один разделитель, и результат не будет содержать пустых строк в начале или в конце, если в строке есть передние или задние пробельные символы. Следовательно, при разбиении пустой строки или строки, состоящей из одних пробельных символов, с разделителем None возвращается [].

Например:

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

str.splitlines(keepends=False)

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

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

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

Изменено в версии 3.2: В список границ линий добавлены \v и \f.

Например:

>>> 'ab c\n\nde fg\rkl\r\n'.splitlines()
['ab c', '', 'de fg', 'kl']
>>> 'ab c\n\nde fg\rkl\r\n'.splitlines(keepends=True)
['ab c\n', '\n', 'de fg\r', 'kl\r\n']

В отличие от split(), когда задается строка-разделитель sep, этот метод возвращает пустой список для пустой строки, и перевод строки в терминале не приводит к появлению дополнительной строки:

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

Для сравнения, split('\n') дает:

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

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

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

str.strip([chars])

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

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

Из строки вычеркиваются крайние ведущие и ведомые значения аргумента chars. Символы удаляются с ведущего конца до тех пор, пока не будет достигнут символ строки, не содержащийся в наборе символов chars. Аналогичные действия выполняются и в конце строки. Например:

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

str.swapcase()

Возвращает копию строки с символами верхнего регистра, преобразованными в нижний и наоборот. Обратите внимание, что не обязательно верно, что s.swapcase().swapcase() == s.

str.title()

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

Например:

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

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

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

Функция string.capwords() не имеет такой проблемы, поскольку разделяет слова только на пробелы.

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

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

str.translate(table)

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

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

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

str.upper()

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

Используемый алгоритм перевода в верхний регистр - described in section 3.13 „Default Case Folding“ of the Unicode Standard.

str.zfill(width)

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

Например:

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

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

Примечание

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

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

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

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

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

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)
'%'	Ни один аргумент не преобразуется, в результате в результатах появляется символ '%'.

Примечания:

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, который использует buffer protocol для доступа к памяти других двоичных объектов без необходимости создания копии.

Модуль array поддерживает эффективное хранение основных типов данных, таких как 32-битные целые числа и плавающие значения двойной точности IEEE754.

Байты Объекты

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

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

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

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

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

• Тройное цитирование: b'''3 single quotes''', b"""3 double quotes"""

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

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

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

Помимо буквальных форм, байт-объекты могут быть созданы и другими способами:

• Объект с нулевым заполнением байтов заданной длины: bytes(10)

• Из итерируемого множества целых чисел: bytes(range(20))

• Копирование существующих двоичных данных по буферному протоколу: bytes(obj)

Также смотрите встроенный bytes.

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

classmethod fromhex(string)

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

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

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

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

hex([sep[, bytes_per_sep]])

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

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

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

Added in version 3.5.

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

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

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

Объекты байтовых массивов

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

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

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

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

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

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

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

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

Также смотрите встроенный bytearray.

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

classmethod fromhex(string)

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

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

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

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

hex([sep[, bytes_per_sep]])

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

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

Added in version 3.5.

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

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

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

Операции с байтами и байтовыми массивами

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

Примечание

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

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

и:

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

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

Примечание

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

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

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

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

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

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

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

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

bytes.removeprefix(prefix, /)

bytearray.removeprefix(prefix, /)

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

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

В качестве префикса может выступать любой bytes-like object.

Примечание

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

Added in version 3.9.

bytes.removesuffix(suffix, /)

bytearray.removesuffix(suffix, /)

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

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

В качестве суффикса может выступать любой bytes-like object.

Примечание

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

Added in version 3.9.

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

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

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

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

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

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

Примечание

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

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

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

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

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

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

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

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

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

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

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

Примечание

Метод find() следует использовать только в том случае, если вам нужно знать позицию sub. Чтобы проверить, является ли sub подстрокой или нет, используйте оператор in:

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

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

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

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

Аналогично find(), но поднимает ValueError, если подпоследовательность не найдена.

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

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

bytes.join(iterable)

bytearray.join(iterable)

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

static bytes.maketrans(from, to)

static bytearray.maketrans(from, to)

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

Added in version 3.1.

bytes.partition(sep)

bytearray.partition(sep)

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

Разделителем для поиска может быть любой bytes-like object.

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

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

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

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

Примечание

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

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

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

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

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

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

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

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

Аналогично rfind(), но выводит ValueError, если подпоследовательность sub не найдена.

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

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

bytes.rpartition(sep)

bytearray.rpartition(sep)

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

Разделителем для поиска может быть любой bytes-like object.

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

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

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

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

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

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

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

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

Установите аргумент table в None для переводов, удаляющих только символы:

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

Изменено в версии 3.6: Теперь в качестве аргумента ключевого слова поддерживается delete.

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

bytes.center(width[, fillbyte])

bytearray.center(width[, fillbyte])

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

Примечание

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

bytes.ljust(width[, fillbyte])

bytearray.ljust(width[, fillbyte])

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

Примечание

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

bytes.lstrip([chars])

bytearray.lstrip([chars])

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

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

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

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

Примечание

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

bytes.rjust(width[, fillbyte])

bytearray.rjust(width[, fillbyte])

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

Примечание

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

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

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

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

bytes.rstrip([chars])

bytearray.rstrip([chars])

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

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

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

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

Примечание

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

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'1<>2<>3'.split(b'<>') возвращает [b'1', b'2', b'3']). Разделение пустой последовательности с указанным разделителем возвращает [b''] или [bytearray(b'')] в зависимости от типа разделяемого объекта. Аргумент sep может быть любым bytes-like object.

Например:

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

Если sep не указан или равен None, применяется другой алгоритм разбиения: последовательные пробельные символы ASCII рассматриваются как один разделитель, и результат не будет содержать пустых строк в начале или в конце, если последовательность имеет передние или задние пробельные символы. Следовательно, при разбиении пустой последовательности или последовательности, состоящей только из пробельных символов ASCII без указанного разделителя, возвращается [].

Например:

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

bytes.strip([chars])

bytearray.strip([chars])

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

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

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

Примечание

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

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

bytes.capitalize()

bytearray.capitalize()

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

Примечание

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

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'

Примечание

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

bytes.isalnum()

bytearray.isalnum()

Возвращает True, если все байты в последовательности являются алфавитными символами ASCII или десятичными цифрами ASCII и последовательность не пуста, False в противном случае. Алфавитные символы ASCII - это значения байтов в последовательности b'abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ'. Десятичные цифры ASCII - это значения байтов в последовательности b'0123456789'.

Например:

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

bytes.isalpha()

bytearray.isalpha()

Возвращает True, если все байты в последовательности являются алфавитными символами ASCII и последовательность не пуста, False в противном случае. Алфавитными символами ASCII считаются значения байтов в последовательности b'abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ'.

Например:

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

bytes.isascii()

bytearray.isascii()

Возвращает True, если последовательность пуста или все байты в последовательности являются ASCII, False в противном случае. Байты ASCII находятся в диапазоне 0-0x7F.

Added in version 3.7.

bytes.isdigit()

bytearray.isdigit()

Возвращает True, если все байты в последовательности являются десятичными цифрами ASCII и последовательность не пуста, False в противном случае. Десятичные цифры ASCII - это значения байтов в последовательности b'0123456789'.

Например:

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

bytes.islower()

bytearray.islower()

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

Например:

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

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

bytes.isspace()

bytearray.isspace()

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

bytes.istitle()

bytearray.istitle()

Возвращает True, если последовательность является заглавной буквой ASCII и последовательность не пуста, False в противном случае. Более подробную информацию об определении «заглавной буквы» см. в разделе bytes.title().

Например:

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

bytes.isupper()

bytearray.isupper()

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

Например:

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

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

bytes.lower()

bytearray.lower()

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

Например:

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

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

Примечание

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

bytes.splitlines(keepends=False)

bytearray.splitlines(keepends=False)

Возвращает список строк в двоичной последовательности с разбиением по границам ASCII-строк. Этот метод использует подход universal newlines для разбиения строк. Разрывы строк не включаются в результирующий список, если не задано значение keepends и оно не равно true.

Например:

>>> 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 преобразования регистра симметричны, хотя для произвольных кодовых точек Юникода это, как правило, не так.

Примечание

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

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

Примечание

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

bytes.upper()

bytearray.upper()

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

Например:

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

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

Примечание

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

bytes.zfill(width)

bytearray.zfill(width)

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

Например:

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

Примечание

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

Форматирование байтов в printf-стиле

Примечание

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

Объекты байтов (bytes/bytearray) имеют одну уникальную встроенную операцию: оператор % (modulo). Он также известен как оператор форматирования или интерполяции байтов. Учитывая format % values (где формат - объект байтов), спецификации преобразования % в формате заменяются нулем или несколькими элементами значений. Эффект аналогичен использованию sprintf() в языке C.

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

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

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'	Байты (любой объект, следующий за buffer protocol или имеющий __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.

Примечание

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

См.также

PEP 461 - Добавление форматирования % к байтам и байтовым массивам

Added in version 3.5.

Виды памяти

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

class memoryview(object)

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

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

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

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

Если базовый объект доступен для записи, просмотр памяти поддерживает одномерное назначение фрагментов. Изменение размера не допускается:

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

Одномерные представления памяти типа hashable (только для чтения) с форматами „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: Одномерные представления памяти теперь можно нарезать. Одномерные представления памяти с форматами „B“, „b“ или „c“ теперь hashable.

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

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

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

__eq__(exporter)

Представление памяти и экспортер 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

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

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

tobytes(order='C')

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

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

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

Added in version 3.8: order может быть {„C“, „F“, „A“}. Если order имеет значение „C“ или „F“, данные исходного массива преобразуются в порядок C или Fortran. Для смежных представлений „A“ возвращает точную копию физической памяти. В частности, сохраняется порядок Фортрана в памяти. Для несмежных представлений данные сначала преобразуются в C. order=None - то же самое, что и order=“C“.

hex([sep[, bytes_per_sep]])

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

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

Added in version 3.5.

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

tolist()

Возвращает данные в буфере в виде списка элементов.

>>> memoryview(b'abc').tolist()
[97, 98, 99]
>>> import array
>>> a = array.array('d', [1.1, 2.2, 3.3])
>>> m = memoryview(a)
>>> m.tolist()
[1.1, 2.2, 3.3]

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

toreadonly()

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

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

Added in version 3.8.

release()

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

После вызова этого метода любая дальнейшая операция над представлением вызывает ошибку 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

Added in version 3.2.

cast(format[, shape])

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

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

Приведение 1D/long к 1D/беззнаковым байтам:

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

Приведение байтов 1D/unsigned к 1D/char:

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

Приведение 1D/байтов к 3D/интов к 1D/signed char:

>>> import struct
>>> buf = struct.pack("i"*12, *list(range(12)))
>>> x = memoryview(buf)
>>> y = x.cast('i', shape=[2,2,3])
>>> y.tolist()
[[[0, 1, 2], [3, 4, 5]], [[6, 7, 8], [9, 10, 11]]]
>>> y.format
'i'
>>> y.itemsize
4
>>> len(y)
2
>>> y.nbytes
48
>>> z = y.cast('b')
>>> z.format
'b'
>>> z.itemsize
1
>>> len(z)
48
>>> z.nbytes
48

Перевести 1D/unsigned long в 2D/unsigned long:

>>> buf = struct.pack("L"*6, *list(range(6)))
>>> x = memoryview(buf)
>>> y = x.cast('L', shape=[2,3])
>>> len(y)
2
>>> y.nbytes
48
>>> y.tolist()
[[0, 1, 2], [3, 4, 5]]

Added in version 3.3.

Изменено в версии 3.5: Формат источника больше не ограничивается при приведении к байтовому представлению.

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

obj

Объект, лежащий в основе просмотра памяти:

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

Added in version 3.3.

nbytes

nbytes == product(shape) * itemsize == len(m.tobytes()). Это объем пространства в байтах, который массив занимал бы при непрерывном представлении. Оно не обязательно равно len(m):

>>> import array
>>> a = array.array('i', [1,2,3,4,5])
>>> m = memoryview(a)
>>> len(m)
5
>>> m.nbytes
20
>>> y = m[::2]
>>> len(y)
3
>>> y.nbytes
12
>>> len(y.tobytes())
12

Многомерные массивы:

>>> import struct
>>> buf = struct.pack("d"*12, *[1.5*x for x in range(12)])
>>> x = memoryview(buf)
>>> y = x.cast('d', shape=[3,4])
>>> y.tolist()
[[0.0, 1.5, 3.0, 4.5], [6.0, 7.5, 9.0, 10.5], [12.0, 13.5, 15.0, 16.5]]
>>> len(y)
3
>>> y.nbytes
96

Added in version 3.3.

readonly

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

format

Строка, содержащая формат (в стиле модуля struct) для каждого элемента в представлении. Представление памяти может быть создано из экспортеров с произвольными строками формата, но некоторые методы (например, tolist()) ограничены собственными форматами одного элемента.

Изменено в версии 3.3: Формат 'B' теперь обрабатывается в соответствии с синтаксисом модуля struct. Это означает, что memoryview(b'abc')[0] == b'abc'[0] == 97.

itemsize

Размер в байтах каждого элемента представления памяти:

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

Bool, указывающий, является ли данная память C-contiguous.

Added in version 3.3.

f_contiguous

bool, указывающий, является ли данная память фортрановской contiguous.

Added in version 3.3.

contiguous

Число bool, указывающее, является ли память contiguous.

Added in version 3.3.

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

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

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

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

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

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

class set([iterable])

class frozenset([iterable])

Возвращает новое множество или объект frozenset, элементы которого взяты из iterable. Элементы множества должны быть hashable. Для представления множеств множеств внутренние множества должны быть объектами 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.

isdisjoint(other)

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

issubset(other)

set <= other

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

set < other

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

issuperset(other)

set >= other

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

set > other

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

union(*others)

set | other | ...

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

intersection(*others)

set & other & ...

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

difference(*others)

set - other - ...

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

symmetric_difference(other)

set ^ other

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

copy()

Возвращает неглубокую копию набора.

Обратите внимание, что неоператорные версии методов union(), intersection(), difference(), symmetric_difference(), issubset() и issuperset() будут принимать в качестве аргумента любую итерируемую переменную. В отличие от них, их аналоги, основанные на операторах, требуют, чтобы их аргументы были множествами. Это исключает такие опасные для ошибок конструкции, как set('abc') & 'cbs', в пользу более читабельной set('abc').intersection('cbs').

И set, и frozenset поддерживают сравнение множества с множеством. Два множества равны тогда и только тогда, когда каждый элемент каждого из них содержится в другом (каждое из них является подмножеством другого). Множество меньше другого множества тогда и только тогда, когда первое множество является правильным подмножеством второго множества (является подмножеством, но не равно). Множество больше другого множества тогда и только тогда, когда первое множество является правильным супермножеством второго множества (является супермножеством, но не равно ему).

Экземпляры set сравниваются с экземплярами frozenset на основе их членов. Например, set('abc') == frozenset('abc') возвращает True и set('abc') in set([frozenset('abc')]) тоже.

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

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

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

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

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

update(*others)

set |= other | ...

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

intersection_update(*others)

set &= other & ...

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

difference_update(*others)

set -= other | ...

Обновите набор, удалив элементы, встречающиеся в других.

symmetric_difference_update(other)

set ^= other

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

add(elem)

Добавьте элемент elem в набор.

remove(elem)

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

discard(elem)

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

pop()

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

clear()

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

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

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

Типы отображения — dict

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

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

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

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

В качестве иллюстрации приведем следующие примеры, все из которых возвращают словарь, равный {"one": 1, "two": 2, "three": 3}:

>>> a = dict(one=1, two=2, three=3)
>>> b = {'one': 1, 'two': 2, 'three': 3}
>>> c = dict(zip(['one', 'two', 'three'], [1, 2, 3]))
>>> d = dict([('two', 2), ('one', 1), ('three', 3)])
>>> e = dict({'three': 3, 'one': 1, 'two': 2})
>>> f = dict({'one': 1, 'three': 3}, two=2)
>>> a == b == c == d == e == f
True

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

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

list(d)

Возвращает список всех ключей, используемых в словаре d.

len(d)

Возвращает количество элементов в словаре d.

d[key]

Возвращает элемент d с ключом key. Вызывает ошибку KeyError, если key нет в карте.

Если подкласс dict определяет метод __missing__(), а key отсутствует, операция d[key] вызывает этот метод с ключом key в качестве аргумента. Затем операция d[key] возвращает или поднимает то, что было возвращено или поднято вызовом __missing__(key). Никакие другие операции или методы не вызывают __missing__(). Если __missing__() не определен, вызывается KeyError. __missing__() должен быть методом; он не может быть переменной экземпляра:

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

В примере выше показана часть реализации collections.Counter. В collections.defaultdict используется другой метод __missing__.

d[key] = value

Установите d[key] на значение.

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 в качестве изменяемого объекта, например, пустого списка. Чтобы получить разные значения, используйте вместо этого dict comprehension.

get(key, default=None)

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

items()

Возвращает новое представление элементов словаря (пары``(key, value)``). Смотрите documentation of view objects.

keys()

Возвращает новое представление ключей словаря. Смотрите documentation of view objects.

pop(key[, default])

Если key есть в словаре, удалите его и верните его значение, иначе верните default. Если значение default не задано и key отсутствует в словаре, возникает ошибка KeyError.

popitem()

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

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

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

reversed(d)

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

Added in version 3.8.

setdefault(key, default=None)

Если key есть в словаре, верните его значение. Если нет, вставьте key со значением default и верните default. Значение default по умолчанию равно None.

update([other])

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

update() принимает либо другой объект словаря, либо итерабель пар ключ/значение (в виде кортежей или других итерабельных пар длины два). Если указаны аргументы в виде ключевых слов, то словарь обновляется этими парами ключ/значение: d.update(red=1, blue=2).

values()

Возвращает новое представление значений словаря. Смотрите documentation of view objects.

Сравнение на равенство одного представления dict.values() с другим всегда вернет False. Это также применимо при сравнении dict.values() с самим собой:

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

d | other

Создайте новый словарь с объединенными ключами и значениями d и other, которые оба должны быть словарями. Значения other имеют приоритет, если d и other имеют общие ключи.

Added in version 3.9.

d |= other

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

Added in version 3.9.

Словари сравниваются одинаково тогда и только тогда, когда в них есть одинаковые пары (key, value) (независимо от порядка). Сравнение по порядку („<“, „<=“, „>=“, „>“) приводит к увеличению TypeError.

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

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

Изменено в версии 3.7: Порядок в словаре гарантированно соответствует порядку вставки. Это поведение было деталью реализации CPython начиная с версии 3.6.

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

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

Изменено в версии 3.8: Словари теперь обратимы.

См.также

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

Объекты словарного представления

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

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

len(dictview)

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

iter(dictview)

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

Added in version 3.10.

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

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

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

>>> # iteration
>>> n = 0
>>> for val in values:
...     n += val
...
>>> print(n)
504

>>> # keys and values are iterated over in the same order (insertion order)
>>> list(keys)
['eggs', 'sausage', 'bacon', 'spam']
>>> list(values)
[2, 1, 1, 500]

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

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

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

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

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

contextmanager.__enter__()

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

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

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

contextmanager.__exit__(exc_type, exc_val, exc_tb)

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

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

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

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

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

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

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

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

Общий тип псевдонима

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

Примечание

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

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

Для контейнерного класса аргумент(ы), передаваемый(ые) в subscription класса, может(ут) указывать тип(ы) элементов, которые содержит объект. Например, 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 не обеспечивает соблюдение type annotations. Это распространяется на общие типы и их параметры типа. При создании объекта-контейнера из 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() на generic показывает параметризованный тип:

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

Однако такие выражения допустимы, если используется type variables. Индекс должен содержать столько элементов, сколько элементов переменной типа есть в GenericAlias объекта __args__:

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

Стандартные общие классы

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

• tuple

• list

• dict

• set

• frozenset

• type

• collections.deque

• collections.defaultdict

• collections.OrderedDict

• collections.Counter

• collections.ChainMap

• collections.abc.Awaitable

• collections.abc.Coroutine

• collections.abc.AsyncIterable

• collections.abc.AsyncIterator

• collections.abc.AsyncGenerator

• collections.abc.Iterable

• collections.abc.Iterator

• collections.abc.Generator

• collections.abc.Reversible

• collections.abc.Container

• collections.abc.Collection

• collections.abc.Callable

• collections.abc.Set

• collections.abc.MutableSet

• collections.abc.Mapping

• collections.abc.MutableMapping

• collections.abc.Sequence

• collections.abc.MutableSequence

• collections.abc.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__

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

Added in version 3.11.

См.также

PEP 484 - Тип Подсказки

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

PEP 585 - Подсказка типов в стандартных коллекциях

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

Дженерики, user-defined generics и typing.Generic.

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

Added in version 3.9.

Тип союза

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

• Необязательные типы могут быть записаны в виде союза с None:

  str | None == typing.Optional[str]
  

isinstance(obj, union_object)

issubclass(obj, union_object)

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

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

Однако parameterized generics в объектах объединения нельзя проверить:

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

Пользовательский тип для объекта объединения может быть доступен из types.UnionType и использоваться для проверок isinstance(). Объект не может быть инстанцирован из типа:

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

Примечание

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

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

См.также

PEP 604 – PEP, предлагающий синтаксис X | Y и тип Union.

Added in version 3.10.

Другие типы встраиваемых устройств

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

Модули

Единственной специальной операцией над модулем является доступ к атрибуту: m.name, где m - модуль, а name - имя, определенное в таблице символов m. Атрибуты модуля могут быть присвоены. (Обратите внимание, что оператор import, строго говоря, не является операцией над объектом модуля; import foo не требует существования объекта модуля с именем foo, скорее он требует наличия (внешнего) определения для модуля с именем foo).

Особым атрибутом каждого модуля является __dict__. Это словарь, содержащий таблицу символов модуля. Изменение этого словаря фактически изменит таблицу символов модуля, но прямое присвоение атрибуту __dict__ невозможно (вы можете написать m.__dict__['a'] = 1, который определяет m.a как 1, но не можете написать m.__dict__ = {}). Изменять __dict__ напрямую не рекомендуется.

Модули, встроенные в интерпретатор, записываются следующим образом: <module 'sys' (built-in)>. Если они загружены из файла, то записываются как <module 'os' from '/usr/local/lib/pythonX.Y/os.pyc'>.

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

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

Функции

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

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

Дополнительные сведения см. в разделе Определения функций.

Методы

Методы - это функции, которые вызываются с помощью нотации атрибутов. Существует два варианта: built-in methods (например, append() в списках) и class instance method. Встроенные методы описываются вместе с типами, которые их поддерживают.

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

Как и function objects, объекты связанных методов поддерживают получение произвольных атрибутов. Однако, поскольку атрибуты метода хранятся в базовом объекте функции (method.__func__), установка атрибутов метода в связанных методах запрещена. Попытка установить атрибут метода приводит к появлению сообщения AttributeError. Чтобы задать атрибут метода, необходимо явно задать его на базовом объекте функции:

>>> class C:
...     def method(self):
...         pass
...
>>> c = C()
>>> c.method.whoami = 'my name is method'  # can't set on the method
Traceback (most recent call last):
  File "<stdin>", line 1, in <module>
AttributeError: 'method' object has no attribute 'whoami'
>>> c.method.__func__.whoami = 'my name is method'
>>> c.method.whoami
'my name is method'

Дополнительные сведения см. в разделе Методы экземпляра.

Кодовые объекты

Объекты кода используются реализацией для представления «псевдокомпилированного» исполняемого кода Python, такого как тело функции. Они отличаются от объектов функций тем, что не содержат ссылки на свою глобальную среду выполнения. Объекты кода возвращаются встроенной функцией compile() и могут быть извлечены из объектов функций через их атрибут __code__. См. также модуль code.

Доступ к __code__ вызывает auditing event object.__getattr__ с аргументами obj и "__code__".

Объект кода можно выполнить или оценить, передав его (вместо исходной строки) встроенным функциям exec() или eval().

Дополнительные сведения см. в разделе Стандартная иерархия типов.

Типовые объекты

Объекты типа представляют различные типы объектов. Доступ к типу объекта осуществляется с помощью встроенной функции type(). Специальных операций над типами не существует. Стандартный модуль types определяет имена для всех стандартных встроенных типов.

Типы записываются следующим образом: <class 'int'>.

Нулевой объект

Этот объект возвращается функциями, которые явно не возвращают значение. Он не поддерживает никаких специальных операций. Существует ровно один объект null, называемый None (встроенное имя). При использовании type(None)() получается тот же самый синглтон.

Он записывается как None.

Объект Ellipsis

Этот объект обычно используется при нарезке (см. Нарезка). Он не поддерживает никаких специальных операций. Существует ровно один объект ellipsis с именем Ellipsis (встроенное имя). type(Ellipsis)() порождает синглтон Ellipsis.

Он записывается как Ellipsis или ....

Объект NotImplemented

Этот объект возвращается из сравнений и бинарных операций, когда им предлагается работать с типами, которые они не поддерживают. Более подробную информацию см. в разделе Сравнения. Существует ровно один объект NotImplemented. type(NotImplemented)() создает экземпляр singleton.

Он записывается как NotImplemented.

Внутренние объекты

Эту информацию см. в разделе Стандартная иерархия типов. Здесь описаны объекты stack frame objects, traceback objects и срезы.

Специальные атрибуты

Реализация добавляет несколько специальных атрибутов, доступных только для чтения, к нескольким типам объектов, где они уместны. Некоторые из них не сообщаются встроенной функцией dir().

object.__dict__

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

instance.__class__

Класс, к которому принадлежит экземпляр класса.

class.__bases__

Кортеж базовых классов объекта класса.

definition.__name__

Имя класса, функции, метода, дескриптора или экземпляра генератора.

definition.__qualname__

qualified name класса, функции, метода, дескриптора или экземпляра генератора.

Added in version 3.3.

definition.__type_params__

type parameters общих классов, функций и type aliases.

Added in version 3.12.

class.__mro__

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

class.mro()

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

class.__subclasses__()

Каждый класс хранит список слабых ссылок на свои непосредственные подклассы. Этот метод возвращает список всех этих ссылок, которые еще живы. Список приводится в порядке определения. Пример:

>>> int.__subclasses__()
[<class 'bool'>, <enum 'IntEnum'>, <flag 'IntFlag'>, <class 're._constants._NamedIntConstant'>]

class.__static_attributes__

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

Added in version 3.13.

Ограничение длины преобразования целочисленных строк

CPython имеет глобальное ограничение на преобразование между int и str для защиты от атак типа «отказ в обслуживании». Это ограничение только применяется к десятичной или другой системе счисления, не имеющей силы двух. Шестнадцатеричные, восьмеричные и двоичные преобразования неограниченны. Ограничение может быть настроено.

Тип int в CPython - это число произвольной длины, хранящееся в двоичной форме (обычно известной как «бигнум»). Не существует алгоритма, который мог бы преобразовать строку в двоичное целое число или двоичное целое число в строку за линейное время, если основание не является степенью 2. Даже самые известные алгоритмы для основания 10 имеют субквадратичную сложность. Преобразование большого значения, такого как int('1' * 500_000), может занять более секунды на быстром процессоре.

Ограничение размера конвертации - это практический способ избежать CVE-2020-10735.

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

Если операция превысит лимит, будет выдан сигнал ValueError:

>>> import sys
>>> sys.set_int_max_str_digits(4300)  # Illustrative, this is the default.
>>> _ = int('2' * 5432)
Traceback (most recent call last):
...
ValueError: Exceeds the limit (4300 digits) for integer string conversion: value has 5432 digits; use sys.set_int_max_str_digits() to increase the limit
>>> i = int('2' * 4300)
>>> len(str(i))
4300
>>> i_squared = i*i
>>> len(str(i_squared))
Traceback (most recent call last):
...
ValueError: Exceeds the limit (4300 digits) for integer string conversion; use sys.set_int_max_str_digits() to increase the limit
>>> len(hex(i_squared))
7144
>>> assert int(hex(i_squared), base=16) == i*i  # Hexadecimal is unlimited.

По умолчанию установлено ограничение в 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')
...

Added in version 3.11.

Затронутые 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.

Настройка ограничения

Перед запуском 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. Если установлены и env var, и параметр -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, который отключает его).

Added in version 3.11.

Осторожно

Установка низкого предела может привести к проблемам. Хотя это и редкость, существует код, содержащий в исходном тексте целочисленные константы в десятичной системе счисления, превышающие минимальный порог. Следствием установки ограничения является то, что исходный код Python, содержащий десятичные целочисленные литералы длиннее ограничения, столкнется с ошибкой при разборе, обычно во время запуска или импорта, или даже во время установки - в любое время, когда для кода еще не существует актуального .pyc. Обходным решением для исходных текстов, содержащих такие большие константы, является преобразование их в шестнадцатеричную форму 0x, поскольку она не имеет ограничений.

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

Рекомендуемая конфигурация

Ожидается, что значение по умолчанию 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)

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