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

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

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

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

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

4.1. Проверка истинности

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

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

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

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

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

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

4.2. Булевы операции – and, or, not

Это логические операции, упорядоченные по возрастанию приоритета:

Операция	Результат	Примечания
x or y	если x ложно, то y, иначе x	(1)
x and y	если x ложно, то x, иначе y	(2)
not x	если x ложно, то True, иначе False	(3)

Примечания:

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

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

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

4.3. Сравнения

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

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

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

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

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

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

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

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

4.4. Числовые типы – int, float, complex

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

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

Python полностью поддерживает смешанную арифметику: когда бинарный арифметический оператор имеет операнды разных числовых типов, операнд с «более узким» типом расширяется до типа другого операнда, где целое число уже, чем число с плавающей запятой, которое уже, чем комплексное число. Сравнения чисел смешанного типа следуют тому же правилу. 2 Конструкторы int(), float() и complex() могут использоваться для создания чисел определённого типа.

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

Операция	Результат	Примечания	Полная документация
x + y	сумма x и y
x - y	разность x и y
x * y	произведение x и y
x / y	частное x и y
x // y	частное с округлением вниз от x и y	(1)
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. Результат всегда округляется в сторону минус бесконечности: 1//2 равно 0, (-1)//2 равно -1, 1//(-2) равно -1, а (-1)//(-2) равно 0.

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

3. Преобразование числа с плавающей точкой в целое может округлять или усекать как в C; см. функции math.floor() и math.ceil() для однозначных преобразований.

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

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

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

   См. http://www.unicode.org/Public/9.0.0/ucd/extracted/DerivedNumericType.txt для полного списка кодовых точек со свойством Nd.

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

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

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

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

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

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

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

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

Примечания:

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

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

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

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

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

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

int.bit_length()¶

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

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

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

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

def bit_length(self):
    s = bin(self)       # двоичное представление:  bin(-37) --> '-0b100101'
    s = s.lstrip('-0b') # удалить ведущие нули и знак минуса
    return len(s)       # len('100101') --> 6

Новое в версии 3.1.

