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

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

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

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

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

Примечания:

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

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

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

int.bit_length()

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

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

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

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

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

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

int.bit_count()

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

def from_bytes(bytes, byteorder='big', signed=False):
    if byteorder == 'little':
        little_ordered = list(bytes)
    elif byteorder == 'big':
        little_ordered = list(reversed(bytes))
    else:
        raise ValueError("byteorder must be either 'little' or 'big'")

    n = sum(b << i*8 for i, b in enumerate(little_ordered))
    if signed and little_ordered and (little_ordered[-1] & 0x80):
        n -= 1 << 8*len(little_ordered)

    return n

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

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

int.as_integer_ratio()

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

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

int.is_integer()

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

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

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

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

classmethod float.from_number(x)

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

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

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

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

float.as_integer_ratio()

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

float.is_integer()

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

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

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

float.hex()

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

classmethod float.fromhex(s)

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

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

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

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

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

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

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

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

classmethod complex.from_number(x)

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

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

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

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

Для чисел 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.

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

• Если x = m / n — неотрицательное рациональное число, а n не делится на P, определим hash(x) как m * invmod(n, P) % P, где invmod(n, P) задаёт обратное значение для n по модулю P.
• Если x = m / n — неотрицательное рациональное число, а n делится на P (но m — нет), то n не имеет обратного значения по модулю P, поэтому приведённое выше правило неприменимо; в этом случае определим hash(x) как постоянное значение sys.hash_info.inf.
• Если x = m / n — отрицательное рациональное число, определим hash(x) как -hash(-x). Если полученный хеш равен -1, заменим его на -2.
• Значения sys.hash_info.inf и -sys.hash_info.inf используются как хеши положительной и отрицательной бесконечности соответственно.
• Для числа типа complex z значения хешей действительной и мнимой частей объединяются вычислением hash(z.real) + sys.hash_info.imag * hash(z.imag) с приведением по модулю 2**sys.hash_info.width, чтобы результат находился в диапазоне range(-2**(sys.hash_info.width - 1), 2**(sys.hash_info.width - 1)). И снова, если результат равен -1, он заменяется на -2.

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

import sys, math

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Примечания:

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

   >>> "gg" in "eggs"
   True
   

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

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

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

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

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

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

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

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

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

   • при конкатенации объектов str можно сформировать список и в конце использовать str.join() либо записывать данные в экземпляр io.StringIO и получить его значение по завершении
   • при конкатенации объектов bytes аналогично можно использовать bytes.join() или io.BytesIO; также можно выполнять конкатенацию на месте с помощью объекта bytearray. Объекты bytearray изменяемы и используют эффективный механизм выделения дополнительной памяти
   • при конкатенации объектов tuple вместо этого расширяйте list
   • для других типов изучите соответствующую документацию класса
7. Некоторые типы последовательностей (например, range) поддерживают только последовательности элементов, соответствующие определённым шаблонам, и поэтому не поддерживают конкатенацию или повторение последовательностей.
8. Если i выходит за границы последовательности, возникает исключение IndexError.

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

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

sequence.count(value, /)

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

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

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

Если value не найдено в sequence, возникает исключение ValueError.

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

Внимание

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

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

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

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

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

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

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

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

Примечания:

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

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

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

sequence.append(value, /)

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

sequence.clear()

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

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

sequence.copy()

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

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

Подсказка

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

sequence.extend(iterable, /)

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

sequence.insert(index, value, /)

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

sequence.pop(index=-1, /)

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

sequence.remove(value, /)

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

Если value не найдено в sequence, возникает исключение ValueError.

sequence.reverse()

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

Списки

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

class list(iterable=(), /)

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

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

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

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

Списки являются обобщёнными по типам своих элементов.

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

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

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

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

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

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

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

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

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

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

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

Кортежи

Кортежи — это неизменяемые последовательности, обычно используемые для хранения наборов разнородных данных (например, пар элементов, создаваемых встроенной функцией 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=1, /)

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

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

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

Объект 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))
[]

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

start

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

stop

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

step

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

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

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

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

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

Методы строк

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

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

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

