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

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

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

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

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

Примечания:

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

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

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

int.bit_length()

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

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

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

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

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

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

int.bit_count()

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

    return n

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

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

int.as_integer_ratio()

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

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

int.is_integer()

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

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

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

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

float.as_integer_ratio()

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

float.is_integer()

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

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

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

float.hex()

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

classmethod float.fromhex(s)

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

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

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

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

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

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

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

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

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

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

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

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

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

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

import sys, math

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Примечания:

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

   >>> "gg" in "eggs"
   True
   

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Примечания:

1. Если k не равен 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 считаются равными, если они представляют одну и ту же последовательность значений. (Обратите внимание, что атрибуты start, stop и step у двух равных объектов range могут различаться, например range(0) == range(2, 1, 3) или range(0, 3, 2) == range(0, 4, 2).)

Методы строк

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

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

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

str.capitalize()

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

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

str.casefold()

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

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

Алгоритм свёртки регистра описан в разделе 3.13 «Свёртка регистра по умолчанию» стандарта 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, определённого в разделе 4.10 «Буквы, алфавитные и идеографические символы» стандарта Unicode.

str.isascii()

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

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

str.isdecimal()

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

str.isdigit()

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

str.isidentifier()

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

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

Пример:

>>> from keyword import iskeyword

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

str.islower()

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

str.isnumeric()

Возвращает True, если все символы строки являются числовыми и строка содержит хотя бы один символ, и False в противном случае. К числовым символам относятся цифры и все символы, имеющие свойство числового значения Unicode, например U+2155, ОБЫКНОВЕННАЯ ДРОБЬ ОДНА ПЯТАЯ. Формально числовыми являются символы со значением свойства Numeric_Type=Digit, Numeric_Type=Decimal или Numeric_Type=Numeric.

str.isprintable()

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

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

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

str.isspace()

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

Символ считается пробельным, если в базе данных символов Unicode (см. unicodedata) его общая категория равна Zs («Разделитель, пробел») либо его класс двунаправленности имеет одно из значений 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 может состоять из нескольких символов, которые рассматриваются как один разделитель (для разбиения по нескольким разделителям используйте re.split()). Разбиение пустой строки с заданным разделителем возвращает [''].

Например:

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

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

Например:

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

str.splitlines(keepends=False)

Возвращает список строк, разделяя исходную строку по границам строк. Переводы строк не включаются в результирующий список, если только не задано значение true для аргумента 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__(); обычно это отображение или последовательность. При индексировании по порядковому номеру Юникода (целому числу) объект таблицы может выполнить одно из следующих действий: вернуть порядковый номер Юникода или строку, преобразовав символ в один или несколько других символов; вернуть None, удалив символ из возвращаемой строки; или вызвать исключение LookupError, оставив символ без изменений.

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

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

str.upper()

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

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

str.zfill(width)

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

Например:

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

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

У строковых объектов есть одна уникальная встроенная операция: оператор % (остаток от деления). Он также известен как оператор форматирования или интерполяции строк. Для 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]]])

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

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

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

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

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

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

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

См. также встроенный тип bytes.

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

classmethod fromhex(string)

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

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

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

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

hex([sep[, bytes_per_sep]])

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

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

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

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

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

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

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

Для представления объектов bytes используется формат литералов (b'...'), поскольку он часто удобнее, чем, например, bytes([46, 46, 46]). Байтовый объект всегда можно преобразовать в список целых чисел с помощью 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. Если в iterable есть значения, которые не являются bytes-подобными объектами, в том числе объекты str, возникает исключение TypeError. Разделителем между элементами служит содержимое объекта bytes или bytearray, у которого вызван этот метод.

static bytes.maketrans(from, to)

static bytearray.maketrans(from, to)

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

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

bytes.partition(sep)

bytearray.partition(sep)

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

Например:

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

Если sep не указан или равен None, применяется другой алгоритм разбиения: последовательности идущих подряд пробельных символов ASCII считаются одним разделителем, а если в начале или конце последовательности есть пробельные символы, результат не будет содержать пустых строк в начале или конце. Поэтому разбиение пустой последовательности или последовательности, состоящей только из пробельных символов 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 = 1, это равно количеству элементов в представлении.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

__eq__(exporter)

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

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

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

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

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

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

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

tobytes(order='C')

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

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

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

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

hex([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.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

T[X, Y, ...]

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

X | Y | ...

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

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

Примечание

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

union_object == other

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

• Вложенные объединения объединяются в одно:

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

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

  int | str | int == int | str
  

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

  int | str == str | int
  

• Объединение совместимо с typing.Union:

  int | str == typing.Union[int, str]
  

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

  str | None == typing.Optional[str]
  

isinstance(obj, union_object)

issubclass(obj, union_object)

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

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

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

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

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

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

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

Модули

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

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

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

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

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

Функции

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

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

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

Методы

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

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

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

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

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

Объекты кода

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

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

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

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

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

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

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

Объект Null

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

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

Объект Ellipsis

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

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

Объект NotImplemented

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

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

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

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

Затронутые API

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

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

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

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

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

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

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

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

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

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

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

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

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

Пример:

>>> import sys
>>> if hasattr(sys, "set_int_max_str_digits"):
...     upper_bound = 68000
...     lower_bound = 4004
...     current_limit = sys.get_int_max_str_digits()
...     if current_limit == 0 or current_limit > upper_bound:
...         sys.set_int_max_str_digits(upper_bound)
...     elif current_limit < lower_bound:
...         sys.set_int_max_str_digits(lower_bound)

Чтобы полностью отключить ограничение, задайте значение 0.

Сноски