Встроенные типы¶Built-in Types

Побитовые операции над целыми типами¶Bitwise Operations on Integer Types

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

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

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

Примечания:

1. Отрицательные значения сдвига недопустимы и вызывают ValueError.

2. Сдвиг влево на n битов эквивалентен умножению на pow(2, n).

3. Сдвиг вправо на n битов эквивалентен целочисленному делению на pow(2, n).

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

Дополнительные методы для целых типов¶Additional Methods on Integer Types

Тип 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)       # двоичное представление:  bin(-37) --> '-0b100101'
    s = s.lstrip('-0b') # удалить ведущие нули и знак минус
    return len(s)       # len('100101') --> 6

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

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'

Целое число представляется с использованием длины байт. Исключение 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-подобным объектом, либо итерабельным объектом, производящим байты.

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

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

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

Дополнительные методы float¶Additional Methods on Float

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

float.as_integer_ratio()¶

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

float.is_integer()¶

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

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

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

float.hex()¶

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

classmethod float.fromhex(s)¶

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

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

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

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

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

Обратите внимание, что экспонента записывается в десятичном, а не шестнадцатеричном виде, и что она указывает степень двойки, на которую умножается коэффициент. Например, шестнадцатеричная строка 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'

Хеширование числовых типов¶Hashing of numeric types

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

• Для комплексного числа complex z хеши действительной и мнимой частей объединяются вычислением hash(z.real) + sys.hash_info.imag * hash(z.imag), приведённым по модулю 2**sys.hash_info.width так, чтобы результат находился в range(-2**(sys.hash_info.width - 1), 2**(sys.hash_info.width - 1)). Снова, если результат равен -1, он заменяется на -2.

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

import sys, math

def hash_fraction(m, n):
    """Вычислить хеш рационального числа m / n.

    Предполагается, что m и n – целые числа, n положительное.
    Эквивалентно hash(fractions.Fraction(m, n)).

    """
    P = sys.hash_info.modulus
    # Удалить общие делители P.  (Необязательно, если m и n уже взаимно просты.)
    while m % P == n % P == 0:
        m, n = m // P, n // P

    if n % P == 0:
        hash_value = sys.hash_info.inf
    else:
        # Малая теорема Ферма: pow(n, P-1, P) равно 1, поэтому
        # pow(n, P-2, P) даёт обратный элемент n по модулю 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):
    """Вычислить хеш числа с плавающей запятой x."""

    if math.isnan(x):
        return sys.hash_info.nan
    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):
    """Вычислить хеш комплексного числа z."""

    hash_value = hash_float(z.real) + sys.hash_info.imag * hash_float(z.imag)
    # выполнить знаковое приведение по модулю 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

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

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

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

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

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

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

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

Примечания:

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. The slice of s from i to j with step k is defined as the sequence of items with index x = i + n*k such that 0 <= n < (j-i)/k. In other words, the indices are i, i+k, i+2*k, i+3*k and so on, stopping when j is reached (but never including j). When k is positive, i and j are reduced to len(s) if they are greater. When k is negative, i and j are reduced to len(s) - 1 if they are greater. If i or j are omitted or None, they become “end” values (which end depends on the sign of k). Note, k cannot be zero. If k is None, it is treated like 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), но без копирования данных и с возвращаемым индексом относительно начала последовательности, а не начала среза.

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

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

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

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

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

В следующей таблице приведены операции, определённые для изменяемых типов последовательностей. 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).

   Новое в версии 3.3: clear() и copy() методы.

6. Значение n – целое число или объект, реализующий __index__(). Нулевые и отрицательные значения n очищают последовательность. Элементы последовательности не копируются; на них делаются множественные ссылки, как описано для s * n в разделе Общие операции с последовательностями.

Списки¶Lists

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

class list([iterable])¶

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

• Используя пару квадратных скобок для обозначения пустого списка: []

• Используя квадратные скобки, разделяя элементы запятыми: [a], [a, b, c]

• Используя списковое включение: [x for x in iterable]