str.capitalize()

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

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

str.casefold()

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

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

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

Алгоритм преобразования регистра методом casefold описан в разделе 3.13 «Default Case Folding» стандарта Unicode.

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

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

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

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

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

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

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

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

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

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

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

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

В целях повышения производительности значение errors не проверяется на допустимость, если ошибка кодирования фактически не возникла, не включён режим разработки Python и не используется отладочная сборка. Например:

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

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

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

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

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

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

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

str.expandtabs(tabsize=8)

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

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

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

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

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

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

Примечание

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

>>> 'Py' in 'Python'
True

str.format(*args, **kwargs)

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

>>> "The sum of 1 + 2 is {0}".format(1+2)
'The sum of 1 + 2 is 3'
>>> "The sum of {a} + {b} is {answer}".format(answer=1+2, a=1, b=2)
'The sum of 1 + 2 is 3'
>>> "{1} expects the {0} Inquisition!".format("Spanish", "Nobody")
'Nobody expects the Spanish Inquisition!'

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

Примечание

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

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

str.format_map(mapping, /)

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

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

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

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

Подобно find(), но вызывает исключение ValueError, если подстрока не найдена. Например:

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

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

str.isalnum()

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

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

str.isalpha()

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

>>> 'Letters and spaces'.isalpha()
False
>>> 'LettersOnly'.isalpha()
True
>>> 'µ'.isalpha()  # non-ASCII characters can be considered alphabetical too
True

См. Свойства Unicode.

str.isascii()

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

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

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

str.isdecimal()

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

>>> '0123456789'.isdecimal()
True
>>> '٠١٢٣٤٥٦٧٨٩'.isdecimal()  # Arabic-Indic digits zero to nine
True
>>> 'alphabetic'.isdecimal()
False

str.isdigit()

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

Например:

>>> '0123456789'.isdigit()
True
>>> '٠١٢٣٤٥٦٧٨٩'.isdigit()  # Arabic-Indic digits zero to nine
True
>>> '⅕'.isdigit()  # Vulgar fraction one fifth
False
>>> '²'.isdecimal(), '²'.isdigit(),  '²'.isnumeric()
(False, True, True)

См. также isdecimal() и isnumeric().

str.isidentifier()

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

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

Пример:

>>> from keyword import iskeyword

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

str.islower()

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

str.isnumeric()

Возвращает True, если все символы строки являются числовыми и строка содержит хотя бы один символ, и False в противном случае. К числовым символам относятся цифры и все символы, имеющие свойство числового значения Unicode, например U+2155, VULGAR FRACTION ONE FIFTH. Формально числовыми являются символы со значением свойства Numeric_Type=Digit, Numeric_Type=Decimal или Numeric_Type=Numeric. Например:

>>> '0123456789'.isnumeric()
True
>>> '٠١٢٣٤٥٦٧٨٩'.isnumeric()  # Arabic-Indic digits zero to nine
True
>>> '⅕'.isnumeric()  # Vulgar fraction one fifth
True
>>> '²'.isdecimal(), '²'.isdigit(),  '²'.isnumeric()
(False, True, True)

См. также isdecimal() и isdigit().

str.isprintable()

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

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

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

Например:

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

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

str.isspace()

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

Например:

>>> ''.isspace()
False
>>> ' '.isspace()
True
>>> '\t\n'.isspace() # TAB and BREAK LINE
True
>>> '\u3000'.isspace() # IDEOGRAPHIC SPACE
True

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

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

str.istitle()

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

Например:

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

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

str.isupper()

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

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

str.join(iterable, /)

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

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

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

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

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

Например:

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

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

str.lower()

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

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

Используемый алгоритм преобразования в нижний регистр описан в разделе 3.13 «Default Case Folding» стандарта Unicode.

str.lstrip(chars=None, /)

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

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

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

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

static str.maketrans(dict, /)

статический str.maketrans(from, to, remove='', /)

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

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

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

str.partition(sep, /)

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

Например:

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

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

str.removeprefix(prefix, /)

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

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

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

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

str.removesuffix(suffix, /)

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

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

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

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

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

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

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

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

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

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

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

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

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

