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

Битовые операции над целочисленными типами

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

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

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

Примечания:

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 для бесконечных значений и ValueError для NaN.

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-кода, эквивалентного встроенному хэшу, для вычисления хэша рационального числа, float, или complex:

import sys, math

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Примечания:

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

   >>> "gg" in "eggs"
   True
   

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

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

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

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

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

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

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

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

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

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

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

Примеры сортировки и краткий учебник по сортировке см. в разделе Методы сортировки.

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

Кортежи

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

class tuple([iterable])

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

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

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

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

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

Для гетерогенных коллекций данных, где доступ по имени понятнее, чем доступ по индексу, 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.

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

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

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

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

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

start

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

stop

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

step

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

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

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

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

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

Методы строк

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

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

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

str.capitalize()

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

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

str.casefold()

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

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

Алгоритм приведения к нижнему регистру описан в разделе 3.13 «По умолчанию Приведение к нижнему регистру» стандарта Юникод.

Добавлен в версии 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 Режим разработки Python или используется отладочная сборка.

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

Изменено в версии 3.9: Значение аргумента errors теперь проверяется в режиме разработки Python Режим разработки 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 интерпретируются так же, как в нотации срезов. Возвращает -1 если sub не найдена.

Примечание

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

>>> 'Py' in 'Python'
True

str.format(*args, **kwargs)

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

>>> "The sum of 1 + 2 is {0}".format(1+2)
'The sum of 1 + 2 is 3'

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

Примечание

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

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

str.format_map(mapping)

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

>>> 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 в противном случае. Буквенные символы — это те символы, определённые в базе данных символов Юникода как «Буква», т. е. те, у которых свойство общей категории равно одному из «Lm», «Lt», «Lu», «Ll» или «Lo». Обратите внимание, что это отличается от свойства «Буквенного» символа, определённого в разделе 4.10 «Буквы, буквенные и идеографические» стандарта Юникода.

str.isascii()

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

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

str.isdecimal()

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

str.isdigit()

Возвращает True , если все символы в строке являются цифрами, и в строке есть хотя бы один символ, False в противном случае. Цифры включают в себя десятичные символы и цифры, требующие специальной обработки, например, совместимые цифровые надстрочные знаки. Это охватывает цифры, которые нельзя использовать для образования чисел в системе счисления по основанию 10, например, цифры системы Кхароштхи. Строго говоря, цифра — это символ, у которого значение свойства «Числовой тип» равно «Цифра» или «Десятичный».

str.isidentifier()

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

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

Пример:

>>> from keyword import iskeyword

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

str.islower()

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

str.isnumeric()

Возвращает True , если все символы в строке являются числовыми символами, и в строке есть хотя бы один символ, False в противном случае. Числовые символы включают в себя цифровые символы и все символы, имеющие свойство числового значения Юникода, например, U+2155, ОБЫЧНАЯ ДРОБЬ ОДНА ПЯТАЯ. Строго говоря, числовые символы — это те, у которых значение свойства «Числовой тип» равно «Цифра», «Десятичный» или «Числовой».

str.isprintable()

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

str.isspace()

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

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

str.istitle()

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

str.isupper()

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

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

str.join(iterable)

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

str.ljust(width[, fillchar])

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

str.lower()

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

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

str.lstrip([chars])

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

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

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

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

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

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

Если аргументов один, он должен быть словарем, сопоставляющим коды Юникода (целые числа) или символы (строки длиной 1) с кодами Юникода, строками (любой длины) или 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 найдена, при условии, что sub содержится в s[start:end]. Необязательные аргументы start и end интерпретируются так же, как в обозначении срезов. В случае неудачи возвращает -1.

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

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

str.rjust(width[, fillchar])

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

str.rpartition(sep)

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

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

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

str.rstrip([chars])

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

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

См. str.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)

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

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

Представление	Описание
\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 по умолчанию удаляет пробелы. Аргумент 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-форматирование строк

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

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

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

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

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

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

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

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

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

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

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

classmethod fromhex(string)

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

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

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

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

hex([sep[, bytes_per_sep]])

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Поскольку 2 шестнадцатеричные цифры точно соответствуют одному байту, шестнадцатеричные числа являются часто используемым форматом для описания двоичных данных. Соответственно, тип 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 использует формат литералов bytes (bytearray(b'...')) поскольку он часто более удобен, чем, например, bytearray([46, 46, 46]). Вы всегда можете преобразовать объект bytearray в список целых чисел с помощью list(b).

Операции с объектами bytes и bytearray

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

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-like или целым числом в диапазоне от 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-like.

Примечание

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

Примечание

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

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

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

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

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

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

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

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

Примечание

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

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

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

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

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

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

bytes.join(iterable)

bytearray.join(iterable)

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

static bytes.maketrans(from, to)

static bytearray.maketrans(from, to)

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

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

bytes.partition(sep)

bytearray.partition(sep)

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

Разделитель может быть любым объектом типа bytes-like.

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

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

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

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

Примечание

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

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

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

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

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

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

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

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

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

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

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

bytes.rpartition(sep)

bytearray.rpartition(sep)

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

Разделитель может быть любым объектом типа bytes-like.

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

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

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

Префикс(ы) для поиска может быть любым объектом типа bytes-like.

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-символами. Если опущен или None, аргумент chars по умолчанию удаляет ASCII-пробелы. Аргумент chars не является префиксом; скорее, удаляются все сочетания его значений:

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

Бинарная последовательность значений байтов для удаления может быть любым объектом типа bytes-like. См. 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. Если он опущен или None, аргумент chars по умолчанию удаляет пробельные символы ASCII. Аргумент chars не является суффиксом; вместо этого удаляются все комбинации его значений:

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

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

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

Note

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

Например:

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

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

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

Note

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

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

bytes.capitalize()

bytearray.capitalize()

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

Note

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

Note

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

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

Примечание

Версия метода для типа 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-цифрами до длины width. Префикс знака (b'+'/ b'-') обрабатывается вставкой заполнения после символа знака, а не перед ним. Для объектов bytes исходная последовательность возвращается, если width меньше или равно len(seq).

Например:

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

Примечание

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

printf-стиль форматирования байтовых объектов

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

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

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

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

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

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

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

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

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

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

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

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

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

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

cast(format[, shape])

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

Базовый объект memoryview:

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

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

nbytes

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

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

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

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

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

readonly

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

format

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

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

itemsize

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

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

ndim

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

shape

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

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

strides

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

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

suboffsets

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

c_contiguous

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

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

f_contiguous

Булево значение, указывающее, является ли память Fortran contiguous.

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

contiguous

Булево значение, указывающее, является ли память 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

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

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

Объект None

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

Примечания