Встроенные типы¶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.bit_count()¶

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

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

Эквивалентно следующему:

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

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

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

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

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

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

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

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

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

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

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

Эквивалентно следующему:

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

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

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

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

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

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

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

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

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

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

Эквивалентно следующему:

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

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

    return n

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

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

int.as_integer_ratio()¶

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

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

int.is_integer()¶

Возвращает True. Существует для совместимости с утиной типизацией с float.is_integer().

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

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

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

classmethod float.from_number(x)¶

Метод класса, возвращающий число с плавающей запятой, построенное из числа x.

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

Для произвольного объекта Python x, float.from_number(x) делегирует вызов x.__float__(). Если __float__() не определён, то используется __index__().

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

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'

Дополнительные методы для complex¶Additional Methods on Complex

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

classmethod complex.from_number(x)¶

Метод класса для преобразования числа в комплексное число.

Для обычного объекта Python x метод complex.from_number(x) делегирует вызов x.__complex__(). Если __complex__() не определён, то используется __float__(). Если __float__() не определён, то используется __index__().

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

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

• Для комплексного числа 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 object.__hash__(x)
    elif math.isinf(x):
        return sys.hash_info.inf if x > 0 else -sys.hash_info.inf
    else:
        return hash_fraction(*x.as_integer_ratio())

