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

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

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

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

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

Примечания:

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

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

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

int.bit_length()

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

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

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

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

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

Введено в версии 3.1.

int.bit_count()

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

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

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

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

Введено в версии 3.10.

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

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

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

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

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

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

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

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

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

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

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

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

Введено в версии 3.2.

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

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

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

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

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

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

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

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

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

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

    return n

Введено в версии 3.2.

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

int.as_integer_ratio()

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

Введено в версии 3.8.

Дополнительные методы для Float

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

float.as_integer_ratio()

Возвращает пару целых чисел, чьё отношение точно равно исходному числу с плавающей точкой и положительным знаменателем. Вызывает OverflowError для бесконечностей и 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, и шестнадцатеричные строки, созданные форматом C %a или форматом Java Double.toHexString принимаются float.fromhex().

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

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

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

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

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

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

Вот правила более подробно:

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

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

import sys, math

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

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

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

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

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

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

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

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

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

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

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

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

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

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

str.casefold()

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

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

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

Введено в версии 3.3.

str.center(width[, fillchar])

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

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

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

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

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

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

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

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

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

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

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

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

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

str.expandtabs(tabsize=8)

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

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

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

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

Примечание

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

>>> 'Py' in 'Python'
True

str.format(*args, **kwargs)

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

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

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

Примечание

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

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

str.format_map(mapping)

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

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

Введено в версии 3.2.

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

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

str.isalnum()

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

str.isalpha()

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

str.isascii()

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

Новое в версии 3.7.

str.isdecimal()

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

str.isdigit()

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

str.isidentifier()

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

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

Пример:

>>> from keyword import iskeyword

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

str.islower()

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

str.isnumeric()

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

str.isprintable()

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

str.isspace()

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

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

str.istitle()

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

str.isupper()

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

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

str.join(iterable)

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

str.ljust(width[, fillchar])

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

str.lower()

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

Алгоритм приведения к нижнему регистру описан в разделе 3.13 Стандарта Юникода.

str.lstrip([chars])

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

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

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

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

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

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

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

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

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

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

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

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

str.rjust(width[, fillchar])

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

str.rpartition(sep)

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

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

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

str.rstrip([chars])

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

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

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

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

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

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

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

Например:

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

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

Например:

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

str.splitlines(keepends=False)

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

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

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

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

Например:

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

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

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

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

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

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

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

str.strip([chars])

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

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

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

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

str.swapcase()

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

str.title()

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

Например:

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

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

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

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

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

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

str.translate(table)

Возвращает копию строки, в которой каждый символ отображается с помощью заданной таблицы трансляции. Таблица должна быть объектом, реализующим индексирование с помощью __getitem__(), как правило, отображение или последовательность. При индексировании по порядковому номеру Unicode (целое число), объект таблицы может выполнить одно из следующих действий: вернуть порядковый номер Unicode или строку, чтобы отобразить символ на один или несколько других символов; вернуть None, чтобы удалить символ из возвращаемой строки; или вызвать исключение LookupError, чтобы отобразить символ на себя.

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

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

str.upper()

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

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

str.zfill(width)

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

Например:

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

printf-стиль форматирования строк

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

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

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

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

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

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

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

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

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

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

classmethod fromhex(string)

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

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

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

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

hex([sep[, bytes_per_sep]])

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

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

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

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

Введено в версии 3.5.

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

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

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

Объекты bytearray

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

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

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

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

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

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

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

classmethod fromhex(string)

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

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

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

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

hex([sep[, bytes_per_sep]])

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

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

Введено в версии 3.5.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

bytes.removeprefix(prefix, /)

bytearray.removeprefix(prefix, /)

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

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

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

Примечание

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

Введено в версии 3.9.

bytes.removesuffix(suffix, /)

bytearray.removesuffix(suffix, /)

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

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

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

Примечание

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

Введено в версии 3.9.

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

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

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

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

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

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

Примечание

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

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

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

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

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

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

Суффикс(ы) для поиска может быть любым объектом-подобным байтам.

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

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

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

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

Примечание

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

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

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

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

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

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

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

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

bytes.join(iterable)

bytearray.join(iterable)

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

static bytes.maketrans(from, to)

static bytearray.maketrans(from, to)

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

Введено в версии 3.1.

bytes.partition(sep)

bytearray.partition(sep)

Разделить последовательность на первой встреченной подпоследовательности sep и вернуть кортеж из 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 — двоичная последовательность, определяющая набор значений байтов для удаления. Если опущено или 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'

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

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

Примечание

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

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

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

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

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

Например:

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

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

Например:

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

bytes.strip([chars])

bytearray.strip([chars])

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

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

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

Примечание

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

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

bytes.capitalize()

bytearray.capitalize()

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

Примечание

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

bytes.expandtabs(tabsize=8)

bytearray.expandtabs(tabsize=8)

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

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

Примечание

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

