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

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

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

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

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

Примечания:

1. Отрицательные значения сдвига недопустимы и приводят к возникновению исключения ValueError.
2. Сдвиг влево на n бит эквивалентен умножению на pow(2, n) без проверки переполнения.
3. Сдвиг вправо на n бит эквивалентен делению на pow(2, n) без проверки переполнения.

4.4.2. Дополнительные методы для целых типов¶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() // 8) + 1, byteorder='little')
b'\xe8\x03'

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

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

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

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

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

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

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

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

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

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

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

4.4.3. Дополнительные методы для 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]

где необязательный знак может быть + или -, целая часть и дробная часть – строки шестнадцатеричных цифр, а порядок – десятичное целое с необязательным ведущим знаком. Регистр не имеет значения, и должна быть хотя бы одна шестнадцатеричная цифра либо в целой, либо в дробной части. Этот синтаксис похож на синтаксис, указанный в разделе 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'

4.4.4. Хеширование числовых типов¶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_ = sys.hash_info.inf
    else:
        # Малая теорема Ферма: pow(n, P-1, P) равно 1, поэтому
        # pow(n, P-2, P) даёт обратный элемент n по модулю P.
        hash_ = (abs(m) % P) * pow(n, P - 2, P) % P
    if m < 0:
        hash_ = -hash_
    if hash_ == -1:
        hash_ = -2
    return hash_

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_ = 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_ = (hash_ & (M - 1)) - (hash & M)
    if hash_ == -1:
        hash_ == -2
    return hash_

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

Python’s generators provide a convenient way to implement the iterator protocol. If a container object’s __iter__() method is implemented as a generator, it will automatically return an iterator object (technically, a generator object) supplying the __iter__() and __next__() methods. More information about generators can be found in the documentation for the yield expression.

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

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

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

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

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

Примечания:

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

   >>> "gg" in "eggs"
   True
   

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

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

   Произошло следующее: [[]] – это список из одного элемента, содержащий пустой список, поэтому все три элемента [[]] * 3 являются (указателями на) этот единственный пустой список. Модификация любого из элементов списков изменяет этот единственный список. Создать список из разных списков можно так:

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

3. Если i или j отрицательно, индекс отсчитывается от конца строки: подставляется len(s) + i или len(s) + j. Но обратите внимание, что -0 по-прежнему равно 0.

4. Срез s от i до j определяется как последовательность элементов с индексом k, таким что i <= k < j. Если i или j больше len(s), используется len(s). Если i опущено или равно None, используется 0. Если j опущено или равно None, используется len(s). Если i больше или равно j, срез пуст.

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

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

   • при конкатенации объектов str можно собрать список и в конце применить str.join(), либо записывать в экземпляр io.StringIO и получить его значение после завершения
   • при конкатенации объектов bytes можно аналогично использовать bytes.join() или io.BytesIO, либо выполнять конкатенацию на месте с объектом bytearray. Объекты bytearray изменяемы и имеют эффективный механизм предварительного выделения памяти
   • при конкатенации tuple-объектов лучше расширить список list
   • для других типов – изучите документацию соответствующего класса

7. Некоторые типы последовательностей (например, range) поддерживают только последовательности элементов, которые соответствуют определённым шаблонам, и поэтому не поддерживают конкатенацию или повторение последовательностей.

8. index возбуждает ValueError, если x не найден в s. Если поддерживается, дополнительные аргументы метода index позволяют эффективно искать в подотрезках последовательности. Передача дополнительных аргументов примерно эквивалентна использованию s[i:j].index(x), только без копирования данных и с возвращаемым индексом относительно начала последовательности, а не начала среза.

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

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

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

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

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

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

4.6.4. Списки¶Lists

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

class list([iterable])¶

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

• Используя пару квадратных скобок для обозначения пустого списка: []
• С использованием квадратных скобок, с разделением элементов запятыми: [a], [a, b, c]
• С помощью генератора списка: [x for x in iterable]
• С помощью конструктора типа: list() или list(iterable)

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

Многие другие операции также создают списки, включая встроенную функцию sorted().

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

sort(*, key=None, reverse=None)¶

Этот метод сортирует список на месте, используя только < сравнений между элементами. Исключения не подавляются – если какая-либо операция сравнения завершится ошибкой, вся сортировка завершится ошибкой (и список, скорее всего, останется в частично изменённом состоянии).