• Используя конструктор типа: list() или list(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, если может обнаружить, что список был изменён во время сортировки.

Кортежи¶Tuples

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

class tuple([iterable])¶

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

• Используя пару круглых скобок для обозначения пустого кортежа: ()

• Используя завершающую запятую для кортежа из одного элемента: a, или (a,)

• Разделяя элементы запятыми: a, b, c или (a, b, c)

• Используя встроенную функцию tuple(): tuple() или tuple(iterable)

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

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

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

Для гетерогенных коллекций данных, где доступ по имени понятнее, чем доступ по индексу, collections.namedtuple() может быть более подходящим выбором, чем простой объект кортежа.

Диапазоны¶Ranges

Тип range представляет собой неизменяемую последовательность чисел и обычно используется для цикла с определённым числом итераций в циклах for.

class range(stop)¶

class range(start, stop[, step])

Аргументы конструктора range должны быть целыми числами (либо встроенными int, либо любым объектом, реализующим специальный метод __index__). Если аргумент step опущен, по умолчанию используется 1. Если аргумент start опущен, по умолчанию используется 0. Если step равен нулю, возбуждается ValueError.

Для положительного step содержимое диапазона r определяется формулой r[i] = start + step*i, где i >= 0 и r[i] < stop.

Для отрицательного step содержимое диапазона по-прежнему определяется формулой r[i] = start + step*i, но ограничениями являются i >= 0 и r[i] > stop.

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

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

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

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

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

start¶

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

stop¶

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

step¶

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

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

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

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

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

Методы строк¶String Methods

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

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

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

str.capitalize()¶

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

str.casefold()¶

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

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

Алгоритм casefolding описан в разделе 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 интерпретируются как в нотации срезов.

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

Возвращает закодированную версию строки в виде объекта bytes. Кодировка по умолчанию – 'utf-8'. Параметр errors может быть задан для выбора другой схемы обработки ошибок. По умолчанию для errors используется 'strict', что означает, что ошибки кодирования вызывают исключение UnicodeError. Другие возможные значения: 'ignore', 'replace', 'xmlcharrefreplace', 'backslashreplace', а также любое другое имя, зарегистрированное через codecs.register_error() (см. раздел Обработчики ошибок). Список возможных кодировок приведён в разделе Стандартные кодировки.

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

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

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

str.expandtabs(tabsize=8)¶

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

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

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

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

Примечание

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

>>> 'Py' in 'Python'
True

str.format(*args, **kwargs)¶

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

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

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

Примечание

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

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

str.format_map(mapping)¶

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

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

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

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

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

str.isalnum()¶

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

str.isalpha()¶

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

str.isascii()¶

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

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

str.isdecimal()¶

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

str.isdigit()¶

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

str.isidentifier()¶

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

Используйте keyword.iskeyword() для проверки зарезервированных идентификаторов, таких как def и class.

str.islower()¶

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

str.isnumeric()¶

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

str.isprintable()¶

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

str.isspace()¶

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

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

str.istitle()¶

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

str.isupper()¶

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

str.join(iterable)¶

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

str.ljust(width[, fillchar])¶

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

str.lower()¶

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

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

str.lstrip([chars])¶

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

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

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

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

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

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

str.partition(sep)¶

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

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

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.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])¶

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

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

Представление	Описание
\n	Перевод строки (LF)
\r	Возврат каретки (CR)
\r\n	Возврат каретки + перевод строки (CR+LF)
\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"

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

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

str.translate(table)¶

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

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

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

str.upper()¶

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

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

str.zfill(width)¶

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

Например:

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

Форматирование строк в стиле printf¶printf-style String Formatting

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

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

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

1. Символ '%', обозначающий начало спецификатора.

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

3. Флаги преобразования (необязательно), влияющие на результат для некоторых типов преобразования.

4. Минимальная ширина поля (необязательно). Если указана как '*' (звёздочка), то фактическая ширина берётся из следующего элемента кортежа в values, а преобразуемый объект следует после минимальной ширины поля и необязательной точности.

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

6. Модификатор длины (необязательно).

7. Тип преобразования.

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

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

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

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

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

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

Примечания:

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

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

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

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

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

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

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

6. См. PEP 237.

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

Объекты bytes¶Bytes Objects

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

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

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

• Одинарные кавычки: b'still allows embedded "double" quotes'

• Двойные кавычки: b"still allows embedded 'single' quotes".

• Тройные кавычки: b'''3 single quotes''', b"""3 double quotes"""

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

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

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

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

• Объект bytes, заполненный нулями заданной длины: bytes(10)

• Из итерируемого объекта целых чисел: bytes(range(20))

• Копирование существующих двоичных данных через буферный протокол: bytes(obj)

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

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

classmethod fromhex(string)¶

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

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

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

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

hex()¶

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

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

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

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

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

Объекты Bytearray¶Bytearray Objects

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

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

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

• Создание пустого экземпляра: bytearray()

• Создание экземпляра, заполненного нулями заданной длины: bytearray(10)

• Из итерируемого объекта целых чисел: bytearray(range(20))

• Копирование существующих двоичных данных через буферный протокол: bytearray(b'Hi!')

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

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

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