def hash_complex(z):
    """Вычислить хеш комплексного числа 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 в справочнике по языку.)

Прямые и обратные итераторы по изменяемым последовательностям обращаются к значениям по индексу. Этот индекс будет продолжать двигаться вперёд (или назад), даже если базовая последовательность изменяется. Итератор завершается только при возникновении IndexError или StopIteration (или когда индекс становится меньше нуля).

Примечания:

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

   >>> "gg" in "eggs"
   True
   

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

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

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

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

   Подробное объяснение доступно в разделе FAQ Как создать многомерный список?.

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

4. Срез последовательности s от i до j определяется как последовательность элементов с индексом k, для которых выполняется i <= k < j.

   • Если i опущено или равно None, используется 0.

   • Если j опущено или равно None, используется len(s).

   • Если i или j меньше -len(s), используется 0.

   • Если i или j больше len(s), используется 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. Исключение IndexError возникает, если i выходит за пределы диапазона последовательности.

Методы последовательностей

Типы последовательностей также поддерживают следующие методы:

sequence.count(value, /)¶

Возвращает общее количество вхождений value в последовательности sequence.

sequence.index(value[, start[, stop]])¶

Возвращает индекс первого вхождения value в последовательности sequence.

Вызывает ValueError, если value не найден в sequence.

Аргументы start и stop позволяют эффективно искать подпоследовательности, начиная с start и заканчивая stop. Это примерно эквивалентно start + sequence[start:stop].index(value), но без копирования данных.

Внимание

Не все типы последовательностей поддерживают передачу аргументов start и stop.

Неизменяемые типы последовательностей¶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. Если k не равно 1, то t должно иметь ту же длину, что и заменяемый срез.

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

Методы изменяемых последовательностей

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

sequence.append(value, /)¶

Добавляет value в конец последовательности. Это равносильно записи seq[len(seq):len(seq)] = [value].

sequence.clear()¶

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

Удаляет все элементы из sequence. Это равносильно записи del sequence[:].

sequence.copy()¶

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

Создаёт поверхностную копию sequence. Это равносильно записи sequence[:].

Подсказка

Метод copy() не является частью MutableSequence ABC, но большинство конкретных изменяемых типов последовательностей его предоставляют.

sequence.extend(iterable, /)¶

Расширяет sequence содержимым iterable. В основном это то же самое, что запись seq[len(seq):len(seq)] = iterable.

sequence.insert(index, value, /)¶

Вставляет value в sequence по указанному index. Это равносильно записи sequence[index:index] = [value].

sequence.pop(index=-1, /)¶

Извлекает элемент по index и также удаляет его из sequence. По умолчанию удаляется и возвращается последний элемент sequence.

sequence.remove(value, /)¶

Удаляет первый элемент из sequence, для которого sequence[i] == value.

Вызывает ValueError, если value не найден в sequence.

sequence.reverse()¶

Изменяет порядок элементов sequence на обратный на месте. Этот метод обеспечивает экономию памяти при обращении большой последовательности. Чтобы напомнить пользователям, что он работает с побочным эффектом, он возвращает None.

Списки¶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)) – это вызов функции с одним аргументом – кортежем из трёх элементов.

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

Кортежи являются обобщёнными по типам своего содержимого. Для получения дополнительной информации обратитесь к документации по typing, посвящённой аннотированию кортежей.

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

Диапазоны¶Ranges

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

class range(stop, /)¶

class range(start, stop, step=1, /)

Аргументы конструктора 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()¶

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

Изменено в версии 3.8: Первый символ теперь переводится в регистр заголовка (titlecase) вместо заглавного. Это означает, что символы типа диграфов будут иметь заглавной только первую букву, а не весь символ.

str.casefold()¶

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

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

>>> 'straße'.lower()
'straße'
>>> 'straße'.casefold()
'strasse'

Алгоритм регистронезависимого сравнения описан в разделе 3.13 «Default Case Folding» стандарта Unicode.

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

str.center(width, fillchar=' ', /)¶

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

>>> 'Python'.center(10)
'  Python  '
>>> 'Python'.center(10, '-')
'--Python--'
>>> 'Python'.center(4)
'Python'

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

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

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

>>> 'spam, spam, spam'.count('spam')
3
>>> 'spam, spam, spam'.count('spam', 5)
2
>>> 'spam, spam, spam'.count('spam', 5, 10)
1
>>> 'spam, spam, spam'.count('eggs')
0
>>> 'spam, spam, spam'.count('')
17

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

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

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

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

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

>>> encoded_str_to_bytes = 'Python'.encode()
>>> type(encoded_str_to_bytes)
<class 'bytes'>
>>> encoded_str_to_bytes
b'Python'

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

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

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

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

>>> 'Python'.endswith('on')
True
>>> 'a tuple of suffixes'.endswith(('at', 'in'))
False
>>> 'a tuple of suffixes'.endswith(('at', 'es'))
True
>>> 'Python is amazing'.endswith('is', 0, 9)
True

См. также startswith() и removesuffix().

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'
>>> print('01\t012\n0123\t01234'.expandtabs(4))
01  012
0123    01234

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

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

>>> 'spam, spam, spam'.find('sp')
0
>>> 'spam, spam, spam'.find('sp', 5)
6

См. также rfind() и index().

Примечание

Метод 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'
>>> "The sum of {a} + {b} is {answer}".format(answer=1+2, a=1, b=2)
'The sum of 1 + 2 is 3'
>>> "{1} expects the {0} Inquisition!".format("Spanish", "Nobody")
'Nobody expects the Spanish Inquisition!'

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

Примечание

При форматировании числа (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, если подстрока не найдена. Например:

>>> 'spam, spam, spam'.index('spam')
0
>>> 'spam, spam, spam'.index('eggs')
Traceback (most recent call last):
  File "<python-input-0>", line 1, in <module>
    'spam, spam, spam'.index('eggs')
    ~~~~~~~~~~~~~~~~~~~~~~~~^^^^^^^^
ValueError: substring not found

См. также rindex().

str.isalnum()¶

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

>>> 'abc123'.isalnum()
True
>>> 'abc123!@#'.isalnum()
False
>>> ''.isalnum()
False
>>> ' '.isalnum()
False

str.isalpha()¶

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

>>> 'Letters and spaces'.isalpha()
False
>>> 'LettersOnly'.isalpha()
True
>>> 'µ'.isalpha()  # не-ASCII символы также могут считаться буквенными
True

См. Unicode Properties.

str.isascii()¶

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

>>> 'ASCII characters'.isascii()
True
>>> 'µ'.isascii()
False

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

str.isdecimal()¶

Возвращает True, если все символы строки являются десятичными цифрами и в строке есть хотя бы один символ, иначе False. Десятичные цифры – это символы, которые можно использовать для формирования чисел по основанию 10, например U+0660, ARABIC-INDIC DIGIT ZERO. Формально десятичный символ – это символ из общей категории Юникода «Nd». Например:

>>> '0123456789'.isdecimal()
True
>>> '٠١٢٣٤٥٦٧٨٩'.isdecimal()  # арабо-индийские цифры от нуля до девяти
True
>>> 'alphabetic'.isdecimal()
False

str.isdigit()¶

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

Например:

>>> '0123456789'.isdigit()
True
>>> '٠١٢٣٤٥٦٧٨٩'.isdigit()  # арабо-индийские цифры от нуля до девяти
True
>>> '⅕'.isdigit()  # обыкновенная дробь одна пятая
False
>>> '²'.isdecimal(), '²'.isdigit(),  '²'.isnumeric()
(False, True, True)

См. также isdecimal() и isnumeric().

str.isidentifier()¶

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

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

Пример:

>>> from keyword import iskeyword

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

str.islower()¶

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

str.isnumeric()¶

Возвращает True, если все символы строки являются числовыми символами и в строке есть хотя бы один символ, иначе False. Числовые символы включают цифры и все символы, имеющие свойство числового значения Unicode, например U+2155, VULGAR FRACTION ONE FIFTH. Формально числовыми считаются символы со значением свойства Numeric_Type=Digit, Numeric_Type=Decimal или Numeric_Type=Numeric. Например:

>>> '0123456789'.isnumeric()
True
>>> '٠١٢٣٤٥٦٧٨٩'.isnumeric()  # арабо-индийские цифры от нуля до девяти
True
>>> '⅕'.isnumeric()  # обыкновенная дробь одна пятая
True
>>> '²'.isdecimal(), '²'.isdigit(),  '²'.isnumeric()
(False, True, True)

См. также isdecimal() и isdigit().

str.isprintable()¶

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

Здесь «печатный» означает, что символ подходит для использования repr() в своём выводе; «непечатный» означает, что repr() на встроенных типах будет экранировать символ шестнадцатеричным кодом. Это не влияет на обработку строк, записываемых в sys.stdout или sys.stderr.

Печатные символы – это те, которые в базе данных символов Unicode (см. unicodedata) имеют общую категорию из группы Letter, Mark, Number, Punctuation или Symbol (L, M, N, P или S); плюс пробел ASCII 0x20. Непечатные символы – это символы из группы Separator или Other (Z или C), за исключением пробела ASCII.

Например:

>>> ''.isprintable(), ' '.isprintable()
(True, True)
>>> '\t'.isprintable(), '\n'.isprintable()
(False, False)

См. также isspace().

str.isspace()¶

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

Например:

>>> ''.isspace()
False
>>> ' '.isspace()
True
>>> '\t\n'.isspace() # TAB и перевод строки
True
>>> '\u3000'.isspace() # Идеографический пробел
True

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

См. также isprintable().

str.istitle()¶

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

Например:

>>> 'Spam, Spam, Spam'.istitle()
True
>>> 'spam, spam, spam'.istitle()
False
>>> 'SPAM, SPAM, SPAM'.istitle()
False

См. также title().

str.isupper()¶

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

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

str.join(iterable, /)¶

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

>>> ', '.join(['spam', 'spam', 'spam'])
'spam, spam, spam'
>>> '-'.join('Python')
'P-y-t-h-o-n'

См. также split().

str.ljust(width, fillchar=' ', /)¶

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

Например:

>>> 'Python'.ljust(10)
'Python    '
>>> 'Python'.ljust(10, '.')
'Python....'
>>> 'Monty Python'.ljust(10, '.')
'Monty Python'

См. также rjust().

str.lower()¶

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

>>> 'Lower Method Example'.lower()
'lower method example'

Используемый алгоритм приведения к нижнему регистру описан в разделе 3.13 «Default Case Folding» стандарта Unicode.

str.lstrip(chars=None, /)¶

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

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

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

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

static str.maketrans(dict, /)¶

static str.maketrans(from, to, remove='', /)

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

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

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

str.partition(sep, /)¶

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

Например:

>>> 'Monty Python'.partition(' ')
('Monty', ' ', 'Python')
>>> "Monty Python's Flying Circus".partition(' ')
('Monty', ' ', "Python's Flying Circus")
>>> 'Monty Python'.partition('-')
('Monty Python', '', '')

См. также rpartition().

str.removeprefix(prefix, /)¶

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

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

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

См. также removesuffix() и startswith().

str.removesuffix(suffix, /)¶

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

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

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

См. также removeprefix() и endswith().

str.replace(old, new, /, count=-1)¶

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

>>> 'spam, spam, spam'.replace('spam', 'eggs')
'eggs, eggs, eggs'
>>> 'spam, spam, spam'.replace('spam', 'eggs', 1)
'eggs, spam, spam'

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

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

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

>>> 'spam, spam, spam'.rfind('sp')
12
>>> 'spam, spam, spam'.rfind('sp', 0, 10)
6

См. также find() и rindex().

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

Действует как rfind(), но возбуждает ValueError, если подстрока sub не найдена. Например:

>>> 'spam, spam, spam'.rindex('spam')
12
>>> 'spam, spam, spam'.rindex('eggs')
Traceback (most recent call last):
  File "<stdin-0>", line 1, in <module>
    'spam, spam, spam'.rindex('eggs')
    ~~~~~~~~~~~~~~~~~~~~~~~~~^^^^^^^^
ValueError: substring not found

См. также index() и find().

str.rjust(width, fillchar=' ', /)¶

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

Например:

>>> 'Python'.rjust(10)
'    Python'
>>> 'Python'.rjust(10, '.')
'....Python'
>>> 'Monty Python'.rjust(10, '.')
'Monty Python'

См. также ljust() и zfill().

str.rpartition(sep, /)¶

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

Например:

>>> 'Monty Python'.rpartition(' ')
('Monty', ' ', 'Python')
>>> "Monty Python's Flying Circus".rpartition(' ')
("Monty Python's Flying", ' ', 'Circus')
>>> 'Monty Python'.rpartition('-')
('', '', 'Monty Python')

См. также partition().

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

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

str.rstrip(chars=None, /)¶

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

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

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

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

См. также strip().

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

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

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

Например:

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

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

Например:

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

Если sep не указан или равен None, а maxsplit равен 0, учитываются только начальные последовательности пробельных символов.

Например:

>>> "".split(None, 0)
[]
>>> "   ".split(None, 0)
[]
>>> "   foo   ".split(maxsplit=0)
['foo   ']

См. также join() и rsplit().

str.splitlines(keepends=False)¶

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

Например:

>>> 'Python'.startswith('Py')
True
>>> 'a tuple of prefixes'.startswith(('at', 'a'))
True
>>> 'Python is amazing'.startswith('is', 7)
True

См. также endswith() и removeprefix().

str.strip(chars=None, /)¶

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

Символы пробела определяются с помощью str.isspace().

Например:

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

См. также rstrip().

str.swapcase()¶

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

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

Следует учитывать, что s.swapcase().swapcase() == s не обязательно истинно. Например:

>>> 'straße'.swapcase().swapcase()
'strasse'

См. также str.lower() и str.upper().

str.title()¶

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

Например:

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

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

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

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

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

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

См. также istitle().

str.translate(table, /)¶

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

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

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

str.upper()¶

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

Используемый алгоритм преобразования в верхний регистр описан в разделе 3.13 «Default Case Folding» стандарта Unicode.

str.zfill(width, /)¶

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

Например:

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

См. также rjust().

Форматированные строковые литералы (f-строки)¶Formatted String Literals (f-strings)

F-строка (формально форматированный строковый литерал) – это строковый литерал с префиксом f или F. Такой строковый литерал позволяет встраивать результаты произвольных выражений Python в поля подстановки, которые ограничены фигурными скобками ({}). Каждое поле подстановки должно содержать выражение, за которым необязательно может следовать:

• спецификатор отладки – знак равенства (=);

• спецификатор преобразования – !s, !r или !a; и/или

• спецификатор формата с префиксом в виде двоеточия (:).

Подробнее о синтаксисе этих полей см. раздел «Лексический анализ» про f-строки.

>>> number = 14.3
>>> f'{number=}'
'number=14.3'