Метод sort() принимает два аргумента, которые могут передаваться только по ключу (аргументы только по ключу):

key указывает функцию одного аргумента, которая используется для извлечения ключа сравнения из каждого элемента списка (например, key=str.lower). Ключ, соответствующий каждому элементу списка, вычисляется один раз и затем используется для всего процесса сортировки. Значение по умолчанию None означает, что элементы списка сортируются напрямую, без вычисления отдельного ключа.

Утилита functools.cmp_to_key() доступна для преобразования функции cmp стиля 2.x в функцию key.

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

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

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

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

4.6.5. Кортежи¶Tuples

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

class tuple([iterable])¶

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

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

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

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

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

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

4.6.6. Диапазоны¶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.

Объект range будет пустым, если 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))
[]

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

The advantage of the range type over a regular list or tuple is that a range object will always take the same (small) amount of memory, no matter the size of the range it represents (as it only stores the start, stop and step values, calculating individual items and subranges as needed).

Объекты range реализуют абстрактный базовый класс collections.abc.Sequence и предоставляют такие возможности, как проверка вхождения, поиск индекса элемента, извлечение среза и поддержка отрицательных индексов (см. Sequence Types – 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

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

4.7.1. Методы строк¶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 (по умолчанию пробел).

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

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

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

str.format_map(mapping)¶

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

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

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

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

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

str.isalnum()¶

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

str.isalpha()¶

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

str.isdecimal()¶

Возвращает true, если все символы в строке являются десятичными символами и есть хотя бы один символ, иначе false. Десятичные символы относятся к общей категории «Nd». Эта категория включает цифры и все символы, которые можно использовать для формирования чисел с десятичным основанием, например U+0660, АРАБСКО-ИНДИЙСКАЯ ЦИФРА НОЛЬ.

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, VULGAR FRACTION ONE FIFTH. Формально числовые символы – это символы со значением свойства Numeric_Type=Digit, Numeric_Type=Decimal или Numeric_Type=Numeric.

str.isprintable()¶

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

str.isspace()¶

Возвращает true, если в строке есть только пробельные символы и есть хотя бы один символ, иначе false. Пробельные символы – это символы, определённые в базе данных символов Unicode как «Other» или «Separator», а также символы со свойством двунаправленности, являющимся одним из «WS», «B» или «S».

str.istitle()¶

Возвращает true, если строка является строкой в заглавном регистре (titlecased) и есть хотя бы один символ, например прописные символы могут следовать только за символами без регистра, а строчные – только за символами с регистром. Иначе возвращает false.

str.isupper()¶

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

str.join(iterable)¶

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

str.ljust(width[, fillchar])¶

Возвращает строку, выровненную по левому краю в строке длины width. Заполнение выполняется с помощью указанного символа fillchar (по умолчанию пробел). Исходная строка возвращается, если 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 (по умолчанию пробел). Исходная строка возвращается, если 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']). Разбиение пустой строки с указанным разделителем возвращает [''].

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

Например, ' 1 2 3 '.split()' возвращает ['1', '2', '3'], а ' 1 2 3 '.split(None, 1) возвращает ['1', '2   3  '].

str.splitlines([keepends])¶

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

Например, 'ab c\n\nde fg\rkl\r\n'.splitlines() возвращает ['ab c', '', 'de fg', 'kl'], а тот же вызов с splitlines(True) возвращает ['ab c\n', '\n', 'de fg\r', 'kl\r\n'].

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

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'

str.swapcase()¶

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

str.title()¶

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

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

>>> "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(map)¶

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

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

Примечание

Ещё более гибкий подход – создать собственный кодек отображения символов с помощью модуля codecs (см. encodings.cp1251 в качестве примера).

str.upper()¶

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

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

str.zfill(width)¶

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

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

У строковых объектов есть одна уникальная встроенная операция: оператор % (модуль). Он также известен как оператор форматирования 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. Альтернативная форма приводит к вставке ведущего нуля ('0') между левым заполнением и форматированным числом, если первый символ результата ещё не является нулём.

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

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

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

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

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

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

7. См. PEP 237.

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

4.8.1. Байты¶Bytes

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

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

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

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

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

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

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

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

4.8.2. Объекты bytearray¶Bytearray Objects

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

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

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

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

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

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

Из-за широкого использования ASCII-текста как основы двоичных протоколов объекты bytes и bytearray предоставляют почти все методы, имеющиеся у текстовых строк, за исключением:

• str.encode() (преобразует текстовые строки в объекты bytes)
• str.format() и str.format_map() (используются для форматирования текста для отображения пользователям)
• str.isidentifier(), str.isnumeric(), str.isdecimal(), str.isprintable() (используются для проверки различных свойств текстовых строк, которые обычно не применимы к двоичным протоколам).

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

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

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

Всякий раз, когда методу bytes или bytearray требуется интерпретировать байты как символы (например, методы is...(), split(), strip()), предполагается набор символов ASCII (текстовые строки используют семантику Unicode).

Операции поиска (in, count(), find(), index(), rfind() и rindex()) принимают как целые числа в диапазоне от 0 до 255 включительно, так и последовательности bytes и bytearray.

Каждый экземпляр bytes и bytearray предоставляет удобный метод decode(), являющийся обратным к str.encode():

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(); см. раздел Базовые классы кодеков. Список возможных кодировок – в разделе Стандартные кодировки.

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

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

classmethod bytes.fromhex(string)¶

classmethod bytearray.fromhex(string)¶

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

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

Методы maketrans и translate отличаются семантикой от версий, доступных для строк:

bytes.translate(table[, delete])¶

bytearray.translate(table[, delete])¶

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

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

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

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

static bytes.maketrans(from, to)¶

static bytearray.maketrans(from, to)¶

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

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

4.8.4. Представления памяти¶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 поддерживает срезы для доступа к своим данным. Если format является одним из собственных спецификаторов формата из модуля struct, то индексирование вернёт один элемент правильного типа. Полный срез вернёт подпредставление:

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

Другие собственные форматы:

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

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

Если базовый объект допускает запись, 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')

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

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

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

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

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

Изменено в версии 3.3: В предыдущих версиях сравнивалась необработанная память без учёта формата элемента и логической структуры массива.

tobytes()¶

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

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

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

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-непрерывный и C-непрерывный -> 1D.

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

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

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

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

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

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

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

Преобразовать 1D/unsigned char в 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.

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

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¶

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

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

f_contiguous¶

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

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

contiguous¶

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

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

4.10.1. Объекты-представления словаря¶Dictionary view objects

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

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

len(dictview)

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

iter(dictview)

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

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

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

x in dictview

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

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

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

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

>>> # итерация
>>> n = 0
>>> for val in values:
...     n += val
>>> print(n)
504

>>> # ключи и значения перебираются в одном и том же порядке
>>> list(keys)
['eggs', 'bacon', 'sausage', 'spam']
>>> list(values)
[2, 1, 1, 500]

>>> # объекты представления динамичны и отражают изменения словаря
>>> del dishes['eggs']
>>> del dishes['sausage']
>>> list(keys)
['spam', 'bacon']

>>> # операции над множествами
>>> keys & {'eggs', 'bacon', 'salad'}
{'bacon'}
>>> keys ^ {'sausage', 'juice'}
{'juice', 'sausage', 'bacon', 'spam'}

4.12.1. Модули¶Modules

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

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

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

4.12.2. Классы и экземпляры классов¶Classes and Class Instances

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

4.12.3. Функции¶Functions

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

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

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

4.12.4. Методы¶Methods

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

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

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

>>> class C:
...     def method(self):
...         pass
...
>>> c = C()
>>> c.method.whoami = 'my name is method'  # нельзя установить на методе
Traceback (most recent call last):
  File "<stdin>", line 1, in <module>
AttributeError: 'method' object has no attribute 'whoami'
>>> c.method.__func__.whoami = 'my name is method'
>>> c.method.whoami
'my name is method'

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

4.12.5. Объекты кода¶Code Objects

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

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

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

4.12.6. Объекты типов¶Type Objects

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

Типы записываются так: <class 'int'>.

4.12.7. Объект None¶The Null Object

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

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

4.12.8. Объект Ellipsis¶The Ellipsis Object

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

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

4.12.9. Объект NotImplemented¶The NotImplemented Object

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

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

4.12.10. Булевы значения¶Boolean Values

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

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

4.12.11. Внутренние объекты¶Internal Objects

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