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

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

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

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

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

Примечания:

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 должен быть объектом, подобным байтам, либо итерируемым объектом, выдающим байты.

Аргумент 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 также имеет следующие дополнительные методы.

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'

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

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

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

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

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

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

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

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

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

start

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

stop

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

step

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

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

Объекты диапазонов реализуют 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

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

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

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

Алгоритм преобразования регистра описан в разделе 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'

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

Примечание

При форматировании числа (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, если подстрока не найдена.

str.isalnum()

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

str.isalpha()

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

str.isascii()

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

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

str.isdecimal()

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

str.isdigit()

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

str.isidentifier()

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

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

Пример:

>>> from keyword import iskeyword

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

str.islower()

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

str.isnumeric()

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

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.

str.isspace()

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

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

str.istitle()

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

str.isupper()

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

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

str.join(iterable, /)

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

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

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

str.lower()

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

Используемый алгоритм перевода в нижний регистр описан в разделе 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, /)

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

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

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

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

str.partition(sep, /)

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

str.removeprefix(prefix, /)

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

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

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

str.removesuffix(suffix, /)

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

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

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

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

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

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

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

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

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

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

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

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

str.rpartition(sep, /)

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

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

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

str.rstrip(chars=None, /)

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

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

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

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

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

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

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

Например:

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

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

Например:

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

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

Например:

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

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, сравнение строки заканчивается на этой позиции.

str.strip(chars=None, /)

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

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

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

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

str.swapcase()

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

str.title()

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

Например:

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

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

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

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

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

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

str.translate(table, /)

Возвращает копию строки, в которой каждый символ преобразован с помощью заданной таблицы преобразования. Таблица должна быть объектом, поддерживающим индексацию через __getitem__(); обычно это отображение или последовательность. При индексации по порядковому номеру 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'

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

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

>>> who = 'nobody'
>>> nationality = 'Spanish'
>>> f'{who.title()} expects the {nationality} Inquisition!'
'Nobody expects the Spanish Inquisition!'

Также можно использовать многострочную f-строку:

>>> f'''This is a string
... on two lines'''
'This is a string\non two lines'

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

>>> nationality = 'Spanish'
>>> f'The {nationality} Inquisition!'
'The Spanish Inquisition!'

Чтобы включить в строку буквальный символ { или }, используйте двойные скобки:

>>> x = 42
>>> f'{{x}} is {x}'
'{x} is 42'

Можно также использовать функции и спецификаторы формата:

>>> from math import sqrt
>>> f'√2 \N{ALMOST EQUAL TO} {sqrt(2):.5f}'
'√2 ≈ 1.41421'

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

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

Для явного преобразования используйте оператор ! (восклицательный знак), за которым следует один из допустимых форматов:

Например:

>>> from fractions import Fraction
>>> f'{Fraction(1, 3)!s}'
'1/3'
>>> f'{Fraction(1, 3)!r}'
'Fraction(1, 3)'
>>> question = '¿Dónde está el Presidente?'
>>> print(f'{question!a}')
'\xbfD\xf3nde est\xe1 el Presidente?'

При отладке может быть полезно видеть и выражение, и его значение. Для этого после выражения поставьте знак равенства (=). При этом сохраняются пробелы внутри скобок; такой синтаксис можно использовать с преобразователем. По умолчанию оператор отладки использует преобразование repr() (!r). Например:

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

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

>>> from fractions import Fraction
>>> f'{Fraction(1, 7):.6f}'
'0.142857'
>>> f'{Fraction(1, 7):_^+10}'
'___+1/7___'

Форматирование строк в стиле 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.

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

Примечания:

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.

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

Для преобразования объекта 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, а не только пробелы.

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

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

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 интерпретируются так же, как в записи среза.

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

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

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

bytes.removeprefix(prefix, /)

bytearray.removeprefix(prefix, /)

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

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

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

Примечание

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

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

bytes.removesuffix(suffix, /)

bytearray.removesuffix(suffix, /)

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

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

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

Примечание

Версия этого метода для 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 или bytearray.

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

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

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

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

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

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

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

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

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

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

Примечание

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

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

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

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

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

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

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

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

bytes.join(iterable, /)

bytearray.join(iterable, /)

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

static bytes.maketrans(from, to, /)

static bytearray.maketrans(from, to, /)

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

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

bytes.partition(sep, /)

bytearray.partition(sep, /)

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

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

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

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

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

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

Примечание

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

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

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

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

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

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

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

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

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

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

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

bytes.rpartition(sep, /)

bytearray.rpartition(sep, /)

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Примечание

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

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

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

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

Примечание

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

bytes.lstrip(bytes=None, /)

bytearray.lstrip(bytes=None, /)

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

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

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

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

Примечание

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

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

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

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

Примечание

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

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

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

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

bytes.rstrip(bytes=None, /)

bytearray.rstrip(bytes=None, /)

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

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

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

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

Примечание

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

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

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

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

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

Например:

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

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

Например:

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

bytes.strip(bytes=None, /)

bytearray.strip(bytes=None, /)

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

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

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

Примечание

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

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

bytes.capitalize()

bytearray.capitalize()

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

Примечание

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

bytes.expandtabs(tabsize=8)

bytearray.expandtabs(tabsize=8)

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

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

Примечание

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

bytes.isalnum()

bytearray.isalnum()

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

Например:

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

bytes.isalpha()

bytearray.isalpha()

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

Например:

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

bytes.isascii()

bytearray.isascii()

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

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

bytes.isdigit()

bytearray.isdigit()

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

Например:

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

bytes.islower()

bytearray.islower()

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

Например:

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

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

bytes.isspace()

bytearray.isspace()

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

bytes.istitle()

bytearray.istitle()

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

Например:

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

bytes.isupper()

bytearray.isupper()

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

Например:

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

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

bytes.lower()

bytearray.lower()

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

Например:

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

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

Примечание

Версия этого метода для 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 не изменяет объект на месте — она всегда создаёт новый объект, даже если никаких изменений не было внесено.

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

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

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

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

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

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

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

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

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

Модификатор длины (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, элементы могут быть крупнее.

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

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], то есть результирующее представление будет одномерным. Возвращаемое значение — новое представление памяти, но сам буфер не копируется. Поддерживаются преобразования 1D -> C-смежное и C-смежное -> 1D.

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

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

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

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

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

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

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

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

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

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

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

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

obj

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

>>> 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) каждого элемента представления. Представление памяти можно создать для экспортёров с произвольными строками формата, однако некоторые методы (например, tolist()) поддерживают только нативные одноэлементные форматы.

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

itemsize

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

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

ndim

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

shape

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

Изменено в версии 3.3: При 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.

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

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

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

len(dictview)

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

iter(dictview)

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

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

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

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

x in dictview

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

reversed(dictview)

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

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

dictview.mapping

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

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

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

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

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

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

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

Вызов 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]
  

• Необязательные типы можно записать как объединение с 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

Доступ к типу объекта объединения, доступному пользователю, можно получить через types.UnionType и использовать его для проверок isinstance(). Создать экземпляр этого типа нельзя:

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

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

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

Сноски