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

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

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

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

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

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

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

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

константы, определяемые как ложные: None и False.
ноль любого числового типа: 0, 0.0, 0j, Decimal(0), Fraction(0, 1)
пустые последовательности и коллекции: '', (), [], {}, set(), range(0)

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

Логические операции — `and`, `or`, `not`¶

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

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

Примечания:

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

Сравнения¶

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Операция	Результат	Примечания	Полная документация
`x + y`	сумма x и y
`x - y`	разница x и y
`x * y`	умножение x и y
`x / y`	частное от x и y
`x // y`	целочисленное частное x и y	(1)
`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)`	х в степени у	(5)	`pow()`
`x ** y`	х в степени у	(5)

Примечания:

Также называется целочисленным делением. Результирующее значение — целое число, хотя тип результата необязательно должен быть int. Результат всегда округляется до минус бесконечности: 1//2 — это 0, (-1)//2 — это -1, 1//(-2) — это -1, а (-1)//(-2) — это 0.
Не для комплексных чисел. Вместо этого конвертируйте в числа с плавающей запятой, используя abs(), если это необходимо.
Преобразование из числа с плавающей запятой в целое число может округляться или усекаться, как в C; см. функции math.floor() и math.ceil() для чётко определенных преобразований.
float также принимает строки «nan» и «inf» с необязательным префиксом «+» или «-» для Not a Number (NaN) и положительной или отрицательной бесконечности.
Python определяет pow(0, 0) и 0 ** 0 как 1, что является обычным для языков программирования.
Допустимые числовые литералы включают цифры от 0 до 9 или любой Юникод эквивалент (кодовые точки со свойством Nd).

См. стандарт для получения полного списка кодовых точек со свойством Nd.

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

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

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

Побитовые операции с целыми типами¶

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

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

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

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

Примечания:

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

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

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

int.bit_length()¶

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

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

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

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

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

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