Подобно rfind(), но вызывает исключение ValueError, если подстрока sub не найдена. Например:

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

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

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

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

Например:

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

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

str.rpartition(sep, /)

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

Например:

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

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

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

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

str.rstrip(chars=None, /)

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

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

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

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

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

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

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

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

Например:

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

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

Например:

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

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

Например:

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

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

str.splitlines(keepends=False)

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

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

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

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

Например:

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

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

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

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

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

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

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

Например:

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

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

str.strip(chars=None, /)

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

Пробельные символы определяются методом str.isspace().

Например:

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

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

Например:

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

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

str.swapcase()

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

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

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

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

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

str.title()

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

Например:

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

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

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

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

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

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

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

str.translate(table, /)

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

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

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

str.upper()

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

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

str.zfill(width, /)

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

Например:

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

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

Форматированные строковые литералы (f-строки)

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

• спецификатор отладки — знак равенства (=);
• спецификатор преобразования — !s, !r или !a; и/или
• спецификатор формата с префиксом в виде двоеточия (:).

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

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

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

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

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

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

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

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

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

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

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

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

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

• Вместо вычисления в объект str шаблонные строковые литералы вычисляются в объект string.templatelib.Template.
• Протокол format() не используется. Вместо этого спецификатор формата и преобразования (если они есть) передаются новому объекту Interpolation, создаваемому для каждого вычисленного выражения. Код, обрабатывающий полученный объект Template, сам определяет, как обрабатывать спецификаторы формата и преобразования.
• Спецификаторы формата, содержащие вложенные поля подстановки, вычисляются немедленно, до передачи объекту Interpolation. Например, интерполяция вида {amount:.{precision}f} вычислит внутреннее выражение {precision}, чтобы определить значение атрибута format_spec. Если бы precision имело значение 2, результирующий спецификатор формата был бы '.2f'.
• Если в выражении интерполяции указан знак равенства '=', текст выражения добавляется к строковому литералу, предшествующему соответствующей интерполяции. Он включает знак равенства и окружающие его пробелы. Экземпляр Interpolation для выражения создаётся обычным образом, за исключением того, что conversion по умолчанию получает значение «r» (repr()). Явно заданное преобразование или спецификатор формата переопределяет это поведение по умолчанию.

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

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

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

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

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

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

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

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

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

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

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

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

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

Примечания:

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

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

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

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

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

5. Если точность равна N, вывод обрезается до N символов.
6. См. PEP 237.

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

Объекты bytes

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

class bytes(source=b'')

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

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

• Одинарные кавычки: b'still allows embedded "double" quotes'
• Двойные кавычки: b"still allows embedded 'single' quotes"
• Тройные кавычки: b'''3 single quotes''', b"""3 double quotes"""

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

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

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

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

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

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

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

classmethod fromhex(string, /)

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

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

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

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

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

hex(*, bytes_per_sep=1)

hex(sep, bytes_per_sep=1)

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

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

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

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

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

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

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

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

Объекты bytearray

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

class bytearray(source=b'')

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

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

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

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

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

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

classmethod fromhex(string, /)

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

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

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

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

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

hex(*, bytes_per_sep=1)

hex(sep, bytes_per_sep=1)

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

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

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

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

resize(size, /)

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

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

Если bytearray нужно увеличить, все новые байты после size устанавливаются в нулевые байты.

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

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

Примеры:

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

bytes.removeprefix(prefix, /)

bytearray.removeprefix(prefix, /)

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

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

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

Примечание

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

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

bytes.removesuffix(suffix, /)

bytearray.removesuffix(suffix, /)

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

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

suffix может быть любым объектом, подобным bytes.

Примечание

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

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

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

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

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

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

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

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

Примечание

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

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

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

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

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

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

Искомый суффикс или суффиксы могут быть любым объектом, подобным bytes.

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

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

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

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

Примечание

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

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

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

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

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

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

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

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

bytes.join(iterable, /)

bytearray.join(iterable, /)

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

static bytes.maketrans(from, to, /)

static bytearray.maketrans(from, to, /)

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

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