bytes.isalnum()

bytearray.isalnum()

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

Например:

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

bytes.isalpha()

bytearray.isalpha()

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

Например:

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

bytes.isascii()

bytearray.isascii()

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

Введено в версии 3.7.

bytes.isdigit()

bytearray.isdigit()

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

Например:

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

bytes.islower()

bytearray.islower()

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

Например:

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

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

bytes.isspace()

bytearray.isspace()

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

bytes.istitle()

bytearray.istitle()

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

Например:

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

bytes.isupper()

bytearray.isupper()

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

Например:

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

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

bytes.lower()

bytearray.lower()

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

Например:

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

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

Примечание

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

bytes.splitlines(keepends=False)

bytearray.splitlines(keepends=False)

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

Например:

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

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

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

bytes.swapcase()

bytearray.swapcase()

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

Например:

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

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

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

Примечание

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

bytes.title()

bytearray.title()

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

Например:

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

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

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

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

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

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

Примечание

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

bytes.upper()

bytearray.upper()

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

Например:

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

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

Примечание

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

bytes.zfill(width)

bytearray.zfill(width)

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

Например:

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

Примечание

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

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

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

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

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

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

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

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

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

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

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

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

Примечания:

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

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

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

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

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

5. Если точность N, вывод усекается до N символов.
6. b'%s' устарел, но не будет удалён в серии 3.x.
7. b'%r' устарел, но не будет удалён в серии 3.x.
8. См. PEP 237.

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

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

class memoryview(object)

Создайте memoryview, ссылающийся на object. object должен поддерживать протокол буфера. Встроенные объекты, которые поддерживают протокол буфера, включают bytes и bytearray.

У memoryview есть понятие элемента, которое представляет собой атомную единицу памяти, обрабатываемую исходным объектом. Для многих простых типов, таких как bytes и bytearray, элемент — это один байт, но другие типы, такие как array.array, могут иметь более крупные элементы.

len(view) равно длине tolist. Если view.ndim = 0, длина равна 1. Если view.ndim = 1, длина равна количеству элементов в представлении. Для многомерных представлений длина равна длине вложенного списка, представляющего представление. Атрибут itemsize укажет количество байтов в одном элементе.

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

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

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

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

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

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

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

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

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

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

Изменено в версии 3.4: Теперь представление памяти автоматически регистрируется в 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'

Для несмежных массивов результат равен уплощенному списку с преобразованием всех элементов в байты. 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/символы:

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

Основной объект memoryview:

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

Введено в версии 3.3.

nbytes

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

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

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

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

Введено в версии 3.3.

readonly

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

format

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

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

itemsize

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

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

ndim

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

shape

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

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

strides

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

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

suboffsets

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

c_contiguous

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

Введено в версии 3.3.

f_contiguous

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

Введено в версии 3.3.

contiguous

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

Введено в версии 3.3.

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

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

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

len(dictview)

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

iter(dictview)

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

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

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

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

x in dictview

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

reversed(dictview)

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

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

dictview.mapping

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

Введено в версии 3.10.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

T[X, Y, ...]

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

X | Y | ...

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

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

Примечание

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

union_object == other

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

• Объединения объединений сглаживаются:

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

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

  int | str | int == int | str
  

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

  int | str == str | int
  

• Это совместимо с typing.Union:

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

• Типы по умолчанию могут быть записаны как объединение с None:

  str | None == typing.Optional[str]
  

isinstance(obj, union_object)

issubclass(obj, union_object)

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

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

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

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

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

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

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

Модули

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

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

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

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

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

Функции

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

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

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

Методы

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

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

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

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

Дополнительную информацию см. в Методах экземпляров.

Объекты кода

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

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

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

См. Стандартную иерархию типов для получения дополнительной информации.

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

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

Типы записываются следующим образом: <class 'int'>.

Объект NULL

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

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

Объект Эллипсис

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

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

Объект NotImplemented

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

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

Булевы значения

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

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

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

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

Затронутые API

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

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

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

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

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

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

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

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

• sys.get_int_max_str_digits() и sys.set_int_max_str_digits() являются функциями получения и установки интерпретаторского ограничения. Дочерние интерпретаторы имеют свои собственные ограничения.

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

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

Рекомендуемая настройка

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

Пример:

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

Если вам нужно полностью отключить ограничение, установите его в значение 0.

Примечания

1

Дополнительную информацию об этих специальных методах можно найти в Руководстве по Python (Основная настройка).

2

Следовательно, список [1, 2] считается равным [1.0, 2.0], и аналогично для кортежей.

3

Так как анализатор не может определить тип операндов.

4(1,2,3,4)

Это символы, у которых свойство общей категории равно «Lu» (буква, заглавная), «Ll» (буква, строчная) или «Lt» (буква, заголовок).

5(1,2)

Для форматирования только кортежа необходимо предоставить кортеж-объект с кортежем как единственным элементом.