int.to_bytes(length, byteorder, *, 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, byteorder, *, 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.

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

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

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

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

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

float.is_integer()¶

Возвращает True, если экземпляр с плавающей запятой является конечным с целым значением, и 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, а шестнадцатеричные строки, созданные символом формата C %a или Double.toHexString Java, принимаются float.fromhex().

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

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

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

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

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

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

Детали реализации CPython: В настоящее время основной используется P = 2**31 - 1 на машинах с 32-разрядной C-длиной и P = 2**61 - 1 на машинах с 64-разрядной 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, эквивалентного встроенному хешу, для вычисления хеша рационального числа float или complex

import sys, math

def hash_fraction(m, n):
    """Вычислить хеш рационального числа m/n.

    Предполагает, что m и n являются целыми числами, с положительной n.
    Эквивалентно  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):
    """Вычислить хэш float 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

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

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

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

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

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

iterator.__iter__()¶: Возвращает сам объект итератора. Это необходимо для использования контейнеров и итераторов с операторами for и in. Метод соответствует слоту tp_iter структуры типов для объектов Python в API Python/C.

iterator.__next__()¶: Возвращает следующий элемент из контейнера. Если других элементов нет, вызовет исключение StopIteration. Метод соответствует слоту tp_iternext структуры типов для объектов Python в API Python/C.

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

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

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

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

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

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

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

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

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

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

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

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

Примечания:

В то время как операции in и not in используются только для простой проверки наличия в общем случае, некоторые специализированные последовательности (например, str, bytes и bytearray) также используют их для тестирования подпоследовательностей
```
>>> "gg" in "eggs"
True
```
Значения 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]]
```
Дополнительное объяснение доступно в разделе часто задаваемых вопросов Как создать многомерный список?.
Если i или j отрицательны, индекс относится к концу последовательности s: заменяется len(s) + i или len(s) + j. Но обратите внимание, что -0 по-прежнему 0.
Нарезка s от i до j определяется как последовательность элементов с индексом k, таким как i <= k < j. Если i или j больше len(s), используйте len(s). Если i пропущен или None, используйте 0. Если j не указан или None, используйте len(s). Если i больше или равно j, нарезка пуста.
Нарезка 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.
Объединение неизменяемых последовательностей всегда приводит к новому объекту. Это означает, что создание последовательности путём повторной конкатенации будет с квадратичными затратами времени выполнения от общей длины последовательности. Чтобы получить линейную стоимость времени выполнения, вы должны переключиться на одну из альтернатив, приведенных ниже:
- при объединении объектов str вы можете создать список и использовать str.join() в конце или записать в экземпляр io.StringIO и получить его значение по завершении
- при объединении объектов bytes можно аналогичным образом использовать bytes.join() или io.BytesIO или выполнить объединение на месте с объектом bytearray. Объекты bytearray являются изменяемыми и содержат эффективный механизм превышения доступности
- при объединении объектов tuple, вместо этого расширьте list
- для других типов изучите соответствующую документацию класса
Некоторые типы последовательностей (например, range) поддерживают только последовательности элементов, которые следуют определенным шаблонам, и, следовательно, не поддерживают конкатенацию или повторение последовательностей.
index вызывает ValueError, если x не находится в s. Не все реализации поддерживают передачу дополнительных аргументов i и j. Эти аргументы позволяют эффективно искать части последовательности. Передача дополнительных аргументов примерно эквивалентна использованию s[i:j].index(x), только без копирования каких-либо данных и с возвращаемым индексом, относящимся к началу последовательности, а не к началу нарезки.

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

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

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

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

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

Операции в следующей таблице определены для изменяемых типов последовательностей. 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)

Примечания:

У t должна быть та же длина, что и заменяемая нарезка.
Необязательный аргумент i по умолчанию равен -1, так что по умолчанию последний элемент удаляется и возвращается.
remove() вызывает ValueError, если x не находится в s.
Метод reverse() изменяет существующую последовательность для экономии места при обращении большой последовательности. Чтобы напомнить пользователям, что он работает как побочный эффект, он не возвращает обратную последовательность.
clear() и copy() включены для согласованности с интерфейсами изменяемых контейнеров, которые не поддерживают операции нарезки (например, dict и set). copy() не является частью collections.abc.MutableSequence ABC, но большинство классов изменяемых последовательностей предоставляют его.

Добавлено в версии 3.3: Методы clear() и copy().
Значение n является целым числом или объектом, реализующим __index__(). Нулевые и отрицательные значения n очищают последовательность. Элементы в последовательности не копируются; на них ссылаются несколько раз, как описано для s * n в разделе Общие последовательные операции.

Списки¶

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

class list([iterable])¶

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

Использование пары квадратных скобок для обозначения пустого списка: []
Использование квадратных скобок, разделяя элементы запятыми: [a], [a, b, c]
Использование списковых включений (list comprehension): [x for x in iterable]
Использование конструктора типов: list() or list(iterable)

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

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

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

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

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

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

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

Кортежи¶

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

class tuple([iterable])¶

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

Использование пары круглых скобок для обозначения пустого кортежа: ()
Использование завершающей запятой для одноэлементного кортежа: a, или (a,)
Разделение элементов запятыми: a, b, c или (a, b, c)
Использование встроенного tuple(): tuple() или tuple(iterable)

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

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

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

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

Диапазоны¶

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

class range(stop)¶

class range(start, stop[, step])

Аргументы конструктора диапазона должны быть целыми числами (либо встроенным 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.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

См.также

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

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

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

Одинарные кавычки: '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(object=b'', encoding='utf-8', errors='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 и Строковые методы ниже. Чтобы вывести форматированные строки, см. разделы Форматированные строковые литералы и Синтаксис строки формата. Кроме того, см. раздел Службы по обработке текста.

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

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

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

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

str.capitalize()¶: Возвращает копию строки, в которой первый символ будет заглавной, а остальные — строчными.

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

str.casefold()¶

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

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

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

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

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

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

str.encode(encoding="utf-8", errors="strict")¶: Возвращает закодированную версию строки как байтовый объект. Кодировка по умолчанию — '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. Позиции табуляции появляются для каждого символа 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)¶

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

>>> "Сумма 1 + 2 = {0}".format(1+2)
'Сумма 1 + 2 = 3'

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

Примечание

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

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

str.format_map(mapping)¶

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

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

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

str.index(sub[, start[, end]])¶: Аналогично find(), но вызывает ValueError, когда подстрока не найдена.

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

str.isalpha()¶: Возвращает True, если все символы в строке буквенные и если хотя бы один символ не является им, то False. Буквенные символы — это символы, определённые в базе данных Юникод символов как «Letter», т. е. те, у которых общее свойство категории является одним из «Lm», «Lt», «Lu», «Ll» или «Lo». Обратите внимание, что это отличается от свойства «Alphabetic», определенного в стандарте Юникод.

str.isascii()¶: Возвращает True, если строка пуста или все символы в строке ASCII, в противном случае — False. У символов ASCII кодовые точки в диапазоне U+0000-U+007F.

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

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

str.isdigit()¶: Возвращает True, если все символы в строке являются цифрами, в противном случае False. Цифры включают десятичные символы и цифры, требующие особой обработки, например цифры надстрочного индекса совместимости. Это касается цифр, которые нельзя использовать для образования чисел с основанием 10, например числа Харости (Kharosthi). Формально цифра — это символ, у которого значение свойства Numeric_Type=Digit или Numeric_Type=Decimal.

str.isidentifier()¶

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

Вызвать keyword.iskeyword(), чтобы проверить, является ли строка s зарезервированным идентификатором, например def и class.

Пример:

>>> from keyword import iskeyword

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

str.islower()¶: Возвращает True, если все символы регистра [4] в строке строчные, в противном случае — False.

str.isnumeric()¶: Возвращает True, если все символы в строке являются числовыми символами, в противном случае — False. Числовые символы включают символы цифр и все символы, у которых свойство числового значения Юникод, например U+2155, VULGAR FRACTION ONE FIFTH. Формально числовые символы — это символы со значением свойства Numeric_Type=Digit, Numeric_Type=Decimal или Numeric_Type=Numeric.

str.isprintable()¶: Возвращает True, если все символы в строке печатаются или являются пустой строкой, в противном случае — False. Непечатаемые символы — это символы, определённые в базе данных символов Юникод как «Other» или «Separator», за исключением пробела ASCII (0x20), который считается печатаемым. (Обратите внимание, что печатаемые символы в этом контексте — это те, которые не следует экранировать при вызове repr() в строке. Это не имеет никакого отношения к обработке строк, записанных в sys.stdout или sys.stderr.)

str.isspace()¶

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

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

str.istitle()¶: Вернёт True, если в строке есть хотя бы один символ и все «слова» в строке начинаются с заглавных букв, иначе — False.

str.isupper()¶: Возвращает True, если все символы в [4] строке прописные, в противном случае — False.

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

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

str.lower()¶

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

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

str.lstrip([chars])¶

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

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

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

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

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

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

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

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 и вернуть кортеж из трёх частей, содержащий часть перед разделителем, сам разделитель и часть после разделителя. Если разделитель не найден, вернуть 3-кортеж, содержащий две пустые строки, за которыми следует сама строка.

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

str.rstrip([chars])¶

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

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

str.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 не задано и ложно.

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

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

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

Например:

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

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

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

Для сравнения split('\n') возвращает:

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

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

str.strip([chars])¶

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

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

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

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

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

str.title()¶

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

Например:

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

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

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

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

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

str.translate(table)¶

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

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

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

str.upper()¶

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

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

str.zfill(width)¶

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

Например:

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

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

Примечание

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

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

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

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

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

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

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

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

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

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

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

Примечания:

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

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

Точность определяет количество значащих цифр до и после десятичной точки и по умолчанию составляет 6.
Если точность равна N, вывод усекается до символов N.
См. PEP 237.

Поскольку у строк Python есть явная длина, преобразования %s не предполагает, что '\0' является концом строки.

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

Типы двоичных последовательностей — `bytes`, `bytearray`, `memoryview`¶

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

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

Объекты байтов¶

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

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

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

Одинарные кавычки: b'по-прежнему допускает встроенные "двойные" кавычки'
Двойные кавычки: b"по-прежнему допускает встроенные 'одиночные' кавычки".
Тройное цитирование: b'''3 одинарные кавычки''', b"""3 двойные кавычки"""

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

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

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

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

Заполненный нулями байтовый объект указанной длины: bytes(10)
Из итерации целых чисел: bytes(range(20))
Копирование существующих двоичных данных через буферный протокол: bytes(obj)

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

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

classmethod fromhex(string)¶

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

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

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

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

hex([sep[, bytes_per_sep]])¶

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

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

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

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

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

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

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

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

Примечание

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

Объекты Bytearray¶

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

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

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

Создание пустого экземпляра: bytearray()
Создание экземпляра с заполнением нулями заданной длины: bytearray(10)
Из итерации целых чисел: bytearray(range(20))
Копирование существующих двоичных данных через буферный протокол: bytearray(b'Hi!')

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

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

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

classmethod fromhex(string)¶

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

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

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

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

hex([sep[, bytes_per_sep]])¶

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

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

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

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

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

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

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

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

Примечание

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

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

а также:

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

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

Примечание

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Примечание

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

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

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

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

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

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

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

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

bytes.join(iterable)¶
bytearray.join(iterable)¶: Возвращает объект bytes или bytearray, который представляет собой объединение последовательностей двоичных данных в iterable. Вызывается TypeError, если в iterable есть какие-либо значения, которые не являются term:байтоподобным объектом <байтоподобный объект>, включая объекты str. Разделитель между элементами — это содержимое байтов или объекта байтового массива, предоставляющие этот метод.

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

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

bytes.partition(sep)¶

bytearray.partition(sep)¶

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

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

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

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

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

Подпоследовательность для поиска и её замены может быть любым байтоподобным объектом.

Примечание

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

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

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

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

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

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

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

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

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

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

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

bytes.rpartition(sep)¶

bytearray.rpartition(sep)¶

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

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

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

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

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

Префиксы для поиска могут быть любыми байтоподобными объектами.

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

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

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

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

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

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

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

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

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

Примечание

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

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

Примечание

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

bytes.lstrip([chars])¶

bytearray.lstrip([chars])¶

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

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

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

Примечание

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

bytes.rjust(width[, fillbyte])¶
bytearray.rjust(width[, 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([chars])¶

bytearray.rstrip([chars])¶

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

bytearray.strip([chars])¶

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

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

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

Примечание

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

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

bytes.capitalize()¶
bytearray.capitalize()¶: Возвращает копию последовательности, в которой каждый байт интерпретируется как символ ASCII, причем первый байт — заглавная, а остальные — строчные. Байтовые значения, отличные от ASCII, передаются без изменений.

Примечание

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

bytes.expandtabs(tabsize=8)¶

bytearray.expandtabs(tabsize=8)¶

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

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

Примечание

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

bytes.isalnum()¶

bytearray.isalnum()¶

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

Например:

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

bytes.isalpha()¶

bytearray.isalpha()¶

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

Например:

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

bytes.isascii()¶
bytearray.isascii()¶: Возвращает True, если последовательность пуста или все байты в последовательности ASCII, в противном случае — False. Байты ASCII находятся в диапазоне 0-0x7F.

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

bytes.isdigit()¶

bytearray.isdigit()¶

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

Например:

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

bytes.islower()¶

bytearray.islower()¶

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

Например:

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

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

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

bytes.istitle()¶

bytearray.istitle()¶

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

Например:

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

Примечание

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

bytes.title()¶

bytearray.title()¶

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

Например:

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

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

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

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

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

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

Примечание

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

bytes.upper()¶

bytearray.upper()¶

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

Например:

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

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

Примечание

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

bytes.zfill(width)¶

bytearray.zfill(width)¶

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

Например:

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

Примечание

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

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

Примечание

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

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

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

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

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

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

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

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

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

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

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

Примечания:

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

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

Точность определяет количество значащих цифр до и после десятичной точки и по умолчанию составляет 6.
Если точность равна N, вывод усекается до символов N.
b'%s' устарел, но не будет удалён в серии 3.x.
b'%r' устарел, но не будет удалён в серии 3.x.
См. PEP 237.

Примечание

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

См.также

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

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

Просмотры памяти¶

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

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

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

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

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

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

Одномерные представления памяти хешируемых (только для чтения) типов с форматами «B», «b» или «c» также могут быть хешированы. Хэш определяется как hash(m) == hash(m.tobytes()):

>>> v = memoryview(b'abcefg')
>>> hash(v) == hash(b'abcefg')
True
>>> hash(v[2:4]) == hash(b'ce')
True
>>> hash(v[::-2]) == hash(b'abcefg'[::-2])
True

Изменено в версии 3.3: Одномерные представления памяти теперь можно нарезать. Одномерные представления памяти с форматами «B», «b» или «c» теперь хешируются.

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

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

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

__eq__(exporter)¶

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

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

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

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

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

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

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

tobytes(order=None)¶

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

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

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

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

hex([sep[, bytes_per_sep]])¶

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

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

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

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

tolist()¶

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

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

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

toreadonly()¶

Возвращает версию объекта memoryview только для чтения. Исходный объект memoryview не изменился.

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

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

release()¶

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

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

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

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

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

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

cast(format[, shape])¶

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

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

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

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

Преобразование 1D/беззнаковых байтов в 1D/char:

>>> b = bytearray(b'zyz')
>>> x = memoryview(b)
>>> x[0] = b'a'
Traceback (most recent call last):
  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/байтов в 3D/int в 1D/знаковый char:

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

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

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

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

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

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

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

Типы множества — `set`, `frozenset`¶

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

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

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

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

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

class set([iterable])¶

class frozenset([iterable])¶

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

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

Используя список элементов, разделенных запятыми, в фигурных скобках: {'jack', 'sjoerd'}
Используя множественное включение: {c for c in 'abracadabra' if c not in 'abc'}
Используя конструктор типов: set(), set('foobar'), set(['a', 'b', 'foo'])

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

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

x in s: Проверить x на принадлежность к s.

x not in s: Проверить x на непринадлежность к s.

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

issubset(other)¶
set <= other: Проверить, каждый ли элемент в множестве состоит из other.

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

issuperset(other)¶
set >= other: Проверить, есть ли в множестве все other элементы.

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

union(*others)¶
set | other |...: Возвращает новое множество с элементами из множества и всеми остальными.

intersection(*others)¶
set & other & ...: Возвращает новое множество с элементами, общими для множества и всех остальных.

difference(*others)¶
set - other - ...: Возвращает новое множество с элементами в множестве, которых нет в других.

symmetric_difference(other)¶
set ^ other: Возвращает новое множество с элементами либо в множестве, либо в other, но не с обоими.

copy()¶: Возвращает неглубокую копию множества.

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

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

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

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

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

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

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

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

update(*others)¶
set |= other | ...: Обновить множество, добавив элементы из всех остальных.

intersection_update(*others)¶
set &= other & ...: Обновить множество, сохранив только элементы, найденные в нём и все остальные.

difference_update(*others)¶
set -= other | ...: Обновляет множество, удалив элементы, найденные в других.

symmetric_difference_update(other)¶
set ^= other: Обновляет множество, сохранив только элементы, найденные в любом множестве, но не в обоих.

add(elem)¶: Добавляет элемент elem в множество.

remove(elem)¶: Удаляет элемент elem из множества. Вызывает KeyError, если elem не содержится в множестве.

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

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

clear()¶: Убирает все элементы из множества.

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

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

Типы сопоставления — `dict`¶

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

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

Словари можно создать, поместив разделенный запятыми список пар key: value в фигурные скобки, например: {'jack': 4098, 'sjoerd': 4127} или {4098: 'jack', 4127: 'sjoerd'}, или с помощью конструктора dict.

class dict(**kwarg)

class dict(mapping, **kwarg)

class dict(iterable, **kwarg)

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

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

Используя разделенный запятыми список пар key: value в фигурных скобках: {'jack': 4098, 'sjoerd': 4127} или {4098: 'jack', 4127: 'sjoerd'}
Используя словарное включение: {}, {x: x ** 2 for x in range(10)}
Используя конструктор типа: dict(), dict([('foo', 100), ('bar', 200)]), dict(foo=100, bar=200)

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

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

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

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

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

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

d[key]

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

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

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

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

d[key] = value: Установить d[key] на value.

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

key in d: Возвращает True, если у d есть ключевой key, иначе False.

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

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

clear()¶: Удалить все элементы из словаря.

copy()¶: Возвращает неглубокую копию словаря.

classmethod fromkeys(iterable[, value])¶

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

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

get(key[, default])¶: Возвращает значение key, если key находится в словаре, иначе default. Если значение по умолчанию не указано, по умолчанию используется None, поэтому этот метод никогда не вызывает KeyError.

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

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

pop(key[, default])¶: Если key находится в словаре, удалить его и вернуть его значение, иначе вернуть значение default. Если значение default не указано и key отсутствует в словаре, возникает KeyError.

popitem()¶

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

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

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

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

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

setdefault(key[, default])¶: Если key находится в словаре, вернуть его значение. Если нет, вставить key со значением default и вернуть значение default. default — None.

update([other])¶

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

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

values()¶

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

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

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

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

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

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

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

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

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

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

См.также

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

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

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

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

len(dictview): Возвращает количество записей в словаре.

iter(dictview)

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

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

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

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

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

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

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

Представления ключей похожи на множества, поскольку их записи уникальны и хешируются. Если все значения являются хешируемыми, так что пары (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', 'sausage', 'bacon', 'spam']
>>> list(values)
[2, 1, 1, 500]

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

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

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

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

contextmanager.__enter__()¶

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

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

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

contextmanager.__exit__(exc_type, exc_val, exc_tb)¶

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

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

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

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

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

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

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

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

Модули¶

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

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

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

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

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

Функции¶

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

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

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

Методы¶

Методы — это функции, которые вызываются с использованием записи атрибутов. Есть две разновидности: встроенные методы (например, 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 = 'меня зовут метод'  # не могу установить метод
Traceback (most recent call last):
  File "<stdin>", line 1, in <module>
AttributeError: 'method' object has no attribute 'whoami'
>>> c.method.__func__.whoami = 'меня зовут метод'
>>> c.method.whoami
'меня зовут метод'

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

Объекты кода¶

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

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

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

Объекты типа¶

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

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

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

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

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

Объект многоточия¶

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

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

Не реализованный объект¶

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

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

Логические значения¶

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

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

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

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

Особые атрибуты¶

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

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

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

Логические операции — and, or, not¶

Сравнения¶

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

Побитовые операции с целыми типами¶

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

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

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

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

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

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

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

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

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

Списки¶

Кортежи¶

Диапазоны¶

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

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

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

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

Объекты байтов¶

Объекты Bytearray¶

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

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

Просмотры памяти¶

Типы множества — set, frozenset¶

Типы сопоставления — dict¶

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

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

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

Модули¶

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

Функции¶

Методы¶

Объекты кода¶

Объекты типа¶

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

Объект многоточия¶

Не реализованный объект¶

Логические значения¶

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

Особые атрибуты¶

Логические операции — `and`, `or`, `not`¶

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

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

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

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

Типы двоичных последовательностей — `bytes`, `bytearray`, `memoryview`¶

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

Типы множества — `set`, `frozenset`¶

Типы сопоставления — `dict`¶