int.to_bytes(длина, порядок байтов, *, 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 байтов. Исключение OverflowError возбуждается, если целое число не может быть представлено заданным количеством байтов.

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

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

Новое в версии 3.2.

classmethod int.from_bytes(bytes, порядок байтов, *, signed=False)¶

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

>>> int.from_bytes(b'\x00\x10', byteorder='big')
16
>>> int.from_bytes(b'\x00\x10', byteorder='little')
4096
>>> int.from_bytes(b'\xfc\x00', byteorder='big', signed=True)
-1024
>>> int.from_bytes(b'\xfc\x00', byteorder='big', signed=False)
64512
>>> int.from_bytes([255, 0, 0], byteorder='big')
16711680

Аргумент bytes должен быть либо байтоподобным объектом, либо итерируемым объектом, порождающим байты.

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

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

Новое в версии 3.2.

4.4.3. Дополнительные методы для float

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

float.as_integer_ratio()¶

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

float.is_integer()¶

Возвращает True, если экземпляр float является конечным с целым значением, и False в противном случае:

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

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

float.hex()¶

Возвращает представление числа с плавающей запятой в виде шестнадцатеричной строки. Для конечных чисел с плавающей запятой это представление всегда будет включать ведущий 0x и завершающий p и экспоненту.

classmethod float.fromhex(s)¶

Метод класса для возврата числа с плавающей запятой, представленного шестнадцатеричной строкой s. Строка s может содержать начальные и конечные пробелы.

Обратите внимание, что float.hex() является методом экземпляра, в то время как float.fromhex() – метод класса.

Шестнадцатеричная строка имеет следующий вид:

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

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

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

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

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

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

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

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

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

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

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

• Если x = m / n – неотрицательное рациональное число и n делится на P (но m – нет), то n не имеет обратного по модулю P, и приведённое выше правило не применяется; в этом случае определите hash(x) как константу sys.hash_info.inf.

• Если x = m / n – отрицательное рациональное число, определите hash(x) как -hash(-x). Если полученный хеш равен -1, замените его на -2.

• Конкретные значения sys.hash_info.inf, -sys.hash_info.inf и sys.hash_info.nan используются как хеш-значения для положительной бесконечности, отрицательной бесконечности или nan (соответственно). (Все хешируемые nan имеют одинаковое хеш-значение.)

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

Чтобы прояснить приведённые выше правила, вот пример кода Python, эквивалентного встроенной функции hash, для вычисления хеша рационального числа, float или complex:

import sys, math

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

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

    """
    P = sys.hash_info.modulus
    # Удалить общие множители P. (Необязательно, если m и n уже взаимно просты.)
    while m % P == n % P == 0:
        m, n = m // P, n // P

    if n % P == 0:
        hash_value = sys.hash_info.inf
    else:
        # Малая теорема Ферма: pow(n, P-1, P) равно 1, поэтому
        # pow(n, P-2, P) даёт обратное к n по модулю P.
        hash_value = (abs(m) % P) * pow(n, P - 2, P) % P
    if m < 0:
        hash_value = -hash_value
    if hash_value == -1:
        hash_value = -2
    return hash_value

def hash_float(x):
    """Вычислить хеш числа с плавающей запятой x."""

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

def hash_complex(z):
    """Вычислить хеш комплексного числа z."""

    hash_value = hash_float(z.real) + sys.hash_info.imag * hash_float(z.imag)
    # выполнить знаковое приведение по модулю 2**sys.hash_info.width
    M = 2**(sys.hash_info.width - 1)
    hash_value = (hash_value & (M - 1)) - (hash_value & M)
    if hash_value == -1:
        hash_value = -2
    return hash_value

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

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

Чтобы объекты-контейнеры поддерживали итерацию, нужно определить один метод:

container.__iter__()¶

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

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

iterator.__iter__()¶

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

iterator.__next__()¶

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

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

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

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

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

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

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

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

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

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

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

Операция	Результат	Примечания
x in s	True, если элемент s равен x, иначе False	(1)
x not in s	False, если элемент s равен x, иначе True	(1)
s + t	конкатенация s и t	(6)(7)
s * n или n * s	эквивалентно сложению s с самим собой n раз	(2)(7)
s[i]	i-й элемент s, начиная с 0	(3)
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

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

Примечания:

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, или выполнить конкатенацию на месте с объектом bytearray. Объекты bytearray являются изменяемыми и имеют эффективный механизм предварительного выделения памяти

   • если конкатенируются объекты tuple, расширяйте list вместо этого

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

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

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

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

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

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

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

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

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

В таблице 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([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).

   Новое в версии 3.3: clear() и copy() методы.

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

4.6.4. Списки

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

class list([итерируемый объект])¶

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

4.6.5. Кортежи

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

class tuple([итерируемый объект])¶

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

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

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

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

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

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

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

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

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

4.6.6. Диапазоны

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

class range(stop)¶

classrange(start, stop[, step])

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

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

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

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

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

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

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

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

start¶

Значение параметра start (или 0, если параметр не был указан)

stop¶

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

step¶

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

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

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

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

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

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

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

Новое в версии 3.3: Атрибуты start, stop и step.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

class str(object='')¶

class str(объект=b'', кодировка='utf-8', ошибки='strict')

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

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

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

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

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

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

4.7.1. Методы строк

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

Строки также поддерживают два стиля форматирования: один предоставляет большую гибкость и настройку (см. str.format(), Format String Syntax и Custom String Formatting), а другой основан на C-стиле printf форматирования, который поддерживает более узкий диапазон типов и немного сложнее в правильном использовании, но часто быстрее для тех случаев, с которыми может работать (printf-style String Formatting).

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

str.capitalize()¶

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

str.casefold()¶

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

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

Алгоритм casefolding описан в разделе 3.13 стандарта Unicode.

Новое в версии 3.3.

str.center(width, fillcharfillchar])¶

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

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

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

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

Возвращает закодированную версию строки в виде объекта bytes. Кодировка по умолчанию – 'utf-8'. Параметр errors можно задать для указания другой схемы обработки ошибок. Значение по умолчанию для errors – 'strict', что означает, что ошибки кодирования вызывают исключение UnicodeError. Другие возможные значения: 'ignore', 'replace', 'xmlcharrefreplace', 'backslashreplace' и любое другое имя, зарегистрированное через codecs.register_error(); см. раздел Обработчики ошибок. Список возможных кодировок см. в разделе Стандартные кодировки.

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

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

Возвращает True, если строка заканчивается указанным suffix, в противном случае возвращает 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'

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

Примечание

При форматировании числа (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.6.5: При форматировании числа с типом n функция временно устанавливает локаль LC_CTYPE в локаль LC_NUMERIC в некоторых случаях.

str.format_map(mapping)¶

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

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

Новое в версии 3.2.

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

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

str.isalnum()¶

Return true if all characters in the string are alphanumeric and there is at least one character, false otherwise. A character c is alphanumeric if one of the following returns True: c.isalpha(), c.isdecimal(), c.isdigit(), or c.isnumeric().

str.isalpha()¶

Return true if all characters in the string are alphabetic and there is at least one character, false otherwise. Alphabetic characters are those characters defined in the Unicode character database as “Letter”, i.e., those with general category property being one of “Lm”, “Lt”, “Lu”, “Ll”, or “Lo”. Note that this is different from the “Alphabetic” property defined in the Unicode Standard.

str.isdecimal()¶

Return true if all characters in the string are decimal characters and there is at least one character, false otherwise. Decimal characters are those that can be used to form numbers in base 10, e.g. U+0660, ARABIC-INDIC DIGIT ZERO. Formally a decimal character is a character in the Unicode General Category “Nd”.

str.isdigit()¶

Return true if all characters in the string are digits and there is at least one character, false otherwise. Digits include decimal characters and digits that need special handling, such as the compatibility superscript digits. This covers digits which cannot be used to form numbers in base 10, like the Kharosthi numbers. Formally, a digit is a character that has the property value Numeric_Type=Digit or Numeric_Type=Decimal.

str.isidentifier()¶

Return true if the string is a valid identifier according to the language definition, section Identifiers and keywords.

Используйте keyword.iskeyword() для проверки зарезервированных идентификаторов, таких как def и class.

str.islower()¶

Return true if all cased characters 4 in the string are lowercase and there is at least one cased character, false otherwise.

str.isnumeric()¶

Return true if all characters in the string are numeric characters, and there is at least one character, false otherwise. Numeric characters include digit characters, and all characters that have the Unicode numeric value property, e.g. U+2155, VULGAR FRACTION ONE FIFTH. Formally, numeric characters are those with the property value Numeric_Type=Digit, Numeric_Type=Decimal or Numeric_Type=Numeric.

str.isprintable()¶

Return true if all characters in the string are printable or the string is empty, false otherwise. Nonprintable characters are those characters defined in the Unicode character database as “Other” or “Separator”, excepting the ASCII space (0x20) which is considered printable. (Note that printable characters in this context are those which should not be escaped when repr() is invoked on a string. It has no bearing on the handling of strings written to sys.stdout or sys.stderr.)

str.isspace()¶

Return true if there are only whitespace characters in the string and there is at least one character, false otherwise. Whitespace characters are those characters defined in the Unicode character database as “Other” or “Separator” and those with bidirectional property being one of “WS”, “B”, or “S”.

str.istitle()¶

Return true if the string is a titlecased string and there is at least one character, for example uppercase characters may only follow uncased characters and lowercase characters only cased ones. Return false otherwise.

str.isupper()¶

Return true if all cased characters 4 in the string are uppercase and there is at least one cased character, false otherwise.

str.join(итерируемый объект)¶

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

str.ljust(width[, fillchar])¶

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

str.lower()¶

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

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

str.lstrip([символы])¶

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

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

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

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

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

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

str.partition(sep)¶

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

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

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

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

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

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

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

str.rjust(width[, fillchar])¶

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

str.rpartition(sep)¶

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

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

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

str.rstrip([символы])¶

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

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

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

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

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

Представление	Описание
\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(префикс[, начало[, конец]])¶

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

str.strip([символы])¶

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

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

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

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

str.swapcase()¶

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

str.title()¶

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

Например:

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

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

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

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

>>> import re
>>> def titlecase(s):
...     return re.sub(r"[A-Za-z]+('[A-Za-z]+)?",
...                   lambda mo: mo.group(0)[0].upper() +
...                              mo.group(0)[1:].lower(),
...                   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).

Используемый алгоритм преобразования в верхний регистр описан в разделе 3.13 стандарта Unicode.

str.zfill(ширина)¶

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

Например:

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

4.7.2. printf-стиль форматирования строк

Примечание

Описанные здесь операции форматирования имеют ряд особенностей, которые приводят к множеству распространённых ошибок (например, неверному отображению кортежей и словарей). Использование более новых f-строк или интерфейса str.format() помогает избежать этих ошибок. Эти альтернативы также предоставляют более мощные, гибкие и расширяемые подходы к форматированию текста.

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

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

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

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

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

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

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

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

6. Модификатор длины (необязательно).

7. Тип преобразования.

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

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

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

Символы флагов преобразования:

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

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

Типы преобразования:

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

Примечания:

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.

4.8. Типы двоичных последовательностей – bytes, bytearray, memoryview

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

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

4.8.1. Объекты bytes

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

classbytes([источник[, кодировка[, ошибки]]])¶

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

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

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

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

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

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

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

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

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

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

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

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

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

classmethod fromhex(строка)¶

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

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

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

hex()¶

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

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

Новое в версии 3.5.

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

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

Примечание

Для пользователей Python 2.x: В серии Python 2.x допускались различные неявные преобразования между 8-битными строками (ближайшим аналогом встроенного бинарного типа данных в 2.x) и строками Unicode. Это был временный обходной путь для обратной совместимости, учитывающий, что изначально Python поддерживал только 8-битный текст, а текст Unicode был добавлен позже. В Python 3.x такие неявные преобразования отсутствуют – преобразования между 8-битными бинарными данными и текстом Unicode должны быть явными, и объекты bytes и string всегда будут неравны при сравнении.

4.8.2. Объекты bytearray

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

classbytearray([источник[, кодировка[, ошибки]]])¶

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

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

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

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

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

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

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

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

classmethod fromhex(строка)¶

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

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

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

hex()¶

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

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

Новое в версии 3.5.

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

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

4.8.3. Операции с bytes и bytearray

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

Примечание

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

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

и:

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

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

Примечание

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

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

bytes.count(подстрока[, начало[, конец]])¶

bytearray.count(подстрока[, начало[, конец]])¶

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

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

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

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

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

Возвращает строку, декодированную из заданных байтов. Кодировка по умолчанию – 'utf-8'. Параметр errors можно задать для указания другой схемы обработки ошибок. Значение по умолчанию для errors – 'strict', то есть ошибки кодирования вызывают исключение UnicodeError. Другие возможные значения: 'ignore', 'replace' и любое другое имя, зарегистрированное через codecs.register_error(); см. раздел Обработчики ошибок. Список возможных кодировок приведен в разделе Стандартные кодировки.

Примечание

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

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

bytes.endswith(суффикс[, начало[, конец]])¶

bytearray.endswith(суффикс[, начало[, конец]])¶

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

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

bytes.find(подстрока[, начало[, конец]])¶

bytearray.find(подстрока[, начало[, конец]])¶

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

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

Примечание

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

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

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

bytes.index(подстрока[, начало[, конец]])¶

bytearray.index(подстрока[, начало[, конец]])¶

Как find(), но возбуждает ValueError, когда подпоследовательность не найдена.

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

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

bytes.join(итерируемый объект)¶

bytearray.join(итерируемый объект)¶

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

static bytes.maketrans(от, до)¶

static bytearray.maketrans(от, до)¶

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

Новое в версии 3.1.

bytes.partition(разделитель)¶

bytearray.partition(разделитель)¶

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

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

bytes.replace(старый, новый[, количество])¶

bytearray.replace(старый, новый[, количество])¶

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

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

Примечание

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

bytes.rfind(подстрока[, начало[, конец]])¶

bytearray.rfind(подстрока[, начало[, конец]])¶

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

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

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

bytes.rindex(подстрока[, начало[, конец]])¶

bytearray.rindex(подстрока[, начало[, конец]])¶

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

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

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

bytes.rpartition(разделитель)¶

bytearray.rpartition(разделитель)¶

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

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

bytes.startswith(префикс[, начало[, конец]])¶

bytearray.startswith(префикс[, начало[, конец]])¶

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

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

bytes.translate(таблица, delete=b'')¶

bytearray.translate(таблица, delete=b'')¶

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

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

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

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

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

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

bytes.center(ширина[, fillbyte])¶

bytearray.center(ширина[, fillbyte])¶

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

Примечание

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

bytes.ljust(ширина[, fillbyte])¶

bytearray.ljust(ширина[, fillbyte])¶

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

Примечание

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

bytes.lstrip([символы])¶

bytearray.lstrip([символы])¶

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

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

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

Примечание

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

bytes.rjust(ширина[, fillbyte])¶

bytearray.rjust(ширина[, fillbyte])¶

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

Примечание

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

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

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

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

bytes.rstrip([символы])¶

bytearray.rstrip([символы])¶

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

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

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

Примечание

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

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

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

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

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

Например:

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

Если 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([символы])¶

bytearray.strip([символы])¶

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

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

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

Примечание

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

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

bytes.capitalize()¶

bytearray.capitalize()¶

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

Примечание

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

bytes.expandtabs(tabsize=8)¶

bytearray.expandtabs(tabsize=8)¶

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

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

Примечание

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

bytes.isalnum()¶

bytearray.isalnum()¶

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

Например:

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

bytes.isalpha()¶

bytearray.isalpha()¶

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

Например:

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

bytes.isdigit()¶

bytearray.isdigit()¶

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

Например:

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

bytes.islower()¶

bytearray.islower()¶

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

Например:

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

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

bytes.isspace()¶

bytearray.isspace()¶

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

bytes.istitle()¶

bytearray.istitle()¶

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

Например:

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

bytes.isupper()¶

bytearray.isupper()¶

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

Например:

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

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

bytes.lower()¶

bytearray.lower()¶

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

Например:

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

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

Примечание

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

bytes.splitlines(keepends=False)¶

bytearray.splitlines(keepends=False)¶

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

Например:

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

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

>>> b"".split(b'\n'), b"Two lines\n".split(b'\n')
([b''], [b'Two lines', b''])
>>> b"".splitlines(), b"One line\n".splitlines()
([], [b'One line'])

bytes.swapcase()¶

bytearray.swapcase()¶

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

Например:

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

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

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

Примечание

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

bytes.title()¶

bytearray.title()¶

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

Например:

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

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

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

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

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

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

Примечание

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

bytes.upper()¶

bytearray.upper()¶

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

Например:

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

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

Примечание

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

bytes.zfill(ширина)¶

bytearray.zfill(ширина)¶

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

Например:

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

Примечание

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

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

Примечание

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

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

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

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

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

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

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

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

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

6. Модификатор длины (необязательно).

7. Тип преобразования.

Если правый аргумент является словарём (или другим отображающим типом), то форматы в объекте bytes должны включать ключ отображения в скобках, вставленный сразу после символа '%'. Ключ отображения выбирает значение для форматирования из отображения. Например:

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

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

Символы флагов преобразования:

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

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

Типы преобразования:

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

Примечания:

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

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

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

   Точность определяет количество цифр после десятичной точки; по умолчанию равна 6.

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

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

5. Если точность равна N, вывод усекается до N символов.

6. b'%s' устарело, но не будет удалено в рамках серии 3.x.

7. b'%r' устарело, но не будет удалено в рамках серии 3.x.

8. См. PEP 237.

Примечание

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

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

PEP 461 – Добавление %-форматирования для bytes и bytearray

Новое в версии 3.5.

4.8.5. Представления памяти

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

classmemoryview(obj)¶

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

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

len(view) равен длине tolist. Если view.ndim = 0, длина равна 1. Если view.ndim = 1, длина равна количеству элементов в представлении. Для более высоких размерностей, длина равна длине вложенного списка, представляющего представление. Атрибут itemsize возвращает количество байтов в одном элементе.

memoryview поддерживает срезы и индексацию для доступа к своим данным. Одномерное срезание даёт подпредставление:

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

Если format является одним из собственных спецификаторов формата из модуля struct, также поддерживается индексация целым числом или кортежем целых чисел, которая возвращает один элемент правильного типа. Одномерные memoryviews можно индексировать целым числом или кортежем из одного целого числа. Многомерные memoryviews можно индексировать кортежами из ровно ndim целых чисел, где ndim – это количество измерений. Нулевые memoryviews можно индексировать пустым кортежем.

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

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

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

>>> data = bytearray(b'abcefg')
>>> v = memoryview(data)
>>> v.readonly
False
>>> v[0] = ord(b'z')
>>> data
bytearray(b'zbcefg')
>>> v[1:4] = b'123'
>>> data
bytearray(b'z123fg')
>>> v[2:3] = b'spam'
Traceback (most recent call last):
  File "<stdin>", line 1, in <module>
ValueError: memoryview assignment: lvalue and rvalue have different structures
>>> v[2:6] = b'spam'
>>> data
bytearray(b'z1spam')

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

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

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

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

__eq__(экспортёр)¶

memoryview и экспортёр PEP 3118 равны, если их формы эквивалентны и все соответствующие значения равны при интерпретации кодов формата операндов с использованием синтаксиса struct.

Для подмножества строк формата struct, поддерживаемых в настоящее время tolist(), v и w равны, если v.tolist() == w.tolist():

>>> import array
>>> a = array.array('I', [1, 2, 3, 4, 5])
>>> b = array.array('d', [1.0, 2.0, 3.0, 4.0, 5.0])
>>> c = array.array('b', [5, 3, 1])
>>> x = memoryview(a)
>>> y = memoryview(b)
>>> x == a == y == b
True
>>> x.tolist() == a.tolist() == y.tolist() == b.tolist()
True
>>> z = y[::-2]
>>> z == c
True
>>> z.tolist() == c.tolist()
True

Если хотя бы одна из строк формата не поддерживается модулем struct, то объекты всегда будут сравниваться как неравные (даже если строки формата и содержимое буфера идентичны):

>>> from ctypes import BigEndianStructure, c_long
>>> class BEPoint(BigEndianStructure):
...     _fields_ = [("x", c_long), ("y", c_long)]
...
>>> point = BEPoint(100, 200)
>>> a = memoryview(point)
>>> b = memoryview(point)
>>> a == point
False
>>> a == b
False

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

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

tobytes()¶

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

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

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

hex()¶

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

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

Новое в версии 3.5.

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, а также многомерные представления.

release()¶

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

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

>>> m = memoryview(b'abc')
>>> m.release()
>>> m[0]
Traceback (most recent call last):
  File "<stdin>", line 1, in <module>
ValueError: operation forbidden on released memoryview object

Протокол менеджера контекста можно использовать для аналогичного эффекта с помощью оператора with:

>>> with memoryview(b'abc') as m:
...     m[0]
...
97
>>> m[0]
Traceback (most recent call last):
  File "<stdin>", line 1, in <module>
ValueError: operation forbidden on released memoryview object

Новое в версии 3.2.

cast(формат[, форма])¶

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

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

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

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

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

>>> b = bytearray(b'zyz')
>>> x = memoryview(b)
>>> x[0] = b'a'
Traceback (most recent call last):
  File "<stdin>", line 1, in <module>
ValueError: memoryview: invalid value for format "B"
>>> y = x.cast('c')
>>> y[0] = b'a'
>>> b
bytearray(b'ayz')

Преобразование 1D/bytes в 3D/ints в 1D/signed char:

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

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

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

Новое в версии 3.3.

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

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

obj¶

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

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

Новое в версии 3.3.

nbytes¶

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

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

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

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

Новое в версии 3.3.

readonly¶

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

format¶

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

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

itemsize¶

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

>>> import array, struct
>>> m = memoryview(array.array('H', [32000, 32001, 32002]))
>>> m.itemsize
2
>>> m[0]
32000
>>> struct.calcsize('H') == m.itemsize
True

ndim¶

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

shape¶

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

Изменено в версии 3.3: Пустой кортеж вместо None, когда ndim = 0.

strides¶

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

Изменено в версии 3.3: Пустой кортеж вместо None, когда ndim = 0.

suboffsets¶

Используется внутренне для массивов в стиле PIL. Значение носит только информационный характер.

c_contiguous¶

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

Новое в версии 3.3.

f_contiguous¶

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

Новое в версии 3.3.

contiguous¶

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

Новое в версии 3.3.

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

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

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

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

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

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

class set([итерируемый объект])¶

class frozenset([итерируемый объект])¶

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

Экземпляры set и frozenset предоставляют следующие операции:

len(s)

Возвращает количество элементов в множестве s (мощность s).

x in s

Проверяет принадлежность x множеству s.

x not in s

Проверяет отсутствие x в s.

isdisjoint(другой)¶

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

issubset(другой)¶

set <= other

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

set < other

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

issuperset(другой)¶

set >= other

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

set > other

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

union(*другие)¶

set | other | ...

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

intersection(*другие)¶

set & other & ...

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

difference(*другие)¶

set - other - ...

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

symmetric_difference(другой)¶

set ^ other

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

copy()¶

Возвращает новое множество с поверхностной копией s.

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

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

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

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

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

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

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

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

update(*другие)¶

set |= other | ...

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

intersection_update(*другие)¶

set &= other & ...

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

difference_update(*другие)¶

set -= other | ...

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

symmetric_difference_update(другой)¶

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.

4.10. Типы отображений – dict

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

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

Словари можно создать, разместив разделённый запятыми список пар key: value pairs within braces, for example: {'jack': 4098, 'sjoerd': 4127} or {4098: 'jack', 4127: 'sjoerd'}, or by the dict constructor.

class dict(**kwarg)¶

classdict(отображение, **kwarg)

classdict(итерируемый объект, **kwarg)

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

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

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

Для иллюстрации: следующие примеры возвращают словарь, равный {"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})
>>> a == b == c == d == e
True

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

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

len(d)

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

d[key]

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

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

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

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

d[key] = value

Устанавливает d[key] в value.

del d[key]

Удаляет d[key] из d. Возбуждает KeyError, если key отсутствует в отображении.

key in d

Возвращает True, если d содержит ключ key, иначе False.

key not in d

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

iter(d)

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

clear()¶

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

copy()¶

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

classmethod fromkeys(seq[, value])¶

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

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

get(key[, default])¶

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

items()¶

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

keys()¶

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

pop(key[, default])¶

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

popitem()¶

Удаляет и возвращает произвольную пару (key, value) из словаря.

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

setdefault(key[, default])¶

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

update([другое])¶

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

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

values()¶

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

Словари считаются равными тогда и только тогда, когда они содержат одни и те же пары (key, value). Операции сравнения порядка (‘<’, ‘<=’, ‘>=’, ‘>’) вызывают TypeError.

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

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

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

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

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

len(dictview)

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

iter(dictview)

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

Ключи и значения перебираются в произвольном порядке, который не является случайным, различается в разных реализациях Python и зависит от истории вставок и удалений в словаре. Если представления ключей, значений и элементов перебираются без промежуточных изменений словаря, порядок элементов будет напрямую соответствовать. Это позволяет создавать пары (value, key) с помощью zip(): pairs = zip(d.values(), d.keys()). Другой способ создать тот же список – pairs = [(v, k) for (k, v) in d.items()].

Итерация по представлениям во время добавления или удаления записей в словаре может вызвать RuntimeError или не охватить все записи.

x in dictview

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

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

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

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

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

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

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

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

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

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

contextmanager.__enter__()¶

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

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

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

contextmanager.__exit__(exc_type, exc_val, exc_tb)¶

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

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

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

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

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

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

4.12. Другие встроенные типы

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

4.12.1. Модули

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

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

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

4.12.3. Функции

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

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

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

4.12.4. Методы

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

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

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

>>> class C:
...     def method(self):
...         pass
...
>>> c = C()
>>> c.method.whoami = 'my name is method'  # нельзя установить на методе
Traceback (most recent call last):
  File "<stdin>", line 1, in <module>
AttributeError: 'method' object has no attribute 'whoami'
>>> c.method.__func__.whoami = 'my name is method'
>>> c.method.whoami
'my name is method'

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

4.12.5. Объекты кода

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

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

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

4.12.6. Объекты типов

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

Типы записываются так: <class 'int'>.

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

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

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

4.12.8. Объект Ellipsis

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

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

4.12.9. Объект NotImplemented

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

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

4.12.10. Булевы значения

Булевы значения – это два константных объекта False и True. Они используются для представления истинностных значений (хотя другие значения также могут считаться ложными или истинными). В числовых контекстах (например, при использовании в качестве аргумента арифметического оператора) они ведут себя как целые числа 0 и 1 соответственно. Встроенная функция bool() может использоваться для преобразования любого значения в булево, если значение можно интерпретировать как истинностное (см. раздел Проверка истинности выше).

Они записываются как False и True соответственно.

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

См. Стандартная иерархия типов для получения этой информации. В ней описаны объекты стековых фреймов, объекты трассировки и объекты срезов.

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

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

object.__dict__¶

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

instance.__class__¶

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

class.__bases__¶

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

definition.__name__¶

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

definition.__qualname__¶

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

Новое в версии 3.3.

class.__mro__¶

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

class.mro()¶

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

class.__subclasses__()¶

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

>>> int.__subclasses__()
[<class 'bool'>]

Сноски

1

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

2

Как следствие, список [1, 2] считается равным [1.0, 2.0], и аналогично для кортежей.

3

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

4(1,2,3,4)

Символы, имеющие регистр, – это те, у которых общее свойство категории является одним из «Lu» (буква прописная), «Ll» (буква строчная) или «Lt» (буква заглавная).

5(1,2)

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