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

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

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

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

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

Примечания:

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

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

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

int.bit_length()

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

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

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

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

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

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

int.bit_count()

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Примечания:

1. t должен иметь ту же длину, что и заменяемый срез.
2. Необязательный аргумент i по умолчанию равен -1, поэтому по умолчанию удаляется и возвращается последний элемент.
3. remove() вызывает исключение ValueError, если x не найден в s.
4. Метод reverse() изменяет последовательность на месте, чтобы экономить память при разворачивании длинной последовательности. Чтобы напомнить пользователям о побочном эффекте метода, он не возвращает развёрнутую последовательность.

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

   Добавлено в версии 3.3: методы clear() и copy().

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

Списки

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

class list([iterable])

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

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

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

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

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

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

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

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

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

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

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

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

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

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

start

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

stop

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

step

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

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

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

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

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

Методы строк

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

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

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

str.capitalize()

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

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

str.casefold()

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

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

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

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

str.center(width[, fillchar])

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

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

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

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

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

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

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

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

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

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

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

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

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

str.expandtabs(tabsize=8)

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

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

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

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

Примечание

Метод 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 или имеют длину больше одного байта, а локаль 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», определённого в стандарте Unicode.

str.isascii()

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

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

str.isdecimal()

Возвращает True, если все символы строки являются десятичными и строка содержит хотя бы один символ, и False в противном случае. Десятичные символы можно использовать для записи чисел в десятичной системе счисления, например U+0660 — АРАБСКО-ИНДИЙСКАЯ ЦИФРА НОЛЬ. Формально десятичный символ — это символ, относящийся к общей категории Unicode «Nd».

str.isdigit()

Возвращает True, если все символы строки являются цифрами и строка содержит хотя бы один символ, и False в противном случае. К цифрам относятся десятичные символы и цифры, требующие особой обработки, например совместимые надстрочные цифры. Сюда также входят цифры, которые нельзя использовать для записи чисел в десятичной системе счисления, например числа кхароштхи. Формально цифра — это символ, для которого значение свойства равно 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 — ОБЫКНОВЕННАЯ ДРОБЬ ОДНА ПЯТАЯ. Формально числовыми являются символы со значением свойства Numeric_Type=Digit, Numeric_Type=Decimal или Numeric_Type=Numeric.

str.isprintable()

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

str.isspace()

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

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

str.lstrip([chars])

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

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

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

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

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

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

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

Если заданы два аргумента, это должны быть строки одинаковой длины; в результирующем словаре каждому символу в x будет сопоставлен символ из y, находящийся на той же позиции. Если задан третий аргумент, это должна быть строка, символы которой будут сопоставлены с 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 и этот suffix не пуст, возвращает string[:-len(suffix)]. В противном случае возвращает копию исходной строки:

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

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

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

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

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

Возвращает наибольший индекс в строке, по которому найдена подстрока 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])

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

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

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

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

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

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

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

Например:

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

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

Например:

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

str.splitlines(keepends=False)

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

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

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

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

Например:

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

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

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

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

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

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

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

str.strip([chars])

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

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

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

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

str.swapcase()

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

str.title()

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

Например:

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

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

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

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

Другой способ обойти проблему с апострофами — использовать регулярные выражения:

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

str.translate(table)

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

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

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

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

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

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

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

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

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

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

Модификатор длины (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[, encoding[, errors]]])

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

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

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

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

Хотя литералы и представления bytes основаны на тексте 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([sep[, bytes_per_sep]])

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

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

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

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

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

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

Поскольку объекты 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[, encoding[, errors]]])

Для объектов 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([sep[, bytes_per_sep]])

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

bytes.removeprefix(prefix, /)

bytearray.removeprefix(prefix, /)

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

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

Значением prefix может быть любой объект, подобный bytes.

Примечание

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

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

bytes.removesuffix(suffix, /)

bytearray.removesuffix(suffix, /)

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

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

Значением suffix может быть любой объект, подобный bytes.

Примечание

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

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

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

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

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

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

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

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

Примечание

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

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

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

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

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

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

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

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

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

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

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

Примечание

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

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

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

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

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

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

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

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

bytes.join(iterable)

bytearray.join(iterable)

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

static bytes.maketrans(from, to)

static bytearray.maketrans(from, to)

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

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

bytes.partition(sep)

bytearray.partition(sep)

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

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

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

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

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

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