bytes.partition(sep, /)

bytearray.partition(sep, /)

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

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

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

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

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

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

Примечание

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

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

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

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

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

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

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

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

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

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

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

bytes.rpartition(sep, /)

bytearray.rpartition(sep, /)

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

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

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

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

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

Искомый префикс или префиксы могут быть любым объектом, подобным bytes.

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

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

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

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

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

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

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

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

bytes.center(width, fillbyte=b' ', /)

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

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

Примечание

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

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

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

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

Примечание

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

bytes.lstrip(bytes=None, /)

bytearray.lstrip(bytes=None, /)

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

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

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

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

Примечание

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

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

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

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

Примечание

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

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

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

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

bytes.rstrip(bytes=None, /)

bytearray.rstrip(bytes=None, /)

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

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

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

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

Примечание

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

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

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

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

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

Например:

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

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

Например:

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

bytes.strip(bytes=None, /)

bytearray.strip(bytes=None, /)

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

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

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

Примечание

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

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

bytes.capitalize()

bytearray.capitalize()

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

Примечание

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

bytes.expandtabs(tabsize=8)

bytearray.expandtabs(tabsize=8)

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

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

Примечание

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

bytes.isalnum()

bytearray.isalnum()

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

Например:

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

bytes.isalpha()

bytearray.isalpha()

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

Например:

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

bytes.isascii()

bytearray.isascii()

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

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

bytes.isdigit()

bytearray.isdigit()

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

Например:

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

bytes.islower()

bytearray.islower()

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

Например:

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

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

bytes.isspace()

bytearray.isspace()

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

bytes.istitle()

bytearray.istitle()

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

Например:

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

bytes.isupper()

bytearray.isupper()

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

Например:

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

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

bytes.lower()

bytearray.lower()

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

Например:

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

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

Примечание

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

bytes.splitlines(keepends=False)

bytearray.splitlines(keepends=False)

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

Например:

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

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

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

bytes.swapcase()

bytearray.swapcase()

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

Например:

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

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

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

Примечание

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

bytes.title()

bytearray.title()

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

Например:

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

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

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

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

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

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

Примечание

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

bytes.upper()

bytearray.upper()

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

Например:

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

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

Примечание

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

bytes.zfill(width, /)

bytearray.zfill(width, /)

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

Например:

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

Примечание

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

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

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

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

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

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

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

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

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

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

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

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

Примечания:

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

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

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

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

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

5. Если точность равна N, вывод усекается до N символов.
6. b'%s' является устаревшим, но не будет удален в серии версий 3.x.
7. b'%r' является устаревшим, но не будет удален в серии версий 3.x.
8. См. PEP 237.

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

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

class memoryview(object)

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

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

memoryviews являются обобщёнными по типу содержащихся в них данных.

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

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

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

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

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

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

Пример с форматом, отличным от байтового:

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

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

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

Одномерные представления памяти хешируемых (доступных только для чтения) типов с форматами ‘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: Теперь представления памяти можно индексировать кортежем целых чисел.

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

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

__eq__(exporter)

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

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

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

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

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

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

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

tobytes(order='C')

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

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

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

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

hex(*, bytes_per_sep=1)

hex(sep, bytes_per_sep=1)

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

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

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

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

tolist()

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

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

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

toreadonly()

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

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

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

release()

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

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

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

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

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

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

cast(format, /)

cast(format, shape, /)

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

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

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

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

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

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

Преобразование 1D/байты в 3D/целые числа, затем в 1D/знаковый символ:

>>> 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/беззнаковый long в 2D/беззнаковый long:

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

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

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

count(value, /)

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

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

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

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

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

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

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

obj

Базовый объект представления memoryview:

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

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

nbytes

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

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

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

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

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

readonly

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

format

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

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

itemsize

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

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

ndim

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

shape

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

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

strides

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

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

suboffsets

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

c_contiguous

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

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

f_contiguous

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

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

contiguous

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

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

Информацию о потокобезопасности объектов memoryview в сборке без GIL см. в разделе Потокобезопасность объектов memoryview.

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

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

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

