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

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

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

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

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

Примечания:

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, byteorder, *, 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 байтов. Если целое число не может быть представлено с заданным количеством байтов, то генерируется исключение OverflowError.

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

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

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

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

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

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

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

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

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

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

int.as_integer_ratio()

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

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

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

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

float.as_integer_ratio()

Возвращает пару целых чисел, отношение которых точно равно исходному float, и знаменатель которого положителен. Вызывает исключение 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)

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

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

Шестнадцатеричная строка имеет вид:

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

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

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

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

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

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

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

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

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

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

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

import sys, math

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

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

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

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

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

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

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

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

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

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

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

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

str.casefold()

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

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

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

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

str.center(width[, fillchar])

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

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

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

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

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

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

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

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

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

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

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

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

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

str.expandtabs(tabsize=8)

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

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

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

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

Примечание

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

>>> 'Py' in 'Python'
True

str.format(*args, **kwargs)

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

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

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

Примечание

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

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

str.format_map(mapping)

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

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

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

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

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

str.isalnum()

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

str.isalpha()

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

str.isascii()

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

Новая функция в версии 3.7.

str.isdecimal()

Возвращает True если все символы в строке являются десятичными и в строке есть хотя бы один символ, False в противном случае. Десятичные символы — это символы, которые могут использоваться для формирования чисел в системе счисления с основанием 10, например, U+0660, Арабская цифра ноль. Строго говоря, десятичный символ — это символ в Unicode-категории «Nd».

str.isdigit()

Возвращает True если все символы в строке являются цифрами и в строке есть хотя бы одна цифра, False в противном случае. Цифры включают десятичные символы и цифры, требующие специальной обработки, такие как цифры с верхним индексом. Это охватывает цифры, которые нельзя использовать для формирования чисел в системе счисления с основанием 10, например, цифры системы счисления Харошти. Строго говоря, цифра — это символ, у которого значение свойства Numeric_Type = Digit или 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 если все символы с регистром в строке находятся в нижнем регистре и в строке есть хотя бы один такой символ, False в противном случае.

str.isnumeric()

Возвращает True если все символы в строке являются числовыми, и в строке есть хотя бы один символ, False в противном случае. Числовые символы включают цифры и все символы, имеющие числовое значение Unicode, например, U+2155, обыкновенная дробь одна пятая. Строго говоря, числовые символы — это те, у которых значение свойства Numeric_Type = Digit, Numeric_Type = Decimal или Numeric_Type = Numeric.

str.isprintable()

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

str.isspace()

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

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

str.istitle()

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

str.isupper()

Возвращает True если все символы с регистром в строке находятся в верхнем регистре и в строке есть хотя бы один такой символ, 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()

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

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

str.lstrip([chars])

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

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

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

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

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

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

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

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

str.partition(sep)

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

str.removeprefix(prefix, /)

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

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

Новая функция в версии 3.9.

str.removesuffix(suffix, /)

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

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

Новая функция в версии 3.9.

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

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

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

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

str.rstrip([chars])

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

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

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

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

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

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

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

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

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

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

Например:

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

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

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

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

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

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

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

str.strip([chars])

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

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

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

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

str.swapcase()

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

str.title()

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

Например:

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

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

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

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

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

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

str.translate(table)

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

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

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

str.upper()

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

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

str.zfill(width)

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

Например:

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

printf-форматирование строк

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

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

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

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

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

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

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

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

Модификатор длины (h, 'd', или 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).

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

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

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

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

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

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

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

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

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

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

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

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

bytes.removeprefix(prefix, /)

bytearray.removeprefix(prefix, /)

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

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

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

Примечание

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

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

bytes.removesuffix(suffix, /)

bytearray.removesuffix(suffix, /)

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

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

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

Примечание

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

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

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

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

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

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

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

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

Примечание

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

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

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

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

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

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

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

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

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

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

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

Примечание

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

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

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

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

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

Аналогично find(), но вызывает ValueError при отсутствии подпоследовательности.

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

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