Примечание

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

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

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

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

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

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

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

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

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

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

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

bytes.rpartition(sep)

bytearray.rpartition(sep)

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

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

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

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

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

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

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

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

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

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

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

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

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

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

bytes.center(width[, fillbyte])

bytearray.center(width[, fillbyte])

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

Примечание

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

bytes.ljust(width[, fillbyte])

bytearray.ljust(width[, fillbyte])

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

Примечание

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

bytes.lstrip([chars])

bytearray.lstrip([chars])

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

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

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

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

Примечание

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

bytes.rjust(width[, fillbyte])

bytearray.rjust(width[, fillbyte])

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

Примечание

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

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

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

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

bytes.rstrip([chars])

bytearray.rstrip([chars])

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

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

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

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

Примечание

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

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

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

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

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

Например:

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

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

Например:

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

bytes.strip([chars])

bytearray.strip([chars])

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

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

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

Примечание

Версия этого метода для 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) имеют одну уникальную встроенную операцию: оператор % (остаток от деления). Он также известен как оператор форматирования или интерполяции bytes. При задании 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 = 0, длина равна 1. Если view.ndim = 1, длина равна числу элементов в представлении. Для большей размерности длина равна длине представления в виде вложенного списка. Атрибут itemsize возвращает число байтов в одном элементе.

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

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

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

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

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

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

>>> 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([sep[, bytes_per_sep]])

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

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

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

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

tolist()

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

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

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

toreadonly()

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

>>> m = memoryview(bytearray(b'abc'))
>>> mm = m.toreadonly()
>>> mm.tolist()
[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[, 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.

Представления ключей подобны множествам, поскольку их элементы уникальны и хешируемы. Если все значения хешируемы, так что пары (key, value) уникальны и хешируемы, то представление элементов также подобно множеству. (Представления значений не считаются подобными множествам, поскольку их элементы, как правило, не уникальны.) Для представлений, подобных множествам, доступны все операции, определённые для абстрактного базового класса 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 (встроенное имя). type(Ellipsis)() возвращает одиночный объект Ellipsis.

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

Объект NotImplemented

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

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

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

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

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

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

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

Затронутые API

Ограничение применяется только к потенциально медленным преобразованиям между int и str или bytes:

• int(string) с основанием по умолчанию 10.
• int(string, base) для всех оснований, не являющихся степенью 2.
• str(integer).
• repr(integer).
• любое другое преобразование строки в основание 10, например f"{integer}", "{}".format(integer) или b"%d" % integer.

Ограничения не применяются к функциям с линейным алгоритмом:

• int(string, base) с основанием 2, 4, 8, 16 или 32.
• int.from_bytes() и int.to_bytes().
• hex(), oct(), bin().
• Мини-язык спецификации формата для шестнадцатеричных, восьмеричных и двоичных чисел.
• Преобразование str в float.
• Преобразование str в decimal.Decimal.

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

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

• PYTHONINTMAXSTRDIGITS, например PYTHONINTMAXSTRDIGITS=640 python3, чтобы установить ограничение в 640, или PYTHONINTMAXSTRDIGITS=0 python3, чтобы отключить ограничение.
• -X int_max_str_digits, например python3 -X int_max_str_digits=640
• sys.flags.int_max_str_digits содержит значение PYTHONINTMAXSTRDIGITS или -X int_max_str_digits. Если заданы и переменная окружения, и параметр -X, приоритет имеет параметр -X. Значение -1 означает, что оба параметра не были заданы и при инициализации использовалось значение sys.int_info.default_max_str_digits.

Из кода можно проверить текущее ограничение и задать новое с помощью следующих API модуля sys:

• sys.get_int_max_str_digits() и sys.set_int_max_str_digits() — функции получения и установки ограничения для всего интерпретатора. У подинтерпретаторов собственное ограничение.

Сведения о значении по умолчанию и минимальном значении приведены в sys.int_info:

• sys.int_info.default_max_str_digits — ограничение, заданное по умолчанию при компиляции.
• sys.int_info.str_digits_check_threshold — наименьшее допустимое значение ограничения (кроме 0, отключающего его).

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

Значение по умолчанию sys.int_info.default_max_str_digits считается подходящим для большинства приложений. Если приложению требуется другое ограничение, задайте его в основной точке входа, используя код, не зависящий от версии Python, поскольку эти API были добавлены в выпусках исправлений безопасности для версий до 3.11.

Пример:

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

Сноски