len(dictview)

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

iter(dictview)

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

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

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

Изменено в версии 3.7: Гарантируется, что порядок элементов словаря совпадает с порядком их вставки.

x in dictview

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

reversed(dictview)

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

Изменено в версии 3.8: Теперь представления словаря допускают обратный обход.

dictview.mapping

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

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

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

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

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

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

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

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

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

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

Тип обобщённого псевдонима

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

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

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

Для класса, который определяет __class_getitem__(), но не является контейнером, аргументы, переданные при его индексации, часто указывают типы возвращаемых значений одного или нескольких методов объекта. Например, regular expressions можно использовать как с типом данных str, так и с типом данных bytes:

• Если x = re.search('foo', 'foo'), x будет объектом re.Match, в котором значения, возвращаемые x.group(0) и x[0], будут иметь тип str. В аннотациях типов такой объект можно представить с помощью GenericAlias re.Match[str].
• Если y = re.search(b'bar', b'bar') (обратите внимание на b для bytes), y также будет экземпляром re.Match, но значения, возвращаемые y.group(0) и y[0], будут иметь тип bytes. В аннотациях типов эту разновидность объектов re.Match можно представить с помощью re.Match[bytes].

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

T[X, Y, ...]

Создаёт GenericAlias, представляющий тип T, параметризованный типами X, Y и другими — в зависимости от используемого T. Например, функция, ожидающая list с элементами типа float:

def average(values: list[float]) -> float:
    return sum(values) / len(values)

Другой пример — объекты отображений с использованием dict — обобщённого типа, которому требуются два параметра типа, представляющие тип ключа и тип значения. В этом примере функция ожидает dict с ключами типа str и значениями типа int:

def send_post_request(url: str, body: dict[str, int]) -> None:
    ...

Встроенные функции isinstance() и issubclass() не принимают типы GenericAlias в качестве второго аргумента:

>>> isinstance([1, 2], list[str])
Traceback (most recent call last):
  File "<stdin>", line 1, in <module>
TypeError: isinstance() argument 2 cannot be a parameterized generic

Среда выполнения Python не проверяет аннотации типов. Это относится и к обобщённым типам и их параметрам типов. При создании объекта-контейнера из GenericAlias типы элементов контейнера не проверяются. Например, следующий код использовать не рекомендуется, однако он выполнится без ошибок:

>>> t = list[str]
>>> t([1, 2, 3])
[1, 2, 3]

Кроме того, при создании объекта параметризованные обобщённые типы удаляют параметры типа:

>>> t = list[str]
>>> type(t)
<class 'types.GenericAlias'>

>>> l = t()
>>> type(l)
<class 'list'>

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

>>> import inspect
>>> inspect.isclass(list[int])
False

Это также справедливо для пользовательских обобщённых типов.

Вызов repr() или str() для обобщённого типа показывает параметризованный тип:

>>> repr(list[int])
'list[int]'

>>> str(list[int])
'list[int]'

Метод __getitem__() обобщённых контейнеров вызывает исключение, чтобы предотвратить такие ошибки, как dict[str][str]:

>>> dict[str][str]
Traceback (most recent call last):
  ...
TypeError: dict[str] is not a generic class

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

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

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

Объект объединения хранит значение операции | (побитовое ИЛИ) над несколькими объектами типов. Эти типы предназначены главным образом для аннотаций типов. Выражение типа объединения позволяет записывать подсказки типов более лаконично, чем при индексировании typing.Union.

X | Y | ...

Определяет объект объединения, содержащий типы X, Y и так далее. X | Y означает «X или Y». Это эквивалентно typing.Union[X, Y]. Например, следующая функция ожидает аргумент типа int или float:

def square(number: int | float) -> int | float:
    return number ** 2

Примечание

Оператор | нельзя использовать во время выполнения для определения объединений, если один или несколько их элементов являются предварительными ссылками. Например, int | "Foo", где "Foo" — ссылка на ещё не определённый класс, завершится ошибкой во время выполнения. Для объединений с предварительными ссылками запишите всё выражение в виде строки, например "int | Foo".

