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

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

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

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

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

Примечания:

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 используются в качестве хешей для положительной или отрицательной бесконечности (соответственно).
• Для комплексного числа 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 или используется отладочная сборка.

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

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

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

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

str.expandtabs(tabsize=8)

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

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

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

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

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

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

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

Подобно find(), но вызывает ValueError, когда подстрока не найдена.

str.isalnum()

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

str.isalpha()

Возвращает True , если все символы в строке являются буквенными и существует хотя бы один символ, False в противном случае. Буквенные символы — это символы, определённые в базе данных Unicode как «Буква», то есть те, у которых свойство общей категории является одним из «Lm», «Lt», «Lu», «Ll» или «Lo». Обратите внимание, что это отличается от свойства «Буквенный», определённого в разделе 4.10 «Буквы, буквенные и идеографические» стандарта Unicode.

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, например, цифры системы Кхарости. Формально, цифра — это символ, у которого значение свойства Numeric_Type равно Digit или Decimal.

str.isidentifier()

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

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

Пример:

>>> from keyword import iskeyword

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

str.islower()

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

str.isnumeric()

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

str.isprintable()

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

str.isspace()

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

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

str.istitle()

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

str.isupper()

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

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

str.join(iterable)

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

str.ljust(width[, fillchar])

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

str.lower()

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

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

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

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

Если есть два аргумента, они должны быть строками одинаковой длины, и в получившемся словаре каждый символ в x будет сопоставлен символу на той же позиции в y. Если есть третий аргумент, он должен быть строкой, символы которой будут сопоставлены с None в результате.

str.partition(sep)

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

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=-1)

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

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

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

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

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

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

str.rjust(width[, fillchar])

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

str.rpartition(sep)

Разделяет строку по последнему вхождению sep и возвращает кортеж из 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 or \x0b	Горизонтальная табуляция
\f or \x0c	Форматирование страницы
\x1c	Разделитель файлов
\x1d	Разделитель групп
\x1e	Разделитель записей
\u2028	Следующая строка (код управления C1)
\u2029	Разделитель строк
\x85	Разделитель абзацев

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

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

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

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

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

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

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

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

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

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

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

Примечания:

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

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

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

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

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

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

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

Объекты bytes

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

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

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

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

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

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

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

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

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

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

Поскольку 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).

Операции с объектами 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. См. removesuffix() для метода, который удалит одну строку-суффикс, а не все символы из набора. Например:

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

Примечание

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

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

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

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

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

Например:

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

Примечание

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

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

bytes.capitalize()

bytearray.capitalize()

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

Примечание

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

bytes.expandtabs(tabsize=8)

bytearray.expandtabs(tabsize=8)

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

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

Примечание

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

bytes.isalnum()

bytearray.isalnum()

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

Например:

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

bytes.isalpha()

bytearray.isalpha()

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

Например:

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

bytes.isascii()

bytearray.isascii()

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

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

bytes.isdigit()

bytearray.isdigit()

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

Например:

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

bytes.islower()

bytearray.islower()

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

Например:

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

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

bytes.isspace()

bytearray.isspace()

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

bytes.istitle()

bytearray.istitle()

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

Например:

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

bytes.isupper()

bytearray.isupper()

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

Например:

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

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

bytes.lower()

bytearray.lower()

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

Например:

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

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

Примечание

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

bytes.splitlines(keepends=False)

bytearray.splitlines(keepends=False)

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

Например:

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

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

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

bytes.swapcase()

bytearray.swapcase()

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

Например:

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

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

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

Примечание

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

bytes.title()

bytearray.title()

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

Например:

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

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

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

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

Решение для апострофов можно создать с помощью регулярных выражений:

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

Примечание

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

bytes.upper()

bytearray.upper()

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

Например:

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

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

Примечание

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

bytes.zfill(width)

bytearray.zfill(width)

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

Например:

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

Примечание

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

Форматирование байтовых объектов в стиле printf

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

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

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

1. Символ %, обозначающий начало спецификатора.
2. Ключ отображения (необязательный), представляющий собой заключённую в скобки последовательность символов (например, %s).
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 он не нужен – например, %d идентичен %d.

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

Примечания:

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

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

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

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

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

5. Если точность равна *, выходные данные усекаются до * символов.
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: memoryview теперь регистрируется автоматически с collections.abc.Sequence

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

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

__eq__(exporter)

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

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

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

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

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

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

Изменено в версии 3.3: Предыдущие версии сравнивали сырую память, не учитывая формат элементов и логическую структуру массива.

tobytes(order='C')

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

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

Для несмежных массивов результат равен представлению сглаженного списка со всеми элементами, преобразованными в bytes. 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])

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

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

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

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

Преобразование 1D/беззнаковых байтов в 1D/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/байтов в 3D/целые числа в 1D/знаковые байты:

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

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

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

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

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

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

obj

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

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

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

nbytes

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

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

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

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

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

readonly

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

format

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

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

itemsize

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

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

ndim

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

shape

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

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

strides

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

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

suboffsets

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

c_contiguous

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

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

f_contiguous

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

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

contiguous

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

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

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

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

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

len(dictview)

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

iter(dictview)

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

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

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

Изменено в версии 3.7: Порядок словарей гарантированно соответствует порядку вставки.

x in dictview

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

reversed(dictview)

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

Изменено в версии 3.8: Представления словарей теперь обратимы.

dictview.mapping

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

T[X, Y, ...]

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Однако, такие выражения допустимы, когда используются переменные типов. Индекс должен содержать столько элементов, сколько элементов переменных типа в 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'>.

Объект Null

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

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

Объект Ellipsis

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

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

Объект NotImplemented

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

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

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

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

Затронутые API

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

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

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

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

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

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

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

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

• sys.get_int_max_str_digits() и sys.set_int_max_str_digits() — это getter и setter для интерпретатора.

Сведения о значении по умолчанию и минимуме можно найти в 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.

Примечания