classmethod fromhex(string)¶

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

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

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

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

hex()¶

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

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

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

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

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

Операции с bytes и bytearray¶Bytes and Bytearray Operations

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

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

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

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

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

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

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

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

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

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

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

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

Возвращает строку, декодированную из переданных байтов. Кодировка по умолчанию – 'utf-8'. Параметр errors может быть задан для выбора другой схемы обработки ошибок. Значение по умолчанию для errors – 'strict', что означает, что ошибки кодирования вызывают исключение UnicodeError. Другие возможные значения: 'ignore', 'replace' и любое другое имя, зарегистрированное через codecs.register_error() (см. раздел Обработчики ошибок). Список возможных кодировок приведён в разделе Стандартные кодировки.

Примечание

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

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

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

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

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

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

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

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

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

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

Примечание

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

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

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

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

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

Как find(), но возбуждает ValueError, если подпоследовательность не найдена.

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

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

bytes.join(iterable)¶

bytearray.join(iterable)¶

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

static bytes.maketrans(from, to)¶

static bytearray.maketrans(from, to)¶

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

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

bytes.partition(sep)¶

bytearray.partition(sep)¶

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

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

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

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

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

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

Примечание

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

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

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

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

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

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

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

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

Действует как rfind(), но вызывает ValueError, если подпоследовательность sub не найдена.

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

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

bytes.rpartition(sep)¶

bytearray.rpartition(sep)¶

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

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

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

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

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

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

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'

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

Примечание

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

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

Примечание

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

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

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

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

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

Например:

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

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

Например:

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

bytes.strip([chars])¶

bytearray.strip([chars])¶

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

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

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

Примечание

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

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

bytes.capitalize()¶

bytearray.capitalize()¶

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

Примечание

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

bytes.expandtabs(tabsize=8)¶

bytearray.expandtabs(tabsize=8)¶

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

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

Примечание

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

bytes.isalnum()¶

bytearray.isalnum()¶

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

Например:

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

bytes.isalpha()¶

bytearray.isalpha()¶

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

Например:

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

bytes.isascii()¶

bytearray.isascii()¶

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

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

bytes.isdigit()¶

bytearray.isdigit()¶

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

Например:

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

bytes.islower()¶

bytearray.islower()¶

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

Например:

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

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

bytes.isspace()¶

bytearray.isspace()¶

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

bytes.istitle()¶

bytearray.istitle()¶

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

Например:

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

bytes.isupper()¶

bytearray.isupper()¶

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

Например:

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

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

bytes.lower()¶

bytearray.lower()¶

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

Например:

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

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

Примечание

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

bytes.splitlines(keepends=False)¶

bytearray.splitlines(keepends=False)¶

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

Например:

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

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

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

bytes.swapcase()¶

bytearray.swapcase()¶

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

Например:

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

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

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

Примечание

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

bytes.title()¶

bytearray.title()¶

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

Например:

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

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

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

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

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

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

Примечание

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

bytes.upper()¶

bytearray.upper()¶

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

Например:

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

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

Примечание

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

bytes.zfill(width)¶

bytearray.zfill(width)¶

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

Например:

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

Примечание

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

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

Объекты 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.

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

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

class memoryview(obj)¶

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

memoryview имеет понятие элемента, который является атомарной единицей памяти, обрабатываемой исходным объектом obj. Для многих простых типов, таких как 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, то также поддерживается индексация целым числом или кортежем целых чисел, которая возвращает отдельный элемент с правильным типом. Одномерные memoryview можно индексировать целым числом или кортежем из одного целого. Многомерные memoryview можно индексировать кортежами ровно из ndim целых чисел, где ndim – количество измерений. Нулевые memoryview можно индексировать пустым кортежем.

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

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

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

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

Одномерные memoryview хешируемых (только для чтения) типов с форматами ‘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: Одномерные memoryview теперь можно нарезать. Одномерные memoryview с форматами ‘B’, ‘b’ или ‘c’ теперь являются хешируемыми.

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

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

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

__eq__(exporter)¶

Memoryview и 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()¶

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

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

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

hex()¶

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

>>> m = memoryview(b"abc")
>>> m.hex()
'616263'

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

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, а также многомерные представления.

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])¶

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

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

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

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

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

>>> b = bytearray(b'zyz')
>>> x = memoryview(b)
>>> x[0] = b'a'
Traceback (most recent call last):
  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¶

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

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¶

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

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

f_contiguous¶

Логическое значение (bool), указывающее, является ли память непрерывной по Фортрану.

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

contiguous¶

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

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