union_object == other

Объекты объединения можно сравнивать на равенство с другими объектами объединения. Подробности:

• Вложенные объединения уплощаются:

  (int | str) | float == int | str | float
  

• Избыточные типы удаляются:

  int | str | int == int | str
  

• При сравнении объединений порядок не учитывается:

  int | str == str | int
  

• Создаются экземпляры typing.Union:

  int | str == typing.Union[int, str]
  type(int | str) is typing.Union
  

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

  str | None == typing.Optional[str]
  

isinstance(obj, union_object)

issubclass(obj, union_object)

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

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

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

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

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

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

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

Модули

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

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

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

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

Объекты кода

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

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

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

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

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

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

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

Объект Null

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

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

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

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

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

В типичном использовании ... в качестве объекта Ellipsis встречается в нескольких местах, например:

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

Python также использует три точки в случаях, когда они не являются объектами Ellipsis, например:

• ELLIPSIS в doctest как шаблон для пропущенного содержимого.
• Стандартное приглашение Python в интерактивной оболочке, когда ввод неполон.

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

Объект NotImplemented

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

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

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

Дополнительную информацию см. в разделе Стандартная иерархия типов. В нём описаны объекты кадров стека, объекты трассировки стека и объекты срезов.

Затронутые API

Ограничение применяется только к потенциально медленным преобразованиям между int и str или bytes:

• int(string) со значением основания по умолчанию 10.
• int(string, base) для всех оснований, которые не являются степенью 2.
• str(integer).
• repr(integer).
• любое другое преобразование строки в систему счисления с основанием 10, например f"{integer}", "{}".format(integer) или b"%d" % integer.

Ограничения не распространяются на функции с линейным алгоритмом:

• int(string, base) с основанием 2, 4, 8, 16 или 32.
• int.from_bytes() и int.to_bytes().
• hex(), oct(), bin().
• Мини-язык спецификаций формата для шестнадцатеричных, восьмеричных и двоичных чисел.
• str в float.
• str в decimal.Decimal.

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

До запуска Python можно настроить ограничение с помощью переменной окружения или флага командной строки интерпретатора:

• PYTHONINTMAXSTRDIGITS, например PYTHONINTMAXSTRDIGITS=640 python3, чтобы установить ограничение в 640, или PYTHONINTMAXSTRDIGITS=0 python3, чтобы отключить ограничение.
• -X int_max_str_digits, например python3 -X int_max_str_digits=640
• sys.flags.int_max_str_digits содержит значение PYTHONINTMAXSTRDIGITS или -X int_max_str_digits. Если заданы и переменная окружения, и параметр -X, приоритет имеет параметр -X. Значение -1 означает, что оба параметра не были заданы, поэтому при инициализации использовалось значение sys.int_info.default_max_str_digits.

В коде можно узнать текущее ограничение и задать новое с помощью следующих API из sys:

• sys.get_int_max_str_digits() и sys.set_int_max_str_digits() — функции получения и установки ограничения для всего интерпретатора. У подинтерпретаторов свои ограничения.

Сведения о значениях по умолчанию и минимальном значении можно найти в sys.int_info:

• sys.int_info.default_max_str_digits — ограничение по умолчанию, заданное при компиляции.
• sys.int_info.str_digits_check_threshold — наименьшее допустимое значение ограничения (кроме 0, отключающего его).

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

Значение sys.int_info.default_max_str_digits по умолчанию считается подходящим для большинства приложений. Если вашему приложению требуется другое ограничение, задайте его в основной точке входа, используя код, совместимый с разными версиями Python, поскольку эти API были добавлены в выпусках с исправлениями безопасности для версий до 3.12.

Пример:

>>> import sys
>>> if hasattr(sys, "set_int_max_str_digits"):
...     upper_bound = 68000
...     lower_bound = 4004
...     current_limit = sys.get_int_max_str_digits()
...     if current_limit == 0 or current_limit > upper_bound:
...         sys.set_int_max_str_digits(upper_bound)
...     elif current_limit < lower_bound:
...         sys.set_int_max_str_digits(lower_bound)

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

Сноски