bytes.join(iterable)

bytearray.join(iterable)

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

static bytes.maketrans(from, to)

static bytearray.maketrans(from, to)

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

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

bytes.partition(sep)

bytearray.partition(sep)

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

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

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

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

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

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

Примечание

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

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

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

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

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

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

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

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

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

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

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

bytes.rpartition(sep)

bytearray.rpartition(sep)

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

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

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

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

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

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

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

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

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

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

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

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

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

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

bytes.center(width[, fillbyte])

bytearray.center(width[, fillbyte])

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

Примечание

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

bytes.ljust(width[, fillbyte])

bytearray.ljust(width[, fillbyte])

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

Примечание

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

bytes.lstrip([chars])

bytearray.lstrip([chars])

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

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

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

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

Примечание

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

bytes.rjust(width[, fillbyte])

bytearray.rjust(width[, fillbyte])

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

Примечание

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

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

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

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

bytes.rstrip([chars])

bytearray.rstrip([chars])

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

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

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

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

Примечание

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

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

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

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

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

Например:

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

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

Например:

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

bytes.strip([chars])

bytearray.strip([chars])

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

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

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

Примечание

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

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

bytes.capitalize()

bytearray.capitalize()

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

Примечание

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

bytes.expandtabs(tabsize=8)

bytearray.expandtabs(tabsize=8)

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

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

Примечание

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

bytes.isalnum()

bytearray.isalnum()

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

Например:

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

bytes.isalpha()

bytearray.isalpha()

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

Например:

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

bytes.isascii()

bytearray.isascii()

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

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

bytes.isdigit()

bytearray.isdigit()

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

Например:

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

bytes.islower()

bytearray.islower()

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

Например:

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

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

bytes.isspace()

bytearray.isspace()

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

bytes.istitle()

bytearray.istitle()

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

Например:

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

bytes.isupper()

bytearray.isupper()

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

Например:

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

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

bytes.lower()

bytearray.lower()

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

Например:

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

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

Примечание

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

bytes.splitlines(keepends=False)

bytearray.splitlines(keepends=False)

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

Например:

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

Например:

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

Примечание

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

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

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

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

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

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

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

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

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

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

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

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

Примечания:

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

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

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

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

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

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

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

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

class memoryview(object)

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

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

Возвращает данные в буфере в виде строки байтов. Это эквивалентно вызову конструктора 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()
[89, 98, 99]
>>> mm[0] = 42
Traceback (most recent call last):
  File "<stdin>", line 1, in <module>
TypeError: cannot modify read-only memory
>>> m[0] = 43
>>> mm.tolist()
[43, 98, 99]

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

release()

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

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

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

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

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

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

cast(format[, shape])

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

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

Преобразование 1D/long в 1D/unsigned bytes:

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

Преобразование 1D/unsigned bytes в 1D/char:

>>> b = bytearray(b'zyz')
>>> x = memoryview(b)
>>> x[0] = b'a'
Traceback (most recent call last):
  File "<stdin>", line 1, in <module>
ValueError: memoryview: invalid value for format "B"
>>> y = x.cast('c')
>>> y[0] = b'a'
>>> b
bytearray(b'ayz')

Преобразование 1D/bytes в 3D/ints в 1D/signed char:

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

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

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

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

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

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

obj

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

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

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

nbytes

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

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

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

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

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

readonly

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

format

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

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

itemsize

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

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

ndim

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

shape

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

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

strides

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

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

suboffsets

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

c_contiguous

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

Добавлено в версии 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'}

>>> # 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):
  File "<stdin>", line 1, in <module>
TypeError: There are no type variables left in dict[str]

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

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])
Traceback (most recent call last):
  File "<stdin>", line 1, in <module>
TypeError: isinstance() argument 2 cannot contain 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 | __main__.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).

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

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

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

Чтобы отформатировать только кортеж, необходимо предоставить кортеж-объект с единственным элементом — кортежем, который нужно отформатировать.