# Вбудовані типи

У наступних розділах описуються стандартні типи, вбудовані в інтерпретатор.

Основними вбудованими типами є числа, послідовності, відображення, класи, екземпляри та винятки.

Деякі класи колекцій є мутабельними. Методи, які додають, віднімають або переставляють свої члени на місці, і не повертають конкретний елемент, ніколи не повертають сам екземпляр колекції, а натомість повертають `None`.

Деякі операції підтримуються кількома типами об’єктів; зокрема, практично всі об’єкти можна порівняти на рівність, перевірити на значення істинності та перетворити на рядок (за допомогою функції `repr()` або трохи іншої функції `str()`). Остання функція неявно використовується, коли об’єкт записується функцією `print()`.

## Перевірка значення на істинність

Будь-який об’єкт можна перевірити на значення істинності для використання як умову в конструкціях `if` або `while` або як операнд булевих операцій, наведених нижче.

За замовчуванням об’єкт вважається істинним, якщо його клас не визначає або метод `__bool__()`, що повертає `False`, або метод `__len__()`, що повертає нуль, коли викликати його для цього об’єкта. [1] Тут наведена більшість вбудованих об’єктів, що вважаються хибними:

- константи, визначені як хибні: `None` і `False`

- нуль будь-якого числового типу: `0`, `0.0`, `0j`, `Decimal(0)`, `Fraction(0, 1)`

- порожні послідовності та колекції: `''`, `()`, `[]`, `{}`, `set()`, `range(0)`

Операції та вбудовані функції, які мають булевий результат, завжди повертають `0` або `False` для хибного значення і `1` або `True` для істинного, якщо не вказано інше. (Важливий виняток: логічні операції `or` та `and` завжди повертають один зі своїх операндів.)

## Булеві операції — `and`, `or`, `not`

Ось булеві операції, впорядковані за зростанням пріоритету:

Операція | Результат | Примітки
--- | --- | ---
`x or y` | якщо x є істинним, то x, інакше y | (1)
`x and y` | якщо x є хибним, тоді x, інакше y | (2)
`not x` | якщо x є хибним, тоді `True`, інакше `False` | (3)

Примітки:

1. Це оператор зі скороченим обчисленням, тому він обчислює другий аргумент лише якщо перший є хибним.

2. Це оператор короткого замикання, тому він обчислює лише другий аргумент, якщо перший істинний.

3. `not` має нижчий пріоритет, ніж не-булеві оператори, тому `not a == b` інтерпретується як `not (a == b)`, а `a == not b` є синтаксичною помилкою.

## Порівняння

У Python є вісім операцій порівняння. Усі вони мають однаковий пріоритет (вищий, ніж у булевих операцій). Порівняння можна довільно додавати у ланцюжки; наприклад, `x < y <= z` еквівалентно `x < y and y <= z`, за винятком того, що y обчислюється лише один раз (але в обох випадках z узагалі не обчислюється, коли `x < y` виявляється хибним).

Ця таблиця підсумовує операції порівняння:

Операція | Значення
--- | ---
`<` | строго менше ніж
`<=` | менше або дорівнює
`>` | строго більше ніж
`>=` | більше або дорівнює
`==` | дорівнює
`!=` | не дорівнює
`is` | ідентичність об’єктів
`is not` | заперечення ідентичності об’єктів

Об’єкти різних типів, за винятком різних числових типів, ніколи не дорівнюють одне одному. Оператор `==` завжди визначений, але для деяких типів об’єктів (наприклад, об’єктів класу) еквівалентний `is`. Оператори `<`, `<=`, `>` і `>=` визначені лише там, де вони мають сенс; наприклад, вони викликають виняток `TypeError`, коли один із аргументів є комплексним числом.

Порівняння неідентичних екземплярів класу зазвичай дає хибний результат, якщо лише у класі не визначений метод `__eq__()`.

Екземпляри класу не можуть бути впорядковані відносно інших екземплярів того самого класу або інших типів об’єктів, якщо клас не визначає достатньо методів `__lt__()`, `__le__()`,:meth:~object.__gt__ і `__ge__()` (зазвичай, методів `__lt__()` і `__eq__()` достатньо, якщо вас влаштовує звичайна поведінка операторів порівняння).

Поведінку операторів `is` і `is not` не можна налаштувати; також вони можуть бути застосовані до будь-яких двох об’єктів і ніколи не викликають винятків.

Ще дві операції з тим же синтаксичним пріоритетом, `in` і `not in`, підтримуються типами, що є ітерабельними чи реалізують метод `__contains__()`

## Числові типи — `int`, `float`, `complex`

Існує три різних числових типи: цілі, числа з рухомою комою та комплексні числа. На додачу, булеві числа є підтипом цілих чисел. Цілі числа мають необмежену точність. Числа з рухомою комою зазвичай реалізуються за допомогою double у C; інформацію про точність та внутрішнє представлення чисел з рухомою комою для машини, на якій виконується ваша програма, можна знайти у `sys.float_info`. Комплексні числа мають дійсну та уявну частини, кожна з яких є числом з рухомою комою. Щоб отримати ці частини з комплексного числа z, використовуйте `z.real` та `z.imag`. (Стандартна бібліотека включає додаткові числові типи `fractions.Fraction` для раціональних чисел та `decimal.Decimal` для чисел з рухомою комою з точністю, визначеною користувачем).

Числа створюються за допомогою числового літерала або як результат вбудованих функцій та операторів. Неприкрашені цілочисельні літерали (включаючи шістнадцяткові, вісімкові та двійкові числа) дають цілі числа. Числові літерали, що містять десяткову крапку або знак експоненти, дають числа з рухомою комою. Додавання `'j'` або `'J'` до числового літерала дає уявне число (комплексне число з нульовою дійсною частиною), яке ви можете додати до цілого числа або до числа з рухомою комою, щоб отримати комплексне число з дійсною та уявною частинами.

Конструктори `int()`, `float()` і `complex()` можна використовувати для отримання чисел певного типу.

Python fully supports mixed arithmetic: when a binary arithmetic operator has operands of different numeric types, the operand with the «narrower» type is widened to that of the other, where integer is narrower than floating point. Arithmetic with complex and real operands is defined by the usual mathematical formula, for example:

    x + complex(u, v) = complex(x + u, v)
    x * complex(u, v) = complex(x * u, x * v)

A comparison between numbers of different types behaves as though the exact values of those numbers were being compared. [2]

Усі числові типи (крім комплексних) підтримують наступні операції (пріоритети операцій див. Пріоритет оператора):

Операція | Результат | Примітки | Повна документація
--- | --- | --- | ---
`x + y` | сума x і y |  |
`x - y` | різниця x і y |  |
`x * y` | добуток x і y |  |
`x / y` | частка x і y |  |
`x // y` | округлена донизу частка x і y | (1)(2) |
`x % y` | остача від `x / y` | (2) |
`-x` | протилежне x |  |
`+x` | x без змін |  |
`abs(x)` | абсолютне значення або величина x |  | `abs()`
`int(x)` | x, перетворене на ціле число | (3)(6) | `int()`
`float(x)` | x, перетворене на число з рухомою комою | (4)(6) | `float()`
`complex(re, im)` | комплексне число з дійсною частиною re, уявною частиною im. im за замовчуванням дорівнює нулю. | (6) | `complex()`
`c.conjugate()` | спряжене комплексне число c |  |
`divmod(x, y)` | пара `(x // y, x % y)` | (2) | `divmod()`
`pow(x, y)` | x у степені y | (5) | `pow()`
`x ** y` | x у степені y | (5) |

Примітки:

1. Інша назва - цілочисельне ділення. Для операндів типу `int` результат має тип `int`. Для операндів типу `float` результат має тип `float`. У загальному випадку результатом є ціле число, хоча тип результату не обов’язково `int`. Результат завжди округлюється в бік мінус нескінченності: `1//2` дорівнює `0`, `(-1)//2` дорівнює `-1`, `1//(-2)` дорівнює `-1`, а `(-1)//(-2)` дорівнює `0`.

2. Не для комплексних чисел. Натомість конвертуйте у числа з рухомою комою за допомогою `abs()`, якщо це доречно.

3. При перетворенні `float` в `int` відбувається усічення, дробова частина відкидається. Дивіться функції `math.floor()` та `math.ceil()` для альтернативних перетворень.

4. float також приймає рядки «nan» і «inf» з необов’язковим префіксом «+» або «-» на позначення Not a Number (NaN, Не Число) і додатною або від’ємною нескінченністю.

5. Python визначає `pow(0, 0)` і `0 ** 0` як `1`, як це прийнято для мов програмування.

6. Прийнятні числові літерали включають цифри від `0` до `9` або будь-який еквівалент Unicode (кодові пункти з властивістю `Nd`).

   Повний список кодових пунктів з властивістю `Nd` див. у Стандарті Юнікоду.

Усі типи `numbers.Real` (`int` і `float`) також містять такі операції:

Операція | Результат
--- | ---
`math.trunc(x)` | x, усічене до `Integral`
`round(x[, n])` | x, округлене до n цифр, з округленням половини до парного числа. Якщо n опущено, за замовчанням дорівнює 0.
`math.floor(x)` | найбільший `Integral` <= x
`math.ceil(x)` | найменший `Integral` >= x

Для отримання додаткових числових операцій перегляньте модулі `math` і `cmath`.

### Побітові операції над цілими типами

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

Пріоритети двійкових побітових операцій нижчі, ніж числових операцій, і вищі, ніж порівняння; унарна операція `~` має той самий пріоритет, що й інші унарні числові операції (`+` і `-`).

У цій таблиці наведено порозрядні операції, відсортовані за зростанням пріоритету:

Операція | Результат | Примітки
--- | --- | ---
`x | y` | побітове або x і y | (4)
`x ^ y` | побітове виключне або x і y | (4)
`x & y` | побітове і x і y | (4)
`x << n` | x, зсунуте ліворуч на n бітів | (1)(2)
`x >> n` | x, зсунуте праворуч на n бітів | (1)(3)
`~x` | інвертовані біти x |

Примітки:

1. Зсуви на від’ємне число є неприпустимим і викликає `ValueError`.

2. Зсув ліворуч на n бітів еквівалентний множенню на `pow(2, n)`.

3. Зсув праворуч на n бітів еквівалентний діленню з округленням донизу на `pow(2, n)`.

4. Виконання цих обчислень із принаймні одним додатковим бітом розширення знака в скінченному поданні доповнення до двох (робоча бітова ширина `1 + max(x.bit_length(), y.bit_length())` або більше) є достатньою для отримання того самого результату, що й для нескінченної кількості знакових бітів.

### Додаткові методи для цілих типів

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

int.bit_length()

  Повертає кількість бітів, необхідних для представлення цілого числа в двійковій системі, за винятком знака та нулів на початку:

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

  Точніше, якщо `x` відмінне від нуля, то `x.bit_length()` є унікальним натуральним числом `k` таким, що `2**(k-1) <= abs(x) < 2**k`. Аналогічно, коли `abs(x)` достатньо малий, щоб мати правильно округлений логарифм, тоді `k = 1 + int(log(abs(x), 2))`. Якщо `x` дорівнює нулю, то `x.bit_length()` повертає `0`.

  Еквівалентне:

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

  Added in version 3.1.

int.bit_count()

  Повертає кількість одиниць у двійковому представленні абсолютного значення цілого числа. Приклад:

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

  Еквівалентне:

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

  Added in version 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, довжина=1, byteorder='big', signed=False):
          if byteorder == 'little':
              order = range(довжина)
          elif byteorder == 'big':
              order = reversed(range(довжина))
          else:
              raise ValueError("порядок байт повинен бути або 'little' або 'big'")

          повертати bytes((n >> i*8) & 0xff для i в порядку)

  Added in version 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 має бути або байт-подібним об’єктом, або ітерабельним об’єктом, що створює байти.

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

  Аргумент 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

  Added in version 3.2.

  Змінено в версії 3.11: Додано значення аргументу за замовчуванням `byteorder`.

int.as_integer_ratio()

  Повертає пару цілих чисел, відношення яких дорівнює вихідному цілому числу і має додатний знаменник. Цілочисельне відношення цілих чисел завжди має ціле число у чисельнику та `1` у знаменнику.

  Added in version 3.8.

int.is_integer()

  Повертає `True`. Існує для сумісності за «качиною типізацією» з `float.is_integer()`.

  Added in version 3.12.

### Додаткові методи для Float

Тип float реалізує `numbers.Real` абстрактний базовий клас. float також має такі додаткові методи.

classmethod float.from_number(x)

  Class method to return a floating-point number constructed from a number x.

  If the argument is an integer or a floating-point number, a floating-point number with the same value (within Python’s floating-point precision) is returned. If the argument is outside the range of a Python float, an `OverflowError` will be raised.

  For a general Python object `x`, `float.from_number(x)` delegates to `x.__float__()`. If `__float__()` is not defined then it falls back to `__index__()`.

  Added in version 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 зберігаються усередині як двійкові числа, перетворення числа з плаваючою точкою в десятковий рядок або з нього зазвичай включає невелику помилку округлення. Навпаки, шістнадцяткові рядки дозволяють точне представлення та специфікацію чисел з плаваючою комою. Це може бути корисним під час налагодження та чисельної роботи.

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

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

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

Застосування зворотного перетворення до `3740.0` дає інший шістнадцятковий рядок, що представляє те саме число:

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

### Additional Methods on Complex

The `complex` type implements the `numbers.Complex` abstract base class. `complex` also has the following additional methods.

classmethod complex.from_number(x)

  Class method to convert a number to a complex number.

  For a general Python object `x`, `complex.from_number(x)` delegates to `x.__complex__()`. If `__complex__()` is not defined then it falls back to `__float__()`. If `__float__()` is not defined then it falls back to `__index__()`.

  Added in version 3.14.

### Хешування числових типів

For numbers `x` and `y`, possibly of different types, it’s a requirement that `hash(x) == hash(y)` whenever `x == y` (see the `__hash__()` method documentation for more details). For ease of implementation and efficiency across a variety of numeric types (including `int`, `float`, `decimal.Decimal` and `fractions.Fraction`) Python’s hash for numeric types is based on a single mathematical function that’s defined for any rational number, and hence applies to all instances of `int` and `fractions.Fraction`, and all finite instances of `float` and `decimal.Decimal`. Essentially, this function is given by reduction modulo `P` for a fixed prime `P`. The value of `P` is made available to Python as the `modulus` attribute of `sys.hash_info`.

В даний час простим числом, яке використовується, є `P = 2**31 - 1` на машинах з 32-розрядним C long і `P = 2**61 - 1` на машинах з 64-бітним C long.

Ось правила в деталях:

- Якщо `x = m / n` є невід’ємним раціональним числом, а `n` не ділиться на `P`, визначте `hash(x)` як `m * invmod(n, P) % P`, де `invmod(n, P)` дає обернене `n` за модулем `P`.

- Якщо `x = m / n` є невід’ємним раціональним числом, а `n` ділиться на `P` (але `m` не ділиться на `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` так, щоб він знаходився в `діапазоні (-2**(sys.hash_info.width - 1), 2**(sys.hash_info.width - 1) ))`. Знову ж таки, якщо результат `-1`, він замінюється на `-2`.

Щоб прояснити наведені вище правила, ось приклад коду Python, еквівалентного вбудованому хешу, для обчислення хешу раціонального числа, `float` або `complex`:

    import sys, math

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

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

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

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

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

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

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

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

## Boolean Type - `bool`

Booleans represent truth values. The `bool` type has exactly two constant instances: `True` and `False`.

The built-in function `bool()` converts any value to a boolean, if the value can be interpreted as a truth value (see section Перевірка значення на істинність above).

For logical operations, use the boolean operators `and`, `or` and `not`. When applying the bitwise operators `&`, `|`, `^` to two booleans, they return a bool equivalent to the logical operations «and», «or», «xor». However, the logical operators `and`, `or` and `!=` should be preferred over `&`, `|` and `^`.

Застаріло починаючи з версії 3.12: The use of the bitwise inversion operator `~` is deprecated and will raise an error in Python 3.16.

`bool` is a subclass of `int` (see Числові типи — int, float, complex). In many numeric contexts, `False` and `True` behave like the integers 0 and 1, respectively. However, relying on this is discouraged; explicitly convert using `int()` instead.

## Типи ітераторів

Python підтримує концепцію ітерації над контейнерами. Це реалізується за допомогою двох різних методів; вони використовуються, щоб дозволити визначеним користувачем класам підтримувати ітерацію. Послідовності, описані нижче більш детально, завжди підтримують ітераційні методи.

Потрібно визначити один метод для об’єктів-контейнерів, щоб забезпечити підтримку iterable:

container.__iter__()

  Повертає об’єкт iterator. Об’єкт повинен підтримувати описаний нижче протокол ітератора. Якщо контейнер підтримує різні типи ітерацій, можна надати додаткові методи для спеціального запиту ітераторів для цих типів ітерацій. (Прикладом об’єкта, що підтримує кілька форм ітерації, може бути деревоподібна структура, яка підтримує обхід як у ширину, так і в глибину.) Цей метод відповідає слоту `tp_iter` структури типу для об’єктів Python в API Python/C.

Самі об’єкти ітератора повинні підтримувати наступні два методи, які разом утворюють iterator protocol:

iterator.__iter__()

  Повертає сам об’єкт iterator. Це потрібно, щоб дозволити використовувати як контейнери, так і ітератори з операторами `for` і `in`. Цей метод відповідає слоту `tp_iter` структури типу для об’єктів Python в API Python/C.

iterator.__next__()

  Повертає наступний елемент із iterator. Якщо більше елементів немає, підніміть виняток `StopIteration`. Цей метод відповідає слоту `tp_iternext` структури типу для об’єктів Python в API Python/C.

Python визначає декілька об’єктів-ітераторів для підтримки ітерації загальних і конкретних типів послідовностей, словників та інших більш спеціалізованих форм. Конкретні типи не важливі за межами їхньої реалізації протоколу ітератора.

Коли метод `__next__()` ітератора викликає `StopIteration`, він повинен продовжувати робити це під час наступних викликів. Реалізації, які не підкоряються цій властивості, вважаються зламаними.

### Типи генераторів

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.

## Типи послідовностей — `list`, `tuple`, `range`

Існує три основні типи послідовностей: списки, кортежі та об’єкти діапазону. Додаткові типи послідовностей, призначені для обробки бінарних даних і текстових рядків, описані у спеціальних розділах.

### Загальні операції послідовності

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

У цій таблиці наведено послідовність операцій, відсортованих за зростанням пріоритету. У таблиці s і t — послідовності одного типу, n, i, j і k — цілі числа, а x — довільний об’єкт, який відповідає будь-яким обмеженням щодо типу та значення накладений s.

Операції `in` і `not in` мають ті самі пріоритети, що й операції порівняння. Операції `+` (конкатенація) і `*` (повторення) мають той самий пріоритет, що й відповідні числові операції. [3]

Операція | Результат | Примітки
--- | --- | ---
`x в s` | `True`, якщо елемент s дорівнює x, інакше `False` | (1)
`x не в s` | `False`, якщо елемент s дорівнює x, інакше `True` | (1)
`s + t` | конкатенація s і t | (6)(7)
`s * n` або `n * s` | еквівалентно додаванню s до самого себе n разів | (2)(7)
`s[i]` | iий елемент з s, джерело 0 | (3)(9)
`s[i:j]` | фрагмент s від i до j | (3)(4)
`s[i:j:k]` | фрагмент s від i до j з кроком k | (3)(5)
`len(s)` | довжина s |
`хв(и)` | найменший елемент s |
`max(s)` | найбільший предмет s |
`s.index(x[, i[, j]])` | індекс першого входження x у s (за або після індексу i та перед індексом j) | (8)
`s.count(x)` | загальна кількість входжень x у s |

Послідовності одного типу також підтримують порівняння. Зокрема, кортежі та списки порівнюються лексикографічно шляхом порівняння відповідних елементів. Це означає, що для порівняння однаково кожен елемент повинен порівнюватись рівно, а дві послідовності мають бути одного типу та мати однакову довжину. (Для отримання повної інформації див. Порівняння у мовній довідці.)

Прямі та зворотні ітератори над змінними послідовностями отримують доступ до значень за допомогою індексу. Цей індекс буде продовжувати рух вперед (або назад), навіть якщо базова послідовність змінена. Ітератор завершується лише тоді, коли зустрічається `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 = [[] for i in range(3)]
       >>> lists[0].append(3)
       >>> lists[1].append(5)
       >>> lists[2].append(7)
       >>> lists
       [[3], [5], [7]]

   Подальші пояснення доступні в розділі поширених запитань Як створити багатовимірний список?.

3. Якщо i або j є від’ємними, індекс відноситься до кінця послідовності s: замінюється `len(s) + i` або `len(s) + j`. Але зауважте, що `-0` все одно `0`.

4. Зріз s від i до j визначається як послідовність елементів з індексом k, така що `i <= k < j`. Якщо i або j більше ніж `len(s)`, використовуйте `len(s)`. Якщо i пропущено або `None`, використовуйте `0`. Якщо j пропущено або `None`, використовуйте `len(s)`. Якщо i більше або дорівнює j, фрагмент порожній.

5. Зріз s від i до j з кроком k визначається як послідовність елементів з індексом `x = i + n*k` так, що `0 <= n < (j-i )/k`. Іншими словами, індекси `i`, `i+k`, `i+2*k`, `i+3*k` і так далі, зупиняючись, коли j є досягнуто (але ніколи не включаючи j). Коли k додатне, i і j скорочуються до `len(s)`, якщо вони більші. Коли k від’ємне, i та j скорочуються до `len(s) - 1`, якщо вони більші. Якщо i або j пропущені або `None`, вони стають «кінцевими» значеннями (кінець залежить від знака k). Зауважте, k не може дорівнювати нулю. Якщо k має значення `None`, воно розглядається як `1`.

6. Конкатенація незмінних послідовностей завжди призводить до нового об’єкта. Це означає, що створення послідовності шляхом повторної конкатенації матиме квадратичну вартість виконання в загальній довжині послідовності. Щоб отримати лінійну вартість роботи, ви повинні перейти до однієї з наведених нижче альтернатив:

   - якщо конкатенувати об’єкти `str`, ви можете створити список і використовувати `str.join()` наприкінці або записати в екземпляр `io.StringIO` і отримати його значення після завершення

   - якщо конкатенація об’єктів `bytes`, ви можете так само використовувати `bytes.join()` або `io.BytesIO`, або ви можете виконати конкатенацію на місці з об’єктом `bytearray`. Об’єкти `bytearray` є змінними та мають ефективний механізм загального розподілу

   - якщо конкатенація об’єктів `tuple`, замість цього розширте `list`

   - для інших типів дослідіть відповідну документацію класу

7. Деякі типи послідовностей (наприклад, `range`) підтримують лише послідовності елементів, які відповідають певним шаблонам, і, отже, не підтримують конкатенацію або повторення послідовності.

8. `index` викликає `ValueError`, коли x не знайдено в s. Не всі реалізації підтримують передачу додаткових аргументів i і j. Ці аргументи дозволяють здійснювати ефективний пошук підрозділів послідовності. Передача додаткових аргументів приблизно еквівалентна використанню `s[i:j].index(x)`, тільки без копіювання будь-яких даних і з повернутим індексом відносно початку послідовності, а не початку фрагмента. .

9. An `IndexError` is raised if i is outside the sequence range.

### Незмінні типи послідовностей

Єдина операція, яку зазвичай реалізують незмінні типи послідовностей, яка також не реалізована змінними типами послідовностей, це підтримка вбудованого `hash()`.

Ця підтримка дозволяє використовувати незмінні послідовності, такі як екземпляри `tuple`, як ключі `dict` і зберігати їх у екземплярах `set` і `frozenset`.

Спроба хешувати незмінну послідовність, яка містить нехешовані значення, призведе до `TypeError`.

### Змінні типи послідовностей

Операції в наведеній нижче таблиці визначено для змінних типів послідовностей. `collections.abc.MutableSequence` ABC надається, щоб спростити правильну реалізацію цих операцій у настроюваних типах послідовностей.

У таблиці s є екземпляром змінного типу послідовності, t є будь-яким ітерованим об’єктом, а x є довільним об’єктом, який відповідає будь-яким обмеженням типу та значення, накладеним s (наприклад, `bytearray` приймає лише цілі числа, які відповідають обмеженню значення `0 <= x <= 255`).

Операція | Результат | Примітки
--- | --- | ---
`s[i] = x` | пункт i з s замінено на x |
`del s[i]` | removes item i of s |
`s[i:j] = t` | фрагмент s від i до j замінюється вмістом ітерованого t |
`del s[i:j]` | removes the elements of `s[i:j]` from the list (same as `s[i:j] = []`) |
`s[i:j:k] = t` | елементи `s[i:j:k]` замінюються на елементи t | (1)
`del s[i:j:k]` | видаляє елементи `s[i:j:k]` зі списку |
`s.append(x)` | додає x до кінця послідовності (те саме, що `s[len(s):len(s)] = [x]`) |
`s.clear()` | видаляє всі елементи з s (те саме, що `del s[:]`) | (5)
`s.copy()` | створює поверхневу копію s (те саме, що `s[:]`) | (5)
`s.extend(t)` або `s += t` | розширює s вмістом t (здебільшого те саме, що `s[len(s):len(s)] = t`) |
`s *= n` | оновлює s з повторенням його вмісту n разів | (6)
`s.insert(i, x)` | вставляє x в s за індексом, заданим i (те саме, що `s[i:i] = [x]`) |
`s.pop()` або `s.pop(i)` | отримує елемент у i, а також видаляє його з s | (2)
`s.remove(x)` | removes the first item from s where `s[i]` is equal to x | (3)
`s.reverse()` | перевертає елементи s на місце | (4)

Примітки:

1. If k is not equal to `1`, t must have the same length as the slice it is replacing.

2. Необов’язковий аргумент i за умовчанням має значення `-1`, тому за замовчуванням останній елемент видаляється та повертається.

3. `remove()` викликає `ValueError`, коли x не знайдено в s.

4. Метод `reverse()` змінює поточну послідовність для економії простору під час реверсування великої послідовності. Щоб нагадати користувачам, що він працює за побічним ефектом, він не повертає зворотну послідовність.

5. `clear()` і `copy()` включено для узгодженості з інтерфейсами змінних контейнерів, які не підтримують операції зрізання (таких як `dict` і `set`). `copy()` не є частиною `collections.abc.MutableSequence` ABC, але більшість конкретних змінних класів послідовності надають його.

   Added in version 3.3: Методи `clear()` і `copy()`.

6. Значення n є цілим числом або об’єктом, що реалізує `__index__()`. Нульові та негативні значення n очищають послідовність. Елементи послідовності не копіюються; на них посилаються кілька разів, як пояснюється для `s * n` у Загальні операції послідовності.

### списки

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

class list(iterable=(), /)

  Списки можна створювати кількома способами:

  - Використання пари квадратних дужок для позначення порожнього списку: `[]`

  - Використовуючи квадратні дужки, розділяючи елементи комами: `[a]`, `[a, b, c]`

  - Використання розуміння списку: `[x for x in iterable]`

  - Використання конструктора типу: `list()` або `list(iterable)`

  Конструктор створює список, елементи якого є такими ж і в тому ж порядку, що й елементи iterable. iterable може бути або послідовністю, контейнером, який підтримує ітерацію, або об’єктом ітератора. Якщо iterable вже є списком, копія створюється та повертається, подібно до `iterable[:]`. Наприклад, `list('abc')` повертає `['a', 'b', 'c']`, а `list( (1, 2, 3) )` повертає `[ 1, 2, 3]`. Якщо аргумент не задано, конструктор створює новий порожній список, `[]`.

  Багато інших операцій також створюють списки, включаючи вбудовану `sorted()`.

  Списки реалізують усі common і mutable операції послідовності. Списки також надають наступний додатковий метод:

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

    Цей метод сортує список на місці, використовуючи лише `<` порівняння між елементами. Винятки не пригнічуються — якщо будь-яка операція порівняння завершиться невдало, вся операція сортування буде невдалою (і список, ймовірно, залишиться в частково зміненому стані).

    `sort()` приймає два аргументи, які можуть бути передані лише ключовим словом (аргументи лише для ключових слів):

    key визначає функцію одного аргументу, яка використовується для отримання ключа порівняння з кожного елемента списку (наприклад, `key=str.lower`). Ключ, що відповідає кожному елементу в списку, обчислюється один раз, а потім використовується для всього процесу сортування. Значення за замовчуванням «Немає» означає, що елементи списку сортуються безпосередньо без обчислення окремого значення ключа.

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

    reverse — це логічне значення. Якщо встановлено значення `True`, елементи списку сортуються так, ніби кожне порівняння було зворотним.

    Цей метод змінює наявну послідовність для економії простору під час сортування великої послідовності. Щоб нагадати користувачам, що він працює за побічним ефектом, він не повертає відсортовану послідовність (використовуйте `sorted()`, щоб явно запитати новий екземпляр відсортованого списку).

    Метод `sort()` гарантовано буде стабільним. Сортування є стабільним, якщо воно гарантує відсутність зміни відносного порядку порівнюваних рівних елементів — це корисно для сортування за кілька проходів (наприклад, сортування за відділом, а потім за ступенем зарплати).

    Приклади сортування та короткий посібник із сортування див. Sorting Techniques.

    Поки список сортується, ефект від спроби змінити або навіть перевірити список не визначено. Реалізація Python на C робить список порожнім протягом певного часу та викликає `ValueError`, якщо він може виявити, що список було змінено під час сортування.

### Кортежі

Кортежі — це незмінні послідовності, які зазвичай використовуються для зберігання колекцій різнорідних даних (таких як 2-кортежі, створені за допомогою вбудованої функції `enumerate()`). Кортежі також використовуються у випадках, коли потрібна незмінна послідовність однорідних даних (наприклад, дозволити зберігання в екземплярі `set` або `dict`).

class tuple(iterable=(), /)

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

  - Використання пари круглих дужок для позначення порожнього кортежу: `()`

  - Використання кінцевої коми для одноэлементного кортежу: `a,` або `(a,)`

  - Розділення елементів комами: `a, b, c` або `(a, b, c)`

  - Використання вбудованого `tuple()`: `tuple()` або `tuple(iterable)`

  Конструктор будує кортеж, елементи якого є такими ж і в тому ж порядку, що й елементи iterable. iterable може бути або послідовністю, контейнером, який підтримує ітерацію, або об’єктом ітератора. Якщо iterable вже є кортежем, він повертається без змін. Наприклад, `tuple('abc')` повертає `('a', 'b', 'c')`, `tuple( [1, 2, 3] )` повертає `( 1, 2, 3)`. Якщо аргумент не задано, конструктор створює новий порожній кортеж `()`.

  Зауважте, що насправді кома створює кортеж, а не круглі дужки. Дужки необов’язкові, за винятком порожнього кортежу або коли вони потрібні для уникнення синтаксичної неоднозначності. Наприклад, «f(a, b, c)» — це виклик функції з трьома аргументами, тоді як «f((a, b, c))» — це виклик функції з 3-кортежем як єдиним аргумент.

  Кортежі реалізують усі загальні операції послідовності.

Для різнорідних колекцій даних, де доступ за іменем є зрозумілішим, ніж доступ за індексом, `collections.namedtuple()` може бути більш відповідним вибором, ніж простий об’єкт кортежу.

### діапазони

Тип `range` представляє незмінну послідовність чисел і зазвичай використовується для повторення певної кількості разів у циклах `for`.

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

  Аргументи конструктора діапазону мають бути цілими числами (або вбудованим `int`, або будь-яким об’єктом, який реалізує спеціальний метод `__index__()`). Якщо аргумент step опущено, за умовчанням він дорівнює `1`. Якщо аргумент початок опущено, за умовчанням він дорівнює `0`. Якщо крок дорівнює нулю, виникає `ValueError`.

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

  Для від’ємного кроку вміст діапазону все ще визначається формулою `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`, обчислюючи окремі елементи та піддіапазони за потреби).

Об’єкти діапазону реалізують `collections.abc.Sequence` ABC і надають такі функції, як тести на обмеження, пошук індексу елемента, нарізка та підтримка негативних індексів (див. Типи послідовностей — 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 ) == діапазон(2, 1, 3)` або `діапазон(0, 3, 2) == діапазон(0, 4, 2)`.)

Змінено в версії 3.2: Реалізуйте послідовність ABC. Підтримка нарізки та негативних індексів. Перевіряйте об’єкти `int` на приналежність у постійному часі замість повторення всіх елементів.

Змінено в версії 3.3: Визначте «==» і «!=», щоб порівнювати об’єкти діапазону на основі послідовності значень, які вони визначають (замість порівняння на основі ідентичності об’єкта).

Added the `start`, `stop` and `step` attributes.

Дивись також

- The linspace recipe shows how to implement a lazy version of range suitable for floating-point applications.

## Text and Binary Sequence Type Methods Summary

The following table summarizes the text and binary sequence types methods by category.

Category | `str` methods | `bytes` and `bytearray` methods
--- | --- | ---
Formatting | `str.format()` |
`str.format_map()` |
f-strings |
Форматування рядків у стилі printf | Форматування байтів у стилі printf
Searching and Replacing | `str.find()` | `str.rfind()` | `bytes.find()` | `bytes.rfind()`
`str.index()` | `str.rindex()` | `bytes.index()` | `bytes.rindex()`
`str.startswith()` | `bytes.startswith()`
`str.endswith()` | `bytes.endswith()`
`str.count()` | `bytes.count()`
`str.replace()` | `bytes.replace()`
Splitting and Joining | `str.split()` | `str.rsplit()` | `bytes.split()` | `bytes.rsplit()`
`str.splitlines()` | `bytes.splitlines()`
`str.partition()` | `bytes.partition()`
`str.rpartition()` | `bytes.rpartition()`
`str.join()` | `bytes.join()`
String Classification | `str.isalpha()` | `bytes.isalpha()`
`str.isdecimal()` |
`str.isdigit()` | `bytes.isdigit()`
`str.isnumeric()` |
`str.isalnum()` | `bytes.isalnum()`
`str.isidentifier()` |
`str.islower()` | `bytes.islower()`
`str.isupper()` | `bytes.isupper()`
`str.istitle()` | `bytes.istitle()`
`str.isspace()` | `bytes.isspace()`
`str.isprintable()` |
Case Manipulation | `str.lower()` | `bytes.lower()`
`str.upper()` | `bytes.upper()`
`str.casefold()` |
`str.capitalize()` | `bytes.capitalize()`
`str.title()` | `bytes.title()`
`str.swapcase()` | `bytes.swapcase()`
Padding and Stripping | `str.ljust()` | `str.rjust()` | `bytes.ljust()` | `bytes.rjust()`
`str.center()` | `bytes.center()`
`str.expandtabs()` | `bytes.expandtabs()`
`str.strip()` | `bytes.strip()`
`str.lstrip()` | `str.rstrip()` | `bytes.lstrip()` | `bytes.rstrip()`
Translation and Encoding | `str.translate()` | `bytes.translate()`
`str.maketrans()` | `bytes.maketrans()`
`str.encode()` |
| `bytes.decode()`

## Тип текстової послідовності — `str`

Текстові дані в Python обробляються за допомогою об’єктів `str` або strings. Рядки є незмінними послідовностями кодових точок Unicode. Рядкові літерали записуються різними способами:

- Одинарні лапки: `'дозволяє вбудовані "подвійні" лапки'`

- Подвійні лапки: `"дозволяє вбудовані 'одинарні' лапки"`

- Потрійні лапки: `''Три одинарні лапки''''`, `"""Три подвійні лапки"""`

Рядки з потрійними лапками можуть охоплювати кілька рядків - усі пов’язані пробіли будуть включені в рядковий літерал.

Рядкові літерали, які є частиною одного виразу і мають лише пробіли між собою, будуть неявно перетворені в один рядковий літерал. Тобто `("спам " "яйця") == "спам яйця"`.

See Рядкові та байтові літерали for more about the various forms of string literal, including supported escape sequences, and the `r` («raw») prefix that disables most escape sequence processing.

Рядки також можна створювати з інших об’єктів за допомогою конструктора `str`.

Оскільки окремого типу «символів» немає, індексування рядка створює рядки довжиною 1. Тобто для непорожнього рядка s `s[0] == s[0:1]`.

Також немає змінного типу рядка, але `str.join()` або `io.StringIO` можна використовувати для ефективного створення рядків із кількох фрагментів.

Змінено в версії 3.3: Для зворотної сумісності з серією Python 2 префікс `u` знову дозволений у рядкових літералах. Він не впливає на значення рядкових літералів і не може поєднуватися з префіксом `r`.

class str(*, encoding='utf-8', errors='strict')
class str(object)
class str(object, encoding, errors='strict')
class str(object, *, errors)

  Повертає string версію об’єкта. Якщо object не надано, повертає порожній рядок. В іншому випадку поведінка `str()` залежить від того, чи вказано кодування чи помилки, як показано нижче.

  If neither encoding nor errors is given, `str(object)` returns `type(object).__str__(object)`, which is the «informal» or nicely printable string representation of object. For string objects, this is the string itself. If object does not have a `__str__()` method, then `str()` falls back to returning `repr(object)`.

  Якщо вказано принаймні одну з кодування або помилок, об’єкт має бути bytes-like object (наприклад, `bytes` або `bytearray`). У цьому випадку, якщо object є об’єктом `bytes` (або `bytearray`), тоді `str(bytes, encoding, errors)` еквівалентно `bytes.decode (кодування, помилки)`. В іншому випадку об’єкт bytes, що лежить в основі об’єкта буфера, отримується перед викликом `bytes.decode()`. Перегляньте Типи бінарних послідовностей — bytes, bytearray, memoryview і Буферний протокол для отримання інформації про буферні об’єкти.

  Передача об’єкта `bytes` до `str()` без аргументів encoding або errors підпадає під перший випадок повернення неформального представлення рядка (див. також команду `-b`- рядок для Python). Наприклад:

      >>> str(b'Zoot!')
      "b'Zoot!'"

  Додаткову інформацію про клас `str` і його методи див. у розділі Тип текстової послідовності — str і Рядкові методи нижче. Щоб вивести форматовані рядки, перегляньте розділи f-strings і Синтаксис рядка формату. Крім того, перегляньте розділ Послуги обробки тексту.

### Рядкові методи

Рядки реалізують усі загальні операції послідовності разом із додатковими методами, описаними нижче.

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

Розділ Послуги обробки тексту стандартної бібліотеки охоплює низку інших модулів, які надають різноманітні утиліти, пов’язані з текстом (зокрема підтримку регулярних виразів у модулі `re`).

str.capitalize()

  Повертає копію рядка з великим першим символом, а решта малими.

  Змінено в версії 3.8: Перший символ тепер вводиться в заголовок, а не у верхній регістр. Це означає, що такі символи, як диграфи, матимуть велику першу літеру, а не повний символ.

str.casefold()

  Повертає згорнуту копію рядка. Для зіставлення без регістру можна використовувати рядки з регістром.

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

  The casefolding algorithm is described in section 3.13 „Default Case Folding“ of the Unicode Standard.

  Added in version 3.3.

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

  Return centered in a string of length width. Padding is done using the specified fillchar (default is an ASCII space). The original string is returned if width is less than or equal to `len(s)`. For example:

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

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

  Повертає кількість неперекриваючих входжень підрядка sub у діапазоні [початок, кінець]. Необов’язкові аргументи початок і кінець інтерпретуються як у нотації фрагментів.

  If sub is empty, returns the number of empty strings between characters which is the length of the string plus one. For example:

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

  Return the string encoded to `bytes`.

  encoding defaults to `'utf-8'`; see Стандартні кодування for possible values.

  errors controls how encoding errors are handled. If `'strict'` (the default), a `UnicodeError` exception is raised. Other possible values are `'ignore'`, `'replace'`, `'xmlcharrefreplace'`, `'backslashreplace'` and any other name registered via `codecs.register_error()`. See Обробники помилок for details.

  For performance reasons, the value of errors is not checked for validity unless an encoding error actually occurs, Режим розробки Python is enabled or a debug build is used. For example:

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

  Змінено в версії 3.1: Додано підтримку аргументів ключових слів.

  Змінено в версії 3.9: The value of the errors argument is now checked in Режим розробки Python and in debug mode.

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

  Return `True` if the string ends with the specified suffix, otherwise return `False`. suffix can also be a tuple of suffixes to look for. With optional start, test beginning at that position. With optional end, stop comparing at that position. Using start and end is equivalent to `str[start:end].endswith(suffix)`. For example:

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

  See also `startswith()` and `removesuffix()`.

str.expandtabs(tabsize=8)

  Return a copy of the string where all tab characters are replaced by one or more spaces, depending on the current column and the given tab size. Tab positions occur every tabsize characters (default is 8, giving tab positions at columns 0, 8, 16 and so on). To expand the string, the current column is set to zero and the string is examined character by character. If the character is a tab (`\t`), one or more space characters are inserted in the result until the current column is equal to the next tab position. (The tab character itself is not copied.) If the character is a newline (`\n`) or return (`\r`), it is copied and the current column is reset to zero. Any other character is copied unchanged and the current column is incremented by one regardless of how the character is represented when printed. For example:

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

  Return the lowest index in the string where substring sub is found within the slice `s[start:end]`. Optional arguments start and end are interpreted as in slice notation. Return `-1` if sub is not found. For example:

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

  See also `rfind()` and `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'

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

  Примітка

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

  Змінено в версії 3.7: Під час форматування числа за допомогою типу `n`, у деяких випадках функція тимчасово встановлює `LC_CTYPE` локаль `LC_NUMERIC`.

str.format_map(mapping, /)

  Подібно до `str.format(**mapping)`, за винятком того, що `mapping` використовується безпосередньо, а не копіюється в `dict`. Це корисно, якщо, наприклад, `mapping` є підкласом dict:

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

  Added in version 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()

  Return `True` if all characters in the string are alphabetic and there is at least one character, `False` otherwise. Alphabetic characters are those characters defined in the Unicode character database as «Letter», i.e., those with general category property being one of «Lm», «Lt», «Lu», «Ll», or «Lo». Note that this is different from the Alphabetic property defined in the section 4.10 „Letters, Alphabetic, and Ideographic“ of the Unicode Standard.

str.isascii()

  Повертає `True`, якщо рядок порожній або всі символи в рядку є ASCII, `False` інакше. Символи ASCII мають кодові точки в діапазоні U+0000-U+007F.

  Added in version 3.7.

str.isdecimal()

  Повертає `True`, якщо всі символи в рядку є десятковими символами і є принаймні один символ, `False` інакше. Десяткові символи – це ті, які можна використовувати для утворення чисел за основою 10, напр. U+0660, АРАБСЬКО-ІНДІЙСЬКА ЦИФРА НУЛЬ. Формально десятковий символ — це символ у загальній категорії Unicode «Nd».

str.isdigit()

  Повертає `True`, якщо всі символи в рядку є цифрами і є принаймні один символ, `False` інакше. Цифри включають десяткові символи та цифри, які потребують спеціальної обробки, наприклад цифри сумісності над індексом. Це охоплює цифри, які не можна використовувати для формування чисел з основою 10, як-от числа Харості. Формально цифра — це символ, який має значення властивості Numeric_Type=Digit або Numeric_Type=Decimal.

str.isidentifier()

  Повертає `True`, якщо рядок є дійсним ідентифікатором відповідно до визначення мови, розділ Names (identifiers and keywords).

  `keyword.iskeyword()` can be used to test whether string `s` is a reserved identifier, such as `def` and `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, ВУЛЬГАРНА ФРАКЦІЯ ОДНА П’ЯТА. Формально цифровими символами є символи зі значенням властивості Numeric_Type=Digit, Numeric_Type=Decimal або Numeric_Type=Numeric.

str.isprintable()

  Return `True` if all characters in the string are printable, `False` if it contains at least one non-printable character.

  Here «printable» means the character is suitable for `repr()` to use in its output; «non-printable» means that `repr()` on built-in types will hex-escape the character. It has no bearing on the handling of strings written to `sys.stdout` or `sys.stderr`.

  The printable characters are those which in the Unicode character database (see `unicodedata`) have a general category in group Letter, Mark, Number, Punctuation, or Symbol (L, M, N, P, or S); plus the ASCII space 0x20. Nonprintable characters are those in group Separator or Other (Z or C), except the ASCII space.

str.isspace()

  Повертає `True`, якщо в рядку є лише пробіли та є принаймні один символ, `False` інакше.

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

str.istitle()

  Повертає `True`, якщо рядок є рядком із заголовком і містить принаймні один символ, наприклад, символи верхнього регістру можуть слідувати лише за символами без регістру, а символи нижнього регістру – лише за символами в регістрі. В іншому випадку поверніть `False`.

str.isupper()

  Повертає `True`, якщо всі символи регістру [4] в рядку є верхніми і є принаймні один символ регістру, `False` інакше.

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

str.join(iterable, /)

  Повертає рядок, який є конкатенацією рядків у iterable. Помилка `TypeError` буде викликана, якщо в iterable є будь-які нерядкові значення, включаючи об’єкти `bytes`. Роздільником між елементами є рядок, що забезпечує цей метод.

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

  Повертає рядок, вирівняний за лівим краєм, у рядку довжини width. Заповнення виконується за допомогою вказаного fillchar (за замовчуванням це пробіл ASCII). Оригінальний рядок повертається, якщо width менше або дорівнює `len(s)`.

str.lower()

  Повертає копію рядка з усіма регістровими символами [4], перетвореними на нижній регістр.

  The lowercasing algorithm used is described in section 3.13 „Default Case Folding“ of the Unicode Standard.

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`. Потім символьні ключі будуть перетворені на порядкові.

  If there are two arguments, they must be strings of equal length, and in the resulting dictionary, each character in from will be mapped to the character at the same position in to. If there is a third argument, it must be a string, whose characters will be mapped to `None` in the result.

str.partition(sep, /)

  Розділіть рядок при першому входженні sep і поверніть 3-кортеж, що містить частину перед роздільником, сам роздільник і частину після роздільника. Якщо роздільник не знайдено, поверніть 3-кортеж, що містить сам рядок, а потім два порожні рядки.

str.removeprefix(prefix, /)

  Якщо рядок починається з рядка prefix, поверніть `string[len(prefix):]`. В іншому випадку поверніть копію оригінального рядка:

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

  Added in version 3.9.

str.removesuffix(suffix, /)

  Якщо рядок закінчується рядком suffix і цей suffix не є порожнім, поверніть `string[:-len(suffix)]`. В іншому випадку поверніть копію оригінального рядка:

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

  Added in version 3.9.

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

  Return a copy of the string with all occurrences of substring old replaced by new. If count is given, only the first count occurrences are replaced. If count is not specified or `-1`, then all occurrences are replaced.

  Змінено в версії 3.13: count is now supported as a keyword argument.

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

  Повертає найвищий індекс у рядку, де знайдено підрядок sub, так що sub міститься в `s[start:end]`. Необов’язкові аргументи початок і кінець інтерпретуються як у нотації фрагментів. Повернути `-1` у разі помилки.

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

  Подібно до `rfind()`, але викликає `ValueError`, коли підрядок sub не знайдено.

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

  Повертає рядок, вирівняний по правому краю, у рядку довжини width. Заповнення виконується за допомогою вказаного fillchar (за замовчуванням це пробіл ASCII). Оригінальний рядок повертається, якщо width менше або дорівнює `len(s)`.

str.rpartition(sep, /)

  Розділіть рядок на останнє входження sep і поверніть 3-кортеж, що містить частину перед роздільником, сам роздільник і частину після роздільника. Якщо роздільник не знайдено, поверніть 3-кортеж, що містить два порожні рядки, а потім сам рядок.

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

  Повертає список слів у рядку, використовуючи sep як роздільник. Якщо задано maxsplit, виконується щонайбільше maxsplit розбиття, найправіші. Якщо sep не вказано або `None`, будь-який пробільний рядок є роздільником. За винятком розділення справа, `rsplit()` поводиться як `split()`, що детально описано нижче.

str.rstrip(chars=None, /)

  Повертає копію рядка з видаленими кінцевими символами. Аргумент chars — це рядок, який визначає набір символів, які потрібно видалити. Якщо пропущено або `None`, аргумент chars за умовчанням видаляє пробіли. Аргумент chars не є суфіксом; навпаки, усі комбінації його значень видаляються:

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

  Перегляньте `str.removesuffix()` для методу, який видаляє один рядок суфікса, а не весь набір символів. Наприклад:

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

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

  Повертає список слів у рядку, використовуючи sep як роздільник. Якщо вказано maxsplit, виконується щонайбільше maxsplit розбиття (отже, список міститиме щонайбільше елементів `maxsplit+1`). Якщо maxsplit не вказано або `-1`, тоді немає обмеження на кількість розділень (виконуються всі можливі розділення).

  If sep is given, consecutive delimiters are not grouped together and are deemed to delimit empty strings (for example, `'1,,2'.split(',')` returns `['1', '', '2']`). The sep argument may consist of multiple characters as a single delimiter (to split with multiple delimiters, use `re.split()`). Splitting an empty string with a specified separator returns `['']`.

  Наприклад:

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

  If sep is not specified or is `None` and maxsplit is `0`, only leading runs of consecutive whitespace are considered.

  Наприклад:

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

str.splitlines(keepends=False)

  Повертає список рядків у рядку, розриваючи межі рядків. Розриви рядків не включаються в результуючий список, якщо keepends не задано і не відповідає дійсності.

  Цей метод розбивається на наступні межі рядків. Зокрема, межі є надмножиною universal newlines.

  Представництво | опис
  --- | ---
  `\n` | Переведення рядка
  `\r` | Повернення каретки
  `\r\n` | Повернення каретки + Переведення рядка
  `\v` або `\x0b` | Лінія табуляції
  `\f` або `\x0c` | Подача форми
  `\x1c` | Роздільник файлів
  `\x1d` | Роздільник груп
  `\x1e` | Розділювач записів
  `\x85` | Наступний рядок (контрольний код C1)
  `\u2028` | Розділювач рядків
  `\u2029` | Роздільник абзаців

  Змінено в версії 3.2: `\v` і `\f` додано до списку меж ліній.

  Наприклад:

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

  На відміну від `split()`, коли задано рядок роздільника sep, цей метод повертає порожній список для порожнього рядка, а розрив кінцевого рядка не призводить до додаткового рядка:

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

  Для порівняння `split('\n')` дає:

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

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

  Повертає `True`, якщо рядок починається з префікса, інакше повертає `False`. префікс також може бути кортежем префіксів для пошуку. З необов’язковим початком, тестовий рядок починається з цієї позиції. З необов’язковим end припиняє порівнювати рядок у цій позиції.

str.strip(chars=None, /)

  Повертає копію рядка з видаленими початковими та кінцевими символами. Аргумент chars — це рядок, який визначає набір символів, які потрібно видалити. Якщо пропущено або `None`, аргумент chars за умовчанням видаляє пробіли. Аргумент chars не є префіксом або суфіксом; навпаки, усі комбінації його значень видаляються:

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

  Зовнішні початкові та кінцеві значення аргументів chars видаляються з рядка. Символи видаляються з початку, доки не досягнеться символ рядка, який не міститься в наборі символів у chars. Подібна дія відбувається на кінці. Наприклад:

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

str.swapcase()

  Повертає копію рядка з символами верхнього регістру, перетвореними на малі, і навпаки. Зауважте, що `s.swapcase().swapcase() == s` не обов’язково правда.

str.title()

  Повертає версію рядка в заголовку, де слова починаються з великої літери, а решта символів – нижніми.

  Наприклад:

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

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

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

  Функція `string.capwords()` не має цієї проблеми, оскільки вона розділяє слова лише на пробіли.

  Крім того, обхідний шлях для апострофів можна створити за допомогою регулярних виразів:

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

str.translate(table, /)

  Return a copy of the string in which each character has been mapped through the given translation table. The table must be an object that implements indexing via `__getitem__()`, typically a mapping or sequence. When indexed by a Unicode ordinal (an integer), the table object can do any of the following: return a Unicode ordinal or a string, to map the character to one or more other characters; return `None`, to delete the character from the return string; or raise a `LookupError` exception, to map the character to itself.

  Ви можете використовувати `str.maketrans()`, щоб створити карту перекладу з відображень символів у різні формати.

  Перегляньте також модуль `codecs` для більш гнучкого підходу до нестандартних відображень символів.

str.upper()

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

  The uppercasing algorithm used is described in section 3.13 „Default Case Folding“ of the Unicode Standard.

str.zfill(width, /)

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

  Наприклад:

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

### Formatted String Literals (f-strings)

Added in version 3.6.

Змінено в версії 3.7: The `await` and `async for` can be used in expressions within f-strings.

Змінено в версії 3.8: Added the debugging operator (`=`)

Змінено в версії 3.12: Many restrictions on expressions within f-strings have been removed. Notably, nested strings, comments, and backslashes are now permitted.

An f-string (formally a formatted string literal) is a string literal that is prefixed with `f` or `F`. This type of string literal allows embedding arbitrary Python expressions within replacement fields, which are delimited by curly brackets (`{}`). These expressions are evaluated at runtime, similarly to `str.format()`, and are converted into regular `str` objects. For example:

    >>> who = 'nobody'
    >>> nationality = 'Spanish'
    >>> f'{who.title()} expects the {nationality} Inquisition!'
    'Nobody expects the Spanish Inquisition!'

It is also possible to use a multi line f-string:

    >>> f'''This is a string
    ... on two lines'''
    'This is a string\non two lines'

A single opening curly bracket, `'{'`, marks a replacement field that can contain any Python expression:

    >>> nationality = 'Spanish'
    >>> f'The {nationality} Inquisition!'
    'The Spanish Inquisition!'

To include a literal `{` or `}`, use a double bracket:

    >>> x = 42
    >>> f'{{x}} is {x}'
    '{x} is 42'

Functions can also be used, and format specifiers:

    >>> from math import sqrt
    >>> f'√2 \N{ALMOST EQUAL TO} {sqrt(2):.5f}'
    '√2 ≈ 1.41421'

Any non-string expression is converted using `str()`, by default:

    >>> from fractions import Fraction
    >>> f'{Fraction(1, 3)}'
    '1/3'

To use an explicit conversion, use the `!` (exclamation mark) operator, followed by any of the valid formats, which are:

Перетворення | Значення
--- | ---
`!a` | `ascii()`
`!r` | `repr()`
`!s` | `str()`

Наприклад:

    >>> from fractions import Fraction
    >>> f'{Fraction(1, 3)!s}'
    '1/3'
    >>> f'{Fraction(1, 3)!r}'
    'Fraction(1, 3)'
    >>> question = '¿Dónde está el Presidente?'
    >>> print(f'{question!a}')
    '\xbfD\xf3nde est\xe1 el Presidente?'

While debugging it may be helpful to see both the expression and its value, by using the equals sign (`=`) after the expression. This preserves spaces within the brackets, and can be used with a converter. By default, the debugging operator uses the `repr()` (`!r`) conversion. For example:

    >>> from fractions import Fraction
    >>> calculation = Fraction(1, 3)
    >>> f'{calculation=}'
    'calculation=Fraction(1, 3)'
    >>> f'{calculation = }'
    'calculation = Fraction(1, 3)'
    >>> f'{calculation = !s}'
    'calculation = 1/3'

Once the output has been evaluated, it can be formatted using a format specifier following a colon (`':'`). After the expression has been evaluated, and possibly converted to a string, the `__format__()` method of the result is called with the format specifier, or the empty string if no format specifier is given. The formatted result is then used as the final value for the replacement field. For example:

    >>> from fractions import Fraction
    >>> f'{Fraction(1, 7):.6f}'
    '0.142857'
    >>> f'{Fraction(1, 7):_^+10}'
    '___+1/7___'

### Форматування рядків у стилі `printf`

Примітка

The formatting operations described here exhibit a variety of quirks that lead to a number of common errors (such as failing to display tuples and dictionaries correctly).

Using formatted string literals, the `str.format()` interface, or `string.Template` may help avoid these errors. Each of these alternatives provides their own trade-offs and benefits of simplicity, flexibility, and/or extensibility.

String objects have one unique built-in operation: the `%` operator (modulo). This is also known as the string formatting or interpolation operator. Given `format % values` (where format is a string), `%` conversion specifications in format are replaced with zero or more elements of values. The effect is similar to using the `sprintf()` function in the C language. For example:

    >>> print('%s has %d quote types.' % ('Python', 2))
    Python has 2 quote types.

Якщо для format потрібен один аргумент, values може бути одним некортежним об’єктом. [5] В іншому випадку values має бути кортежем із точною кількістю елементів, визначених рядком формату, або одним об’єктом відображення (наприклад, словником).

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

1. Символ `'%'`, який позначає початок специфікатора.

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

3. Прапорці перетворення (опціонально), які впливають на результат деяких типів перетворення.

4. Мінімальна ширина поля (опціонально). Якщо вказано як `'*'` (зірочка), фактична ширина зчитується з наступного елемента кортежу в значеннях, а об’єкт для перетворення йде після мінімальної ширини поля та необов’язкової точності.

5. Точність (необов’язкова), подається як `'.'` (крапка), за якою йде точність. Якщо вказано як `'*'` (зірочка), фактична точність зчитується з наступного елемента кортежу в значеннях, а значення для перетворення йде після точності.

6. Модифікатор довжини (необов’язково).

7. Тип перетворення.

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

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

У цьому випадку у форматі не може бути специфікаторів `*` (оскільки вони вимагають послідовного списку параметрів).

Символи прапора перетворення:

Прапор | Значення
--- | ---
`'#''` | Перетворення значень використовуватиме «альтернативну форму» (де визначено нижче).
`'0'` | Перетворення буде доповнено нулем для числових значень.
`'-'` | Перетворене значення коригується зліва (перевизначає перетворення `'0'`, якщо подано обидва значення).
`' '` | (пробіл) Пробіл слід залишити перед додатним числом (або порожнім рядком), утвореним перетворенням зі знаком.
`'+'` | Символ знака (`'+'` або `'-'`) передуватиме перетворенню (перевизначає позначку «пробіл»).

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

Типи перетворення:

Перетворення | Значення | Примітки
--- | --- | ---
`'d''` | Ціле десяткове число зі знаком. |
`'я''` | Ціле десяткове число зі знаком. |
`'o'` | Вісімкове значення зі знаком. | (1)
`'u''` | Застарілий тип – він ідентичний `'d'`. | (6)
`'x''` | Шістнадцяткове число зі знаком (нижній регістр). | (2)
`'X''` | Шістнадцяткове число зі знаком (верхній регістр). | (2)
`'e''` | Floating-point exponential format (lowercase). | (3)
`'E'` | Floating-point exponential format (uppercase). | (3)
`'f''` | Floating-point decimal format. | (3)
`'F''` | Floating-point decimal format. | (3)
`'g''` | Floating-point format. Uses lowercase exponential format if exponent is less than -4 or not less than precision, decimal format otherwise. | (4)
`'G''` | Floating-point format. Uses uppercase exponential format if exponent is less than -4 or not less than precision, decimal format otherwise. | (4)
`'c''` | Один символ (приймає рядок цілих чи односимвольних символів). |
`'r''` | Рядок (перетворює будь-який об’єкт Python за допомогою `repr()`). | (5)
`'s''` | Рядок (перетворює будь-який об’єкт Python за допомогою `str()`). | (5)
`'a'` | Рядок (перетворює будь-який об’єкт Python за допомогою `ascii()`). | (5)
`'%'` | Жоден аргумент не перетворюється, результатом є символ `'%'` в результаті. |

Примітки:

1. Альтернативна форма призводить до того, що початковий вісімковий специфікатор (`'0o'`) буде вставлено перед першою цифрою.

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

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

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

4. Альтернативна форма призводить до того, що результат завжди містить десяткову кому, а кінцеві нулі не видаляються, як це було б інакше.

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

5. Якщо точність `N`, вивід скорочується до `N` символів.

6. Дивіться PEP 237.

Оскільки рядки Python мають явну довжину, перетворення `%s` не припускають, що `'\0` є кінцем рядка.

Змінено в версії 3.1: Перетворення `%f` для чисел, абсолютне значення яких перевищує 1e50, більше не замінюються перетвореннями `%g`.

## Типи бінарних послідовностей — `bytes`, `bytearray`, `memoryview`

Основними вбудованими типами для обробки двійкових даних є `bytes` і `bytearray`. Вони підтримуються `memoryview`, який використовує протокол буфера для доступу до пам’яті інших бінарних об’єктів без необхідності створення копії.

Модуль `array` підтримує ефективне зберігання основних типів даних, таких як 32-розрядні цілі числа та плаваючі значення подвійної точності IEEE754.

### Об’єкти Bytes

Об’єкти Bytes — це незмінні послідовності окремих байтів. Оскільки багато основних двійкових протоколів базуються на текстовому кодуванні ASCII, об’єкти bytes пропонують кілька методів, які дійсні лише під час роботи з даними, сумісними з ASCII, і тісно пов’язані з рядковими об’єктами різними способами.

class bytes(source=b'')
class bytes(source, encoding, errors='strict')

  По-перше, синтаксис байтових літералів здебільшого такий самий, як і для рядкових літералів, за винятком того, що додано префікс `b`:

  - Одинарні лапки: `b'все ще дозволяє вбудовані "подвійні" лапки`

  - Подвійні лапки: `b"все ще дозволяє вбудовані 'одинарні' лапки`

  - Потрійні лапки: `b''''3 одинарні лапки''''`, `b"""3 подвійні лапки"""`

  У байтових літералах дозволені лише символи ASCII (незалежно від оголошеного кодування вихідного коду). Будь-які двійкові значення понад 127 потрібно вводити в байтові літерали за допомогою відповідної керуючої послідовності.

  Як і рядкові літерали, літерали bytes також можуть використовувати префікс `r`, щоб вимкнути обробку керуючих послідовностей. Перегляньте Рядкові та байтові літерали, щоб дізнатися більше про різні форми літералів байтів, включаючи підтримувані керуючі послідовності.

  У той час як байтові літерали та представлення базуються на тексті ASCII, об’єкти байтів фактично поводяться як незмінні послідовності цілих чисел, де кожне значення в послідовності обмежено таким чином, що `0 <= x < 256` (спроби порушити це обмеження викличуть `ValueError`). Це зроблено навмисно, щоб підкреслити, що хоча багато двійкових форматів включають елементи на основі ASCII і ними можна корисно маніпулювати за допомогою деяких текстово-орієнтованих алгоритмів, це зазвичай не стосується довільних двійкових даних (сліпе застосування алгоритмів обробки тексту до двійкових форматів даних, які не Сумісність із ASCII зазвичай призводить до пошкодження даних).

  Окрім літеральних форм, об’єкти bytes можна створювати кількома іншими способами:

  - Об’єкт із заповненими нулем байтами вказаної довжини: `bytes(10)`

  - З ітерації цілих чисел: `bytes(range(20))`

  - Копіювання існуючих двійкових даних через протокол буфера: `bytes(obj)`

  Також перегляньте вбудований bytes.

  Оскільки 2 шістнадцяткові цифри точно відповідають одному байту, шістнадцяткові числа є широко використовуваним форматом для опису двійкових даних. Відповідно, тип bytes має додатковий метод класу для читання даних у цьому форматі:

  classmethod fromhex(string, /)

    Цей метод класу `bytes` повертає об’єкт bytes, декодуючи даний рядковий об’єкт. Рядок має містити дві шістнадцяткові цифри на байт, при цьому пробіли ASCII ігноруються.

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

    Змінено в версії 3.7: `bytes.fromhex()` тепер пропускає всі пробіли ASCII у рядку, а не лише пробіли.

    Змінено в версії 3.14: `bytes.fromhex()` now accepts ASCII `bytes` and bytes-like objects as input.

  Існує функція зворотного перетворення для перетворення об’єкта байтів у його шістнадцяткове представлення.

  hex(*, bytes_per_sep=1)
  hex(sep, bytes_per_sep=1)

    Повертає рядковий об’єкт, що містить дві шістнадцяткові цифри для кожного байта екземпляра.

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

    If you want to make the hex string easier to read, you can specify a single character separator sep parameter to include in the output. By default, this separator will be included between each byte. A second optional bytes_per_sep parameter controls the spacing. Positive values calculate the separator position from the right, negative values from the left.

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

    Added in version 3.5.

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

Оскільки об’єкти bytes — це послідовності цілих чисел (подібно до кортежу), для об’єкта bytes b «b[0]» буде цілим числом, тоді як «b[0:1]» буде байтом об’єкт довжини 1. (Це контрастує з текстовими рядками, де як індексування, так і нарізка створять рядок довжиною 1)

Для представлення об’єктів bytes використовується літеральний формат (`b'...''`), оскільки він часто корисніший, ніж, наприклад, `bytes([46, 46, 46])`. Ви завжди можете перетворити об’єкт bytes на список цілих чисел за допомогою `list(b)`.

### Об’єкти байтового масиву

Об’єкти `bytearray` є змінними аналогами об’єктів `bytes`.

class bytearray(source=b'')
class bytearray(source, encoding, errors='strict')

  Для об’єктів bytearray немає виділеного синтаксису літералів, натомість вони завжди створюються шляхом виклику конструктора:

  - Створення порожнього екземпляра: `bytearray()`

  - Створення екземпляра із заповненням нуля із заданою довжиною: `bytearray(10)`

  - З ітерації цілих чисел: `bytearray(range(20))`

  - Копіювання наявних двійкових даних за допомогою буферного протоколу: `bytearray(b'Hi!')`

  Оскільки об’єкти bytearray є змінними, вони підтримують операції послідовності mutable на додаток до звичайних операцій з байтами та байтовими масивами, описаних у Операції з байтами та масивом байтів.

  Також перегляньте вбудований bytearray.

  Оскільки 2 шістнадцяткові цифри точно відповідають одному байту, шістнадцяткові числа є широко використовуваним форматом для опису двійкових даних. Відповідно, тип bytearray має додатковий метод класу для читання даних у цьому форматі:

  classmethod fromhex(string, /)

    Цей метод класу `bytearray` повертає об’єкт bytearray, декодуючи заданий рядковий об’єкт. Рядок має містити дві шістнадцяткові цифри на байт, при цьому пробіли ASCII ігноруються.

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

    Змінено в версії 3.7: `bytearray.fromhex()` тепер пропускає всі пробіли ASCII у рядку, а не лише пробіли.

    Змінено в версії 3.14: `bytearray.fromhex()` now accepts ASCII `bytes` and bytes-like objects as input.

  Існує функція зворотного перетворення для перетворення об’єкта байтового масиву в його шістнадцяткове представлення.

  hex(*, bytes_per_sep=1)
  hex(sep, bytes_per_sep=1)

    Повертає рядковий об’єкт, що містить дві шістнадцяткові цифри для кожного байта екземпляра.

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

    Added in version 3.5.

    Змінено в версії 3.8: Подібно до `bytes.hex()`, `bytearray.hex()` тепер підтримує додаткові параметри sep і bytes_per_sep для вставки роздільників між байтами в шістнадцятковому виведенні.

  resize(size, /)

    Resize the `bytearray` to contain size bytes. size must be greater than or equal to 0.

    If the `bytearray` needs to shrink, bytes beyond size are truncated.

    If the `bytearray` needs to grow, all new bytes, those beyond size, will be set to null bytes.

    This is equivalent to:

        >>> def resize(ba, size):
        ...     if len(ba) > size:
        ...         del ba[size:]
        ...     else:
        ...         ba += b'\0' * (size - len(ba))

    Examples:

        >>> shrink = bytearray(b'abc')
        >>> shrink.resize(1)
        >>> (shrink, len(shrink))
        (bytearray(b'a'), 1)
        >>> grow = bytearray(b'abc')
        >>> grow.resize(5)
        >>> (grow, len(grow))
        (bytearray(b'abc\x00\x00'), 5)

    Added in version 3.14.

Оскільки об’єкти bytearray — це послідовності цілих чисел (схожі на список), для об’єкта bytearray b «b[0]» буде цілим числом, а «b[0:1]» буде масивом bytearray об’єкт довжини 1. (Це контрастує з текстовими рядками, де як індексування, так і нарізка створять рядок довжиною 1)

У представленні об’єктів bytearray використовується формат літералу bytes (`bytearray(b'...')`), оскільки він часто корисніший, ніж, наприклад, `bytearray([46, 46, 46])`. Ви завжди можете перетворити об’єкт bytearray на список цілих чисел за допомогою `list(b)`.

### Операції з байтами та масивом байтів

Як об’єкти bytes, так і bytearray підтримують операції послідовності common. Вони взаємодіють не тільки з операндами того самого типу, але й з будь-яким bytes-like object. Завдяки цій гнучкості їх можна вільно змішувати під час операцій, не викликаючи помилок. Однак тип результату може залежати від порядку операндів.

Примітка

Методи для об’єктів bytes і bytearray не приймають рядки як аргументи, так само як методи для рядків не приймають байти як аргументи. Наприклад, ви повинні написати:

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

і:

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

Деякі операції з байтами та масивами байтів передбачають використання двійкових форматів, сумісних із ASCII, і тому їх слід уникати під час роботи з довільними двійковими даними. Ці обмеження описані нижче.

Примітка

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

Наступні методи для об’єктів bytes і bytearray можна використовувати з довільними двійковими даними.

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

  Повертає кількість неперекриваючих входжень підпослідовності sub у діапазоні [початок, кінець]. Необов’язкові аргументи початок і кінець інтерпретуються як у нотації фрагментів.

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

  If sub is empty, returns the number of empty slices between characters which is the length of the bytes object plus one.

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

bytes.removeprefix(prefix, /)
bytearray.removeprefix(prefix, /)

  Якщо двійкові дані починаються з рядка prefix, поверніть `bytes[len(prefix):]`. В іншому випадку поверніть копію вихідних двійкових даних:

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

  Префікс може бути будь-яким bytes-like object.

  Примітка

  Версія bytearray цього методу не працює на місці – вона завжди створює новий об’єкт, навіть якщо не було зроблено жодних змін.

  Added in version 3.9.

bytes.removesuffix(suffix, /)
bytearray.removesuffix(suffix, /)

  Якщо двійкові дані закінчуються рядком суфікса і цей суфікс не порожній, поверніть `bytes[:-len(suffix)]`. В іншому випадку поверніть копію вихідних двійкових даних:

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

  Суфіксом може бути будь-який bytes-like object.

  Примітка

  Версія bytearray цього методу не працює на місці – вона завжди створює новий об’єкт, навіть якщо не було зроблено жодних змін.

  Added in version 3.9.

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

  Return the bytes decoded to a `str`.

  encoding defaults to `'utf-8'`; see Стандартні кодування for possible values.

  errors controls how decoding errors are handled. If `'strict'` (the default), a `UnicodeError` exception is raised. Other possible values are `'ignore'`, `'replace'`, and any other name registered via `codecs.register_error()`. See Обробники помилок for details.

  For performance reasons, the value of errors is not checked for validity unless a decoding error actually occurs, Режим розробки Python is enabled or a debug build is used.

  Примітка

  Passing the encoding argument to `str` allows decoding any bytes-like object directly, without needing to make a temporary `bytes` or `bytearray` object.

  Змінено в версії 3.1: Додано підтримку аргументів ключових слів.

  Змінено в версії 3.9: The value of the errors argument is now checked in Режим розробки Python and in debug mode.

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

  Повертає `True`, якщо двійкові дані закінчуються вказаним суфіксом, інакше повертає `False`. suffix також може бути кортежем суфіксів для пошуку. З необов’язковим початком тестування починається з цієї позиції. З необов’язковим end, припинити порівняння на цій позиції.

  Суфікс(и) для пошуку може бути будь-яким bytes-like object.

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

  Повертає найнижчий індекс у даних, де знайдено підпослідовність sub, так що sub міститься в сегменті `s[start:end]`. Необов’язкові аргументи початок і кінець інтерпретуються як у нотації фрагментів. Повертає `-1`, якщо sub не знайдено.

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

  Примітка

  Метод `find()` слід використовувати, лише якщо вам потрібно знати позицію sub. Щоб перевірити, чи є sub підрядком, скористайтеся оператором `in`:

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

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

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

  Як `find()`, але викликає `ValueError`, коли підпослідовність не знайдено.

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

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

bytes.join(iterable, /)
bytearray.join(iterable, /)

  Повертає об’єкт bytes або bytearray, який є конкатенацією двійкових послідовностей даних у iterable. Помилка `TypeError` буде викликана, якщо в iterable є будь-які значення, які не є bytes-подібними об’єктами, включаючи об’єкти `str`. Роздільником між елементами є вміст об’єкта bytes або bytearray, що забезпечує цей метод.

static bytes.maketrans(from, to, /)
static bytearray.maketrans(from, to, /)

  Цей статичний метод повертає таблицю перекладу, придатну для `bytes.translate()`, яка відобразить кожен символ у from на символ у тій же позиції в to; from і to мають бути байтоподібними об’єктами і мати однакову довжину.

  Added in version 3.1.

bytes.partition(sep, /)
bytearray.partition(sep, /)

  Розділіть послідовність при першому входженні sep і поверніть 3-кортеж, що містить частину перед роздільником, сам роздільник або його копію байтового масиву та частину після роздільника. Якщо роздільник не знайдено, поверніть 3-кортеж, що містить копію вихідної послідовності, за якою слідують два порожні байти або об’єкти bytearray.

  Роздільником для пошуку може бути будь-який bytes-like object.

bytes.replace(old, new, count=-1, /)
bytearray.replace(old, new, count=-1, /)

  Повертає копію послідовності з заміною всіх входжень підпослідовності old на new. Якщо вказано необов’язковий аргумент count, заміняються лише перші випадки count.

  Підпослідовністю для пошуку та її заміною може бути будь-який bytes-like object.

  Примітка

  Версія bytearray цього методу не працює на місці – вона завжди створює новий об’єкт, навіть якщо не було зроблено жодних змін.

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

  Повертає найвищий індекс у послідовності, де знайдено підпослідовність sub, так що sub міститься в `s[start:end]`. Необов’язкові аргументи початок і кінець інтерпретуються як у нотації фрагментів. Повернути `-1` у разі помилки.

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

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

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

  Подібно до `rfind()`, але викликає `ValueError`, коли підпослідовність sub не знайдено.

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

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

bytes.rpartition(sep, /)
bytearray.rpartition(sep, /)

  Розділіть послідовність при останньому входженні sep і поверніть 3-кортеж, що містить частину перед роздільником, сам роздільник або його копію байтового масиву та частину після роздільника. Якщо роздільник не знайдено, поверніть 3-кортеж, що містить два порожні об’єкти байтів або масиву байтів, а потім копію вихідної послідовності.

  Роздільником для пошуку може бути будь-який bytes-like object.

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

  Повертає `True`, якщо двійкові дані починаються з указаного префікса, інакше повертає `False`. префікс також може бути кортежем префіксів для пошуку. З необов’язковим початком тестування починається з цієї позиції. З необов’язковим end, припинити порівняння на цій позиції.

  Префікс(и) для пошуку може бути будь-яким bytes-like object.

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

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

  Ви можете використовувати метод `bytes.maketrans()` для створення таблиці перекладу.

  Встановіть для аргументу table значення `None` для перекладів, які видаляють лише символи:

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

  Змінено в версії 3.6: delete тепер підтримується як аргумент ключового слова.

Наведені нижче методи для об’єктів bytes і bytearray мають поведінку за замовчуванням, яка передбачає використання ASCII-сумісних двійкових форматів, але все одно їх можна використовувати з довільними двійковими даними шляхом передачі відповідних аргументів. Зауважте, що всі методи bytearray у цьому розділі не працюють на місці, а створюють нові об’єкти.

bytes.center(width, fillbyte=b' ', /)
bytearray.center(width, fillbyte=b' ', /)

  Повертає копію об’єкта з центром у послідовності довжиною шириною. Доповнення виконується за допомогою вказаного fillbyte (за замовчуванням це пробіл ASCII). Для об’єктів `bytes` оригінальна послідовність повертається, якщо width менше або дорівнює `len(s)`.

  Примітка

  Версія bytearray цього методу не працює на місці – вона завжди створює новий об’єкт, навіть якщо не було зроблено жодних змін.

bytes.ljust(width, fillbyte=b' ', /)
bytearray.ljust(width, fillbyte=b' ', /)

  Повертає копію об’єкта, вирівняну за лівим краєм у послідовності довжини ширина. Доповнення виконується за допомогою вказаного fillbyte (за замовчуванням це пробіл ASCII). Для об’єктів `bytes` вихідна послідовність повертається, якщо width менше або дорівнює `len(s)`.

  Примітка

  Версія bytearray цього методу не працює на місці – вона завжди створює новий об’єкт, навіть якщо не було зроблено жодних змін.

bytes.lstrip(bytes=None, /)
bytearray.lstrip(bytes=None, /)

  Return a copy of the sequence with specified leading bytes removed. The bytes argument is a binary sequence specifying the set of byte values to be removed. If omitted or `None`, the bytes argument defaults to removing ASCII whitespace. The bytes argument is not a prefix; rather, all combinations of its values are stripped:

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

  Двійкова послідовність байтових значень для видалення може бути будь-яким bytes-like object. Перегляньте `removeprefix()` для методу, який видаляє один рядок префікса, а не весь набір символів. Наприклад:

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

  Примітка

  Версія bytearray цього методу не працює на місці – вона завжди створює новий об’єкт, навіть якщо не було зроблено жодних змін.

bytes.rjust(width, fillbyte=b' ', /)
bytearray.rjust(width, fillbyte=b' ', /)

  Повертає копію об’єкта, вирівняну по правому краю в послідовності довжина ширина. Доповнення виконується за допомогою вказаного fillbyte (за замовчуванням це пробіл ASCII). Для об’єктів `bytes` оригінальна послідовність повертається, якщо width менше або дорівнює `len(s)`.

  Примітка

  Версія bytearray цього методу не працює на місці – вона завжди створює новий об’єкт, навіть якщо не було зроблено жодних змін.

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

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

bytes.rstrip(bytes=None, /)
bytearray.rstrip(bytes=None, /)

  Return a copy of the sequence with specified trailing bytes removed. The bytes argument is a binary sequence specifying the set of byte values to be removed. If omitted or `None`, the bytes argument defaults to removing ASCII whitespace. The bytes argument is not a suffix; rather, all combinations of its values are stripped:

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

  Двійкова послідовність байтових значень для видалення може бути будь-яким bytes-like object. Перегляньте `removesuffix()`, щоб дізнатися про метод, який видалить один рядок суфікса, а не весь набір символів. Наприклад:

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

  Примітка

  Версія bytearray цього методу не працює на місці – вона завжди створює новий об’єкт, навіть якщо не було зроблено жодних змін.

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

  Розділіть бінарну послідовність на підпослідовності одного типу, використовуючи sep як рядок-роздільник. Якщо задано maxsplit і воно є невід’ємним, виконується щонайбільше розділень maxsplit (отже, список матиме щонайбільше елементів `maxsplit+1`). Якщо maxsplit не вказано або дорівнює `-1`, тоді немає обмежень на кількість розбивок (виконуються всі можливі розбиття).

  If sep is given, consecutive delimiters are not grouped together and are deemed to delimit empty subsequences (for example, `b'1,,2'.split(b',')` returns `[b'1', b'', b'2']`). The sep argument may consist of a multibyte sequence as a single delimiter. Splitting an empty sequence with a specified separator returns `[b'']` or `[bytearray(b'')]` depending on the type of object being split. The sep argument may be any bytes-like object.

  Наприклад:

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

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

  Наприклад:

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

bytes.strip(bytes=None, /)
bytearray.strip(bytes=None, /)

  Return a copy of the sequence with specified leading and trailing bytes removed. The bytes argument is a binary sequence specifying the set of byte values to be removed. If omitted or `None`, the bytes argument defaults to removing ASCII whitespace. The bytes argument is not a prefix or suffix; rather, all combinations of its values are stripped:

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

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

  Примітка

  Версія bytearray цього методу не працює на місці – вона завжди створює новий об’єкт, навіть якщо не було зроблено жодних змін.

Наступні методи для об’єктів bytes і bytearray передбачають використання двійкових форматів, сумісних із ASCII, і їх не слід застосовувати до довільних двійкових даних. Зауважте, що всі методи bytearray у цьому розділі не працюють на місці, а створюють нові об’єкти.

bytes.capitalize()
bytearray.capitalize()

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

  Примітка

  Версія bytearray цього методу не працює на місці – вона завжди створює новий об’єкт, навіть якщо не було зроблено жодних змін.

bytes.expandtabs(tabsize=8)
bytearray.expandtabs(tabsize=8)

  Повертає копію послідовності, де всі символи табуляції ASCII замінено одним або декількома пробілами ASCII, залежно від поточного стовпця та заданого розміру табуляції. Позиції табуляції відбуваються кожні байти табуляції (за замовчуванням — 8, надаючи позиції табуляції в стовпцях 0, 8, 16 і так далі). Щоб розширити послідовність, поточний стовпець встановлюється на нуль і послідовність перевіряється побайтно. Якщо байт є символом табуляції ASCII (`b'\t'`), один або більше символів пробілу вставляються в результат, доки поточний стовпець не буде відповідати наступній позиції табуляції. (Сам символ табуляції не копіюється.) Якщо поточний байт є ASCII символом нового рядка (`b'\n'`) або поверненням каретки (`b'\r'`), він копіюється і поточний стовпець скидається на нуль. Будь-яке інше значення байта копіюється без змін, а поточний стовпець збільшується на одиницю незалежно від того, як значення байта представлено під час друку:

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

  Примітка

  Версія bytearray цього методу не працює на місці – вона завжди створює новий об’єкт, навіть якщо не було зроблено жодних змін.

bytes.isalnum()
bytearray.isalnum()

  Повертає `True`, якщо всі байти в послідовності є алфавітними символами ASCII або десятковими цифрами ASCII і послідовність не є порожньою, `False` інакше. Алфавітні символи ASCII – це значення байтів у послідовності `b'abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ`. Десяткові цифри ASCII – це значення байтів у послідовності `b'0123456789`.

  Наприклад:

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

bytes.isalpha()
bytearray.isalpha()

  Повертає `True`, якщо всі байти в послідовності є алфавітними символами ASCII і послідовність не є пустою, `False` інакше. Алфавітні символи ASCII – це значення байтів у послідовності `b'abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ`.

  Наприклад:

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

bytes.isascii()
bytearray.isascii()

  Повертає `True`, якщо послідовність порожня або всі байти в послідовності ASCII, `False` інакше. Байти ASCII знаходяться в діапазоні 0-0x7F.

  Added in version 3.7.

bytes.isdigit()
bytearray.isdigit()

  Повертає `True`, якщо всі байти в послідовності є десятковими цифрами ASCII і послідовність не порожня, `False` інакше. Десяткові цифри ASCII – це значення байтів у послідовності `b'0123456789`.

  Наприклад:

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

bytes.islower()
bytearray.islower()

  Повертає `True`, якщо в послідовності є принаймні один символ нижнього регістру ASCII і немає символів ASCII у верхньому регістрі, інакше `False`.

  Наприклад:

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

  Символи ASCII у нижньому регістрі – це значення байтів у послідовності `b'abcdefghijklmnopqrstuvwxyz`. Символи ASCII у верхньому регістрі – це значення байтів у послідовності `b'ABCDEFGHIJKLMNOPQRSTUVWXYZ`.

bytes.isspace()
bytearray.isspace()

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

bytes.istitle()
bytearray.istitle()

  Повертає `True`, якщо послідовність має регістр заголовків ASCII і послідовність не є порожньою, `False` інакше. Дивіться `bytes.title()`, щоб дізнатися більше про визначення «заголовка».

  Наприклад:

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

bytes.isupper()
bytearray.isupper()

  Повертає `True`, якщо в послідовності є принаймні один символ ASCII у верхньому регістрі та відсутні символи ASCII у нижньому регістрі, інакше `False`.

  Наприклад:

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

  Символи ASCII у нижньому регістрі – це значення байтів у послідовності `b'abcdefghijklmnopqrstuvwxyz`. Символи ASCII у верхньому регістрі – це значення байтів у послідовності `b'ABCDEFGHIJKLMNOPQRSTUVWXYZ`.

bytes.lower()
bytearray.lower()

  Повертає копію послідовності з усіма символами ASCII у верхньому регістрі, перетвореними на їхні відповідні відповідники у нижньому регістрі.

  Наприклад:

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

  Символи ASCII у нижньому регістрі – це значення байтів у послідовності `b'abcdefghijklmnopqrstuvwxyz`. Символи ASCII у верхньому регістрі – це значення байтів у послідовності `b'ABCDEFGHIJKLMNOPQRSTUVWXYZ`.

  Примітка

  Версія bytearray цього методу не працює на місці – вона завжди створює новий об’єкт, навіть якщо не було зроблено жодних змін.

bytes.splitlines(keepends=False)
bytearray.splitlines(keepends=False)

  Повертає список рядків у двійковій послідовності, розриваючи межі рядків ASCII. Цей метод використовує підхід universal newlines до розділення рядків. Розриви рядків не включаються до результуючого списку, якщо не задано keepends і воно є істинним.

  Наприклад:

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

  На відміну від `split()`, коли задано рядок розділювача sep, цей метод повертає порожній список для порожнього рядка, а розрив кінцевого рядка не призводить до додаткового рядка:

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

bytes.swapcase()
bytearray.swapcase()

  Повертає копію послідовності з усіма символами нижнього регістру ASCII, перетвореними на їхні відповідні відповідники у верхньому регістрі та навпаки.

  Наприклад:

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

  Символи ASCII у нижньому регістрі – це значення байтів у послідовності `b'abcdefghijklmnopqrstuvwxyz`. Символи ASCII у верхньому регістрі – це значення байтів у послідовності `b'ABCDEFGHIJKLMNOPQRSTUVWXYZ`.

  Unlike `str.swapcase()`, it is always the case that `bin.swapcase().swapcase() == bin` for the binary versions. Case conversions are symmetrical in ASCII, even though that is not generally true for arbitrary Unicode code points.

  Примітка

  Версія bytearray цього методу не працює на місці – вона завжди створює новий об’єкт, навіть якщо не було зроблено жодних змін.

bytes.title()
bytearray.title()

  Повертає версію двійкової послідовності в заголовку, де слова починаються з символу ASCII у верхньому регістрі, а решта символів – у нижньому регістрі. Значення байтів без регістру залишаються незмінними.

  Наприклад:

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

  Символи ASCII у нижньому регістрі – це значення байтів у послідовності `b'abcdefghijklmnopqrstuvwxyz`. Символи ASCII у верхньому регістрі – це значення байтів у послідовності `b'ABCDEFGHIJKLMNOPQRSTUVWXYZ`. Усі інші значення байтів без регістру.

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

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

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

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

  Примітка

  Версія bytearray цього методу не працює на місці – вона завжди створює новий об’єкт, навіть якщо не було зроблено жодних змін.

bytes.upper()
bytearray.upper()

  Повертає копію послідовності з усіма символами нижнього регістру ASCII, перетвореними на їхні відповідні відповідники у верхньому регістрі.

  Наприклад:

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

  Символи ASCII у нижньому регістрі – це значення байтів у послідовності `b'abcdefghijklmnopqrstuvwxyz`. Символи ASCII у верхньому регістрі – це значення байтів у послідовності `b'ABCDEFGHIJKLMNOPQRSTUVWXYZ`.

  Примітка

  Версія bytearray цього методу не працює на місці – вона завжди створює новий об’єкт, навіть якщо не було зроблено жодних змін.

bytes.zfill(width, /)
bytearray.zfill(width, /)

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

  Наприклад:

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

  Примітка

  Версія bytearray цього методу не працює на місці – вона завжди створює новий об’єкт, навіть якщо не було зроблено жодних змін.

### Форматування байтів у стилі `printf`

Примітка

Операції форматування, описані тут, демонструють різноманітні особливості, які призводять до низки поширених помилок (наприклад, неправильне відображення кортежів і словників). Якщо значення, яке друкується, може бути кортежем або словником, оберніть його в кортеж.

Об’єкти Bytes (`bytes`/`bytearray`) мають одну унікальну вбудовану операцію: оператор `%` (за модулем). Це також відоме як оператор форматування або інтерполяції байтів. Враховуючи `формат % значень` (де format є об’єктом байтів), `%` специфікації перетворення у format замінюються нулем або більше елементами значень. Ефект подібний до використання `sprintf()` у мові C.

Якщо для format потрібен один аргумент, values може бути одним некортежним об’єктом. [5] В іншому випадку values має бути кортежем із точною кількістю елементів, указаною об’єктом format bytes, або одним об’єктом відображення (наприклад, словником).

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

1. Символ `'%'`, який позначає початок специфікатора.

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

3. Прапорці перетворення (опціонально), які впливають на результат деяких типів перетворення.

4. Мінімальна ширина поля (опціонально). Якщо вказано як `'*'` (зірочка), фактична ширина зчитується з наступного елемента кортежу в значеннях, а об’єкт для перетворення йде після мінімальної ширини поля та необов’язкової точності.

5. Точність (необов’язкова), подається як `'.'` (крапка), за якою йде точність. Якщо вказано як `'*'` (зірочка), фактична точність зчитується з наступного елемента кортежу в значеннях, а значення для перетворення йде після точності.

6. Модифікатор довжини (необов’язково).

7. Тип перетворення.

Коли правильний аргумент є словником (або іншим типом відображення), тоді формати в об’єкті bytes мають містити ключ відображення в дужках у цьому словнику, вставлений відразу після символу `'%'`. Ключ відображення вибирає значення, яке потрібно відформатувати, із відображення. Наприклад:

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

У цьому випадку у форматі не може бути специфікаторів `*` (оскільки вони вимагають послідовного списку параметрів).

Символи прапора перетворення:

Прапор | Значення
--- | ---
`'#''` | Перетворення значень використовуватиме «альтернативну форму» (де визначено нижче).
`'0'` | Перетворення буде доповнено нулем для числових значень.
`'-'` | Перетворене значення коригується зліва (перевизначає перетворення `'0'`, якщо подано обидва значення).
`' '` | (пробіл) Пробіл слід залишити перед додатним числом (або порожнім рядком), утвореним перетворенням зі знаком.
`'+'` | Символ знака (`'+'` або `'-'`) передуватиме перетворенню (перевизначає позначку «пробіл»).

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

Типи перетворення:

Перетворення | Значення | Примітки
--- | --- | ---
`'d''` | Ціле десяткове число зі знаком. |
`'я''` | Ціле десяткове число зі знаком. |
`'o'` | Вісімкове значення зі знаком. | (1)
`'u''` | Застарілий тип – він ідентичний `'d'`. | (8)
`'x''` | Шістнадцяткове число зі знаком (нижній регістр). | (2)
`'X''` | Шістнадцяткове число зі знаком (верхній регістр). | (2)
`'e''` | Floating-point exponential format (lowercase). | (3)
`'E'` | Floating-point exponential format (uppercase). | (3)
`'f''` | Floating-point decimal format. | (3)
`'F''` | Floating-point decimal format. | (3)
`'g''` | Floating-point format. Uses lowercase exponential format if exponent is less than -4 or not less than precision, decimal format otherwise. | (4)
`'G''` | Floating-point format. Uses uppercase exponential format if exponent is less than -4 or not less than precision, decimal format otherwise. | (4)
`'c''` | Однобайтовий (приймає цілі чи однобайтові об’єкти). |
`'b''` | Bytes (any object that follows the buffer protocol or has `__bytes__()`). | (5)
`'s''` | `'s''` є псевдонімом для `'b''` і має використовуватися лише для базового коду Python2/3. | (6)
`'a'` | Байти (перетворює будь-який об’єкт Python за допомогою `repr(obj).encode('ascii', 'backslashreplace')`). | (5)
`'r''` | `'r'` є псевдонімом для `'a'` і має використовуватися лише для базових кодів Python2/3. | (7)
`'%'` | Жоден аргумент не перетворюється, результатом є символ `'%'` в результаті. |

Примітки:

1. Альтернативна форма призводить до того, що початковий вісімковий специфікатор (`'0o'`) буде вставлено перед першою цифрою.

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

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

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

4. Альтернативна форма призводить до того, що результат завжди містить десяткову кому, а кінцеві нулі не видаляються, як це було б інакше.

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

5. Якщо точність `N`, вивід скорочується до `N` символів.

6. `b'%s` є застарілим, але не буде видалено протягом серії 3.x.

7. `b'%r''` є застарілим, але не буде видалено протягом серії 3.x.

8. Дивіться PEP 237.

Примітка

Версія bytearray цього методу не працює на місці – вона завжди створює новий об’єкт, навіть якщо не було зроблено жодних змін.

Дивись також

PEP 461 - Додано форматування % до байтів і масиву байтів

Added in version 3.5.

### Перегляди пам’яті

Об’єкти `memoryview` дозволяють коду Python отримувати доступ до внутрішніх даних об’єкта, який підтримує протокол буфера без копіювання.

class memoryview(object)

  > Створіть `memoryview`, який посилається на об’єкт. об’єкт має підтримувати протокол буфера. Вбудовані об’єкти, які підтримують протокол буфера, включають `bytes` і `bytearray`.

  > `memoryview` має поняття елемента, який є атомарною одиницею пам’яті, яка обробляється вихідним об’єктом. Для багатьох простих типів, таких як `bytes` і `bytearray`, елемент є одним байтом, але інші типи, такі як `array.array`, можуть мати більші елементи.

  > `len(view)` is equal to the length of `tolist`, which is the nested list representation of the view. If `view.ndim = 1`, this is equal to the number of elements in the view.

  > Змінено в версії 3.12: If `view.ndim == 0`, `len(view)` now raises `TypeError` instead of returning 1.

  > The `itemsize` attribute will give you the number of bytes in a single element.

  > `memoryview` підтримує нарізку та індексування для показу своїх даних. Одновимірне нарізання призведе до підвиду:

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

  > Якщо `format` є одним із власних специфікаторів формату з модуля `struct`, індексація за допомогою цілого числа або кортежу цілих чисел також підтримується та повертає один елемент із правильним типом . Одновимірні представлення пам’яті можна індексувати за допомогою цілого або одноцілого кортежу. Багатовимірні представлення пам’яті можна індексувати за допомогою кортежів з точно ndim цілих чисел, де ndim є кількістю вимірів. Нульвимірні представлення пам’яті можна індексувати за допомогою порожнього кортежу.

  > Ось приклад небайтового формату:

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

  > Якщо основний об’єкт доступний для запису, 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')

  > One-dimensional memoryviews of hashable (read-only) types with formats „B“, „b“ or „c“ are also hashable. The hash is defined as `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: One-dimensional memoryviews can now be sliced. One-dimensional memoryviews with formats „B“, „b“ or „c“ are now hashable.

  > Змінено в версії 3.4: memoryview тепер автоматично реєструється в `collections.abc.Sequence`

  > Змінено в версії 3.5: memoryviews тепер можна індексувати кортежем цілих чисел.

  > Змінено в версії 3.14: memoryview is now a generic type.

  > `memoryview` має кілька методів:

  > __eq__(exporter)

  >   Memoriview і експортер 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

  >   Note that, as with floating-point numbers, `v is w` does not imply `v == w` for memoryview objects.

  >   Змінено в версії 3.3: Попередні версії порівнювали необроблену пам’ять без урахування формату елемента та логічної структури масиву.

  > tobytes(order='C')

  >   Повертає дані в буфері як байтовий рядок. Це еквівалентно виклику конструктора `bytes` у memoryview.

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

  >   Для несуміжних масивів результат дорівнює представленню зведеного списку з усіма елементами, перетвореними на байти. `tobytes()` підтримує всі рядки формату, включно з тими, яких немає в синтаксисі модуля `struct`.

  >   Added in version 3.8: порядок може бути {„C“, „F“, „A“}. Якщо порядок має значення «C» або «F», дані вихідного масиву перетворюються на порядок C або Fortran. Для суміжних переглядів «A» повертає точну копію фізичної пам’яті. Зокрема, зберігається порядок Fortran у пам’яті. Для несуміжних переглядів дані спочатку перетворюються на C. order=None те саме, що order=“C“.

  > hex(*, bytes_per_sep=1)
  > hex(sep, bytes_per_sep=1)

  >   Повертає рядковий об’єкт, що містить дві шістнадцяткові цифри для кожного байта в буфері.

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

  >   Added in version 3.5.

  >   Змінено в версії 3.8: Подібно до `bytes.hex()`, `memoryview.hex()` тепер підтримує додаткові параметри sep і bytes_per_sep для вставки роздільників між байтами в шістнадцятковому виведенні.

  > tolist()

  >   Повертає дані в буфері як список елементів.

  >       >>> memoryview(b'abc').tolist()
  >       [97, 98, 99]
  >       >>> import array
  >       >>> a = array.array('d', [1.1, 2.2, 3.3])
  >       >>> m = memoryview(a)
  >       >>> m.tolist()
  >       [1.1, 2.2, 3.3]

  >   Змінено в версії 3.3: `tolist()` тепер підтримує всі односимвольні рідні формати в синтаксисі модуля `struct`, а також багатовимірні представлення.

  > toreadonly()

  >   Повертає версію об’єкта memoryview лише для читання. Оригінальний об’єкт memoryview не змінено.

  >       >>> m = memoryview(bytearray(b'abc'))
  >       >>> mm = m.toreadonly()
  >       >>> mm.tolist()
  >       [97, 98, 99]
  >       >>> mm[0] = 42
  >       Traceback (most recent call last):
  >         File "<stdin>", line 1, in <module>
  >       TypeError: cannot modify read-only memory
  >       >>> m[0] = 43
  >       >>> mm.tolist()
  >       [43, 98, 99]

  >   Added in version 3.8.

  > release()

  >   Вивільніть базовий буфер, відкритий об’єктом memoryview. Багато об’єктів виконують спеціальні дії, коли їх переглядають (наприклад, `bytearray` тимчасово забороняє зміну розміру); отже, виклик release() є зручним, щоб усунути ці обмеження (і звільнити будь-які завислі ресурси) якомога швидше.

  >   After this method has been called, any further operation on the view raises a `ValueError` (except `release()` itself which can be called multiple times):

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

  >   Added in version 3.2.

  > cast(format, /)
  > cast(format, shape, /)

  >   Транслюйте пам’ять у новий формат або форму. shape за умовчанням має значення `[byte_length//new_itemsize]`, що означає, що перегляд результату буде одновимірним. Поверненим значенням є новий перегляд пам’яті, але сам буфер не копіюється. Підтримувані приведення: 1D -> C-contiguous і C-contiguous -> 1D.

  >   The destination format is restricted to a single element native format in `struct` syntax. One of the formats must be a byte format („B“, „b“ or „c“). The byte length of the result must be the same as the original length. Note that all byte lengths may depend on the operating system.

  >   Перетворення 1D/long на 1D/беззнакові байти:

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

  >   Перетворення 1D/беззнакових байтів у 1D/char:

  >       >>> b = bytearray(b'zyz')
  >       >>> x = memoryview(b)
  >       >>> x[0] = b'a'
  >       Traceback (most recent call last):
  >         ...
  >       TypeError: memoryview: invalid type for format 'B'
  >       >>> y = x.cast('c')
  >       >>> y[0] = b'a'
  >       >>> b
  >       bytearray(b'ayz')

  >   Перетворити 1D/байти на 3D/ints на 1D/signed char:

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

  >   Перетворення 1D/unsigned long на 2D/unsigned long

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

  >   Added in version 3.3.

  >   Змінено в версії 3.5: Вихідний формат більше не обмежений під час трансляції до байтового перегляду.

  > count(value, /)

  >   Count the number of occurrences of value.

  >   Added in version 3.14.

  index(value, start=0, stop=sys.maxsize, /)

    > Return the index of the first occurrence of value (at or after index start and before index stop).

    > Raises a `ValueError` if value cannot be found.

    > Added in version 3.14.

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

    obj

      Основний об’єкт memoryview:

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

      Added in version 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

      Added in version 3.3.

    readonly

      Bool, що вказує, чи є пам’ять лише для читання.

    format

      Рядок, що містить формат (у стилі модуля `struct`) для кожного елемента в поданні. Огляд пам’яті можна створити з експортерів із довільними рядками формату, але деякі методи (наприклад, `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-contiguous.

      Added in version 3.3.

    f_contiguous

      Логічне значення, що вказує, чи є пам’ять Fortran contiguous.

      Added in version 3.3.

    contiguous

      Bool, що вказує, чи є пам’ять contiguous.

      Added in version 3.3.

## Типи наборів — `set`, `frozenset`

Об’єкт set — це невпорядкована колекція окремих об’єктів hashable. Загальне використання включає тестування членства, видалення дублікатів із послідовності та обчислення математичних операцій, таких як перетин, об’єднання, різниця та симетрична різниця. (Для інших контейнерів перегляньте вбудовані класи `dict`, `list` і `tuple`, а також модуль `collections`.)

Як і інші колекції, набори підтримують `x in set`, `len(set)` і `for x in set`. Будучи невпорядкованою колекцією, набори не записують положення елемента або порядок вставки. Відповідно, набори не підтримують індексування, нарізку чи іншу поведінку, подібну до послідовності.

Наразі існує два вбудовані типи наборів: `set` і `frozenset`. Тип `set` є змінним — вміст можна змінити за допомогою таких методів, як `add()` і `remove()`. Оскільки він є змінним, він не має хеш-значення і не може використовуватися ні як ключ словника, ні як елемент іншого набору. Тип `frozenset` є незмінним і hashable — його вміст не можна змінити після створення; тому його можна використовувати як ключ до словника або як елемент іншого набору.

Непорожні набори (не заморожені набори) можна створити шляхом розміщення списку елементів, розділених комами, у фігурних дужках, наприклад: `{'jack', 'sjoerd'}`, на додаток до `set` конструктор.

Конструктори для обох класів працюють однаково:

class set(iterable=(), /)
class frozenset(iterable=(), /)

  Повертає новий набір або заморожений об’єкт, елементи якого взяті з iterable. Елементи набору мають бути hashable. Щоб представити набори наборів, внутрішні набори мають бути об’єктами `frozenset`. Якщо iterable не вказано, повертається новий порожній набір.

  Набори можна створювати кількома способами:

  - Використовуйте список елементів, розділених комами, у фігурних дужках: `{'jack', 'sjoerd'}`

  - Використовуйте розуміння набору: `{c для c в 'abracadabra' якщо c не в 'abc'}`

  - Використовуйте конструктор типу: `set()`, `set('foobar')`, `set(['a', 'b', 'foo'])`

  Екземпляри `set` і `frozenset` забезпечують такі операції:

  len(s)

    Повертає кількість елементів у наборі s (мощність s).

  x in s

    Перевірте x на членство в s.

  x not in s

    Перевірте x на неналежність до s.

  isdisjoint(other, /)

    Повертає `True`, якщо набір не має спільних елементів з other. Множини непересічні тоді і тільки тоді, коли їх перетин є порожньою множиною.

  issubset(other, /)
  set <= other

    Перевірте, чи кожен елемент у наборі знаходиться в other.

  set < other

    Перевірте, чи набір є правильною підмножиною other, тобто `set <= other і set != other`.

  issuperset(other, /)
  set >= other

    Перевірте, чи всі елементи в other є в наборі.

  set > other

    Перевірте, чи є набір правильною надмножиною other, тобто `set >= other і set != other`.

  union(*others)
  set | other | ...

    Повернути новий набір з елементами з набору та всі інші.

  intersection(*others)
  set & other & ...

    Повертає новий набір із елементами, спільними для набору та всіх інших.

  difference(*others)
  set - other - ...

    Повертає новий набір з елементами в наборі, яких немає в інших.

  symmetric_difference(other, /)
  set ^ other

    Повертає новий набір з елементами або в наборі, або в іншому, але не в обох.

  copy()

    Поверніть мілку копію набору.

  Зауважте, версії без операторів `union()`, `intersection()`, `difference()`, `symmetric_difference()`, `issubset()` і `issuperset()` методи приймуть будь-яку ітерацію як аргумент. На відміну від цього, їхні аналоги на основі операторів вимагають, щоб їхні аргументи були наборами. Це виключає такі схильні до помилок конструкції, як `set('abc') & 'cbs'` на користь більш читабельного `set('abc').intersection('cbs')`.

  І `set`, і `frozenset` підтримують набір для встановлення порівнянь. Дві множини рівні тоді і тільки тоді, коли кожен елемент кожної множини міститься в іншій (кожен є підмножиною іншого). Набір менший за інший набір тоді і тільки тоді, коли перший набір є належним підмножиною другого набору (є підмножиною, але не дорівнює). Набір більший за інший набір тоді і тільки тоді, коли перший набір є належним надмножиною другого набору (є надмножиною, але не є рівним).

  Примірники `set` порівнюються з примірниками `frozenset` на основі їхніх членів. Наприклад, `set('abc') == frozenset('abc')` повертає `True`, а також `set('abc')` у `set([frozenset('abc')])`.

  Порівняння підмножини та рівності не узагальнюють до загальної функції впорядкування. Наприклад, будь-які дві непорожні непересічні множини не рівні і не є підмножинами одна одної, тому всі з наступного повертають `False`: `a <b`, `a==b`, or `a> b`.

  Оскільки набори визначають лише часткове впорядкування (відносини підмножин), вихід методу `list.sort()` не визначений для списків наборів.

  Елементи набору, як і ключі словника, мають бути hashable.

  Бінарні операції, які поєднують екземпляри `set` із `frozenset`, повертають тип першого операнда. Наприклад: `frozenset('ab') | set('bc')` повертає екземпляр `frozenset`.

  У наступній таблиці наведено операції, доступні для `set`, які не застосовуються до незмінних екземплярів `frozenset`:

  update(*others)
  set |= other | ...

    Оновіть набір, додавши елементи з усіх інших.

  intersection_update(*others)
  set &= other & ...

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

  difference_update(*others)
  set -= other | ...

    Оновіть набір, видаляючи елементи, знайдені в інших.

  symmetric_difference_update(other, /)
  set ^= other

    Оновіть набір, зберігаючи лише елементи, знайдені в будь-якому наборі, але не в обох.

  add(elem, /)

    Додайте елемент elem до набору.

  remove(elem, /)

    Видалити елемент elem із набору. Викликає `KeyError`, якщо elem не міститься в наборі.

  discard(elem, /)

    Видалити елемент elem із набору, якщо він присутній.

  pop()

    Вилучити та повернути довільний елемент із набору. Викликає `KeyError`, якщо набір порожній.

  clear()

    Видаліть усі елементи з набору.

  Зауважте, що безоператорні версії методів `update()`, `intersection_update()`, `difference_update()` і `symmetric_difference_update()` прийматимуть будь-яку ітерацію як аргумент.

  Note, the elem argument to the `__contains__()`, `remove()`, and `discard()` methods may be a set. To support searching for an equivalent frozenset, a temporary one is created from elem.

## Типи зіставлення — `dict`

Об’єкт mapping відображає значення hashable на довільні об’єкти. Відображення є змінними об’єктами. Зараз існує лише один стандартний тип відображення, dictionary. (Для інших контейнерів перегляньте вбудовані класи `list`, `set` і `tuple`, а також модуль `collections`.)

A dictionary’s keys are almost arbitrary values. Values that are not hashable, that is, values containing lists, dictionaries or other mutable types (that are compared by value rather than by object identity) may not be used as keys. Values that compare equal (such as `1`, `1.0`, and `True`) can be used interchangeably to index the same dictionary entry.

class dict(**kwargs)
class dict(mapping, /, **kwargs)
class dict(iterable, /, **kwargs)

  Повертає новий словник, ініціалізований необов’язковим позиційним аргументом і, можливо, порожнім набором ключових аргументів.

  Словники можна створювати кількома способами:

  - Використовуйте розділений комами список пар `ключ: значення` у дужках: `{'jack': 4098, 'sjoerd': 4127}` або `{4098: 'jack', 4127: 'sjoerd' }`

  - Використовуйте розуміння диктового слова: `{}`, `{x: x ** 2 для x в діапазоні (10)}`

  - Використовуйте конструктор типу: `dict()`, `dict([('foo', 100), ('bar', 200)])`, `dict(foo=100, bar=200)`

  If no positional argument is given, an empty dictionary is created. If a positional argument is given and it defines a `keys()` method, a dictionary is created by calling `__getitem__()` on the argument with each returned key from the method. Otherwise, the positional argument must be an iterable object. Each item in the iterable must itself be an iterable with exactly two elements. The first element of each item becomes a key in the new dictionary, and the second element the corresponding value. If a key occurs more than once, the last value for that key becomes the corresponding value in the new dictionary.

  Якщо надано аргументи ключового слова, аргументи ключового слова та їхні значення додаються до словника, створеного з позиційного аргументу. Якщо ключ, який додається, уже присутній, значення з аргументу ключового слова замінює значення з позиційного аргументу.

  Надання аргументів ключових слів, як у першому прикладі, працює лише для ключів, які є дійсними ідентифікаторами Python. В іншому випадку можна використовувати будь-які дійсні ключі.

  Dictionaries compare equal if and only if they have the same `(key, value)` pairs (regardless of ordering). Order comparisons („<“, „<=“, „>=“, „>“) raise `TypeError`. To illustrate dictionary creation and equality, the following examples all return a dictionary equal to `{"one": 1, "two": 2, "three": 3}`:

      >>> a = dict(one=1, two=2, three=3)
      >>> b = {'one': 1, 'two': 2, 'three': 3}
      >>> c = dict(zip(['one', 'two', 'three'], [1, 2, 3]))
      >>> d = dict([('two', 2), ('one', 1), ('three', 3)])
      >>> e = dict({'three': 3, 'one': 1, 'two': 2})
      >>> f = dict({'one': 1, 'three': 3}, two=2)
      >>> a == b == c == d == e == f
      True

  Надання аргументів ключових слів, як у першому прикладі, працює лише для ключів, які є дійсними ідентифікаторами Python. В іншому випадку можна використовувати будь-які дійсні ключі.

  Словники зберігають порядок вставки. Зауважте, що оновлення ключа не впливає на порядок. Ключі, додані після видалення, вставляються в кінці.

      >>> d = {"one": 1, "two": 2, "three": 3, "four": 4}
      >>> d
      {'one': 1, 'two': 2, 'three': 3, 'four': 4}
      >>> list(d)
      ['one', 'two', 'three', 'four']
      >>> list(d.values())
      [1, 2, 3, 4]
      >>> d["one"] = 42
      >>> d
      {'one': 42, 'two': 2, 'three': 3, 'four': 4}
      >>> del d["two"]
      >>> d["two"] = None
      >>> d
      {'one': 42, 'three': 3, 'four': 4, 'two': None}

  Змінено в версії 3.7: Порядок словника гарантовано буде порядком вставки. Така поведінка була деталлю реалізації CPython від 3.6.

  Це операції, які підтримують словники (і, отже, також повинні підтримуватися спеціальні типи зіставлення):

  list(d)

    Повернути список усіх ключів, які використовуються у словнику d.

  len(d)

    Повернути кількість елементів у словнику d.

  d[key]

    Поверніть елемент d за допомогою ключа key. Викликає `KeyError`, якщо key немає на карті.

    Якщо підклас dict визначає метод `__missing__()` і key відсутній, операція `d[key]` викликає цей метод із ключем key як аргументом. Потім операція `d[key]` повертає або викликає все, що повертається або викликається викликом `__missing__(key)`. Жодні інші операції чи методи не викликають `__missing__()`. Якщо `__missing__()` не визначено, виникає `KeyError`. `__missing__()` має бути методом; це не може бути змінна екземпляра:

        >>> class Counter(dict):
        ...     def __missing__(self, key):
        ...         return 0
        ...
        >>> c = Counter()
        >>> c['red']
        0
        >>> c['red'] += 1
        >>> c['red']
        1

    Наведений вище приклад показує частину реалізації `collections.Counter`. Інший метод `__missing__` використовується `collections.defaultdict`.

  d[key] = value

    Установіть для `d[key]` значення value.

  del d[key]

    Видаліть `d[key]` з d. Викликає `KeyError`, якщо key немає на карті.

  key in d

    Повертає `True`, якщо d має ключ key, інакше `False`.

  key not in d

    Еквівалент `не вводити d`.

  iter(d)

    Повертає ітератор над ключами словника. Це ярлик для `iter(d.keys())`.

  clear()

    Видаліть усі елементи зі словника.

  copy()

    Поверніть мілку копію словника.

  classmethod fromkeys(iterable, value=None, /)

    Створіть новий словник із ключами з iterable і значеннями, встановленими на value.

    `fromkeys()` — це метод класу, який повертає новий словник. value за замовчуванням `None`. Усі значення стосуються лише одного екземпляра, тому загалом не має сенсу, щоб value було змінним об’єктом, таким як порожній список. Щоб отримати різні значення, замість цього використовуйте dict comprehension.

  get(key, default=None, /)

    Повертає значення для key, якщо key є в словнику, інакше за замовчуванням. Якщо default не вказано, за замовчуванням буде `None`, тому цей метод ніколи не викликає `KeyError`.

  items()

    Повертає нове подання елементів словника (пари «(ключ, значення)»). Перегляньте документацію об’єктів перегляду.

  keys()

    Повернути новий вигляд ключів словника. Перегляньте документацію об’єктів перегляду.

  pop(key, /)
  pop(key, default, /)

    Якщо key є у словнику, видаліть його та поверніть його значення, інакше поверніть default. Якщо default не вказано, а key немає в словнику, виникає `KeyError`.

  popitem()

    Видалити та повернути пару `(ключ, значення)` зі словника. Пари повертаються в порядку LIFO.

    `popitem()` корисний для деструктивного повторення словника, як це часто використовується в набір алгоритмів. Якщо словник порожній, виклик `popitem()` викликає `KeyError`.

    Змінено в версії 3.7: Замовлення LIFO тепер гарантовано. У попередніх версіях `popitem()` повертав довільну пару ключ/значення.

  reversed(d)

    Повертає зворотний ітератор над ключами словника. Це ярлик для `reversed(d.keys())`.

    Added in version 3.8.

  setdefault(key, default=None, /)

    Якщо key є в словнику, поверніть його значення. Якщо ні, вставте ключ зі значенням default і поверніть default. default за замовчуванням `None`.

  update(**kwargs)
  update(mapping, /, **kwargs)
  update(iterable, /, **kwargs)

    Update the dictionary with the key/value pairs from mapping or iterable and kwargs, overwriting existing keys. Return `None`.

    `update()` accepts either another object with a `keys()` method (in which case `__getitem__()` is called with every key returned from the method) or an iterable of key/value pairs (as tuples or other iterables of length two). If keyword arguments are specified, the dictionary is then updated with those key/value pairs: `d.update(red=1, blue=2)`.

  values()

    Повернути нове подання значень словника. Перегляньте документацію об’єктів перегляду.

    Порівняння рівності між одним переглядом `dict.values()` та іншим завжди повертатиме `False`. Це також стосується порівняння `dict.values()` із собою:

        >>> d = {'a': 1}
        >>> d.values() == d.values()
        False

  d | other

    Створіть новий словник із об’єднаними ключами та значеннями d та other, які мають бути словниками. Значення other мають пріоритет, коли d та other мають спільні ключі.

    Added in version 3.9.

  d |= other

    Оновіть словник d ключами та значеннями з other, які можуть бути mapping або iterable пар ключ/значення. Значення other мають пріоритет, коли d та other мають спільні ключі.

    Added in version 3.9.

  Словники та перегляди словників є оборотними.

      >>> d = {"one": 1, "two": 2, "three": 3, "four": 4}
      >>> d
      {'one': 1, 'two': 2, 'three': 3, 'four': 4}
      >>> list(reversed(d))
      ['four', 'three', 'two', 'one']
      >>> list(reversed(d.values()))
      [4, 3, 2, 1]
      >>> list(reversed(d.items()))
      [('four', 4), ('three', 3), ('two', 2), ('one', 1)]

  Змінено в версії 3.8: Словники тепер оборотні.

Дивись також

`types.MappingProxyType` можна використовувати для створення перегляду `dict` лише для читання.

### Об’єкти перегляду словника

Об’єкти, які повертаються `dict.keys()`, `dict.values()` і `dict.items()`, є об’єктами перегляду. Вони забезпечують динамічний перегляд статей словника, що означає, що коли словник змінюється, перегляд відображає ці зміни.

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

len(dictview)

  Повернути кількість статей у словнику.

iter(dictview)

  Повертає ітератор над ключами, значеннями або елементами (представленими у вигляді кортежів `(ключ, значення)`) у словнику.

  Ключі та значення повторюються в порядку вставки. Це дозволяє створювати пари `(значення, ключ)` за допомогою `zip()`: `pairs = zip(d.values(), d.keys())`. Інший спосіб створити той самий список: `pairs = [(v, k) for (k, v) in d.items()]`.

  Ітерація подання під час додавання чи видалення записів у словнику може викликати `RuntimeError` або не вдається виконати ітерацію по всіх записах.

  Змінено в версії 3.7: Порядок словника гарантовано буде порядком вставки.

x in dictview

  Повертає `True`, якщо x міститься в ключах, значеннях або елементах основного словника (в останньому випадку x має бути кортежем `(ключ, значення)`).

reversed(dictview)

  Повертає зворотний ітератор над ключами, значеннями або елементами словника. Подання буде повторено в порядку, зворотному до вставки.

  Змінено в версії 3.8: Перегляди словника тепер оборотні.

dictview.mapping

  Повертає `types.MappingProxyType`, який обгортає вихідний словник, на який посилається перегляд.

  Added in version 3.10.

Keys views are set-like since their entries are unique and hashable. Items views also have set-like operations since the (key, value) pairs are unique and the keys are hashable. If all values in an items view are hashable as well, then the items view can interoperate with other sets. (Values views are not treated as set-like since the entries are generally not unique.) For set-like views, all of the operations defined for the abstract base class `collections.abc.Set` are available (for example, `==`, `<`, or `^`). While using set operators, set-like views accept any iterable as the other operand, unlike sets which only accept sets as the input.

Приклад використання перегляду словника:

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

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

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

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

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

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

## Типи менеджера контексту

Оператор Python `with` підтримує концепцію контексту виконання, визначеного менеджером контексту. Це реалізовано за допомогою пари методів, які дозволяють визначеним користувачем класам визначати контекст виконання, який вводиться перед виконанням тіла оператора та виходить, коли оператор закінчується:

contextmanager.__enter__()

  Введіть контекст середовища виконання та поверніть або цей об’єкт, або інший об’єкт, пов’язаний із контекстом середовища виконання. Значення, яке повертає цей метод, прив’язується до ідентифікатора в пункті `as` операторів `with` за допомогою цього менеджера контексту.

  Прикладом контекстного менеджера, який повертає сам себе, є file object. Файлові об’єкти повертаються з __enter__(), щоб дозволити використовувати `open()` як вираз контексту в операторі `with`.

  Прикладом менеджера контексту, який повертає пов’язаний об’єкт, є той, який повертає `decimal.localcontext()`. Ці менеджери встановлюють активний десятковий контекст на копію вихідного десяткового контексту, а потім повертають копію. Це дозволяє вносити зміни до поточного десяткового контексту в тілі оператора `with`, не впливаючи на код поза оператором `with`.

contextmanager.__exit__(exc_type, exc_val, exc_tb)

  Вийдіть із контексту виконання та поверніть логічний прапор, який вказує, чи має бути придушено будь-який виняток, який стався. Якщо виняток стався під час виконання тіла оператора `with`, аргументи містять тип винятку, значення та інформацію про відстеження. В іншому випадку всі три аргументи є `Жодним`.

  Повернення цього методу справжнього значення призведе до того, що оператор `with` придушить виняток і продовжить виконання з оператором, який слідує безпосередньо за оператором `with`. В іншому випадку виняткова ситуація продовжує поширюватися після завершення виконання цього методу. Винятки, які виникають під час виконання цього методу, замінять будь-які винятки, які виникли в тілі оператора `with`.

  The exception passed in should never be reraised explicitly - instead, this method should return a false value to indicate that the method completed successfully and does not want to suppress the raised exception. This allows context management code to easily detect whether or not an `__exit__()` method has actually failed.

Python визначає декілька контекстних менеджерів для підтримки легкої синхронізації потоків, швидкого закриття файлів чи інших об’єктів і простішого маніпулювання активним десятковим арифметичним контекстом. Конкретні типи не розглядаються спеціально за межами їх реалізації в протоколі керування контекстом. Перегляньте модуль `contextlib` для деяких прикладів.

generators Python і декоратор `contextlib.contextmanager` забезпечують зручний спосіб реалізації цих протоколів. Якщо функція-генератор прикрашена декоратором `contextlib.contextmanager`, вона повертатиме менеджер контексту, який реалізує необхідні методи `__enter__()` і `__exit__()`, а не ітератор, створений недекорованою функцією генератора.

Зауважте, що немає спеціального слота для жодного з цих методів у структурі типу для об’єктів Python в API Python/C. Типи розширень, які хочуть визначити ці методи, повинні надати їх як звичайний доступний метод Python. Порівняно з накладними витратами на налаштування контексту виконання, накладні витрати на пошук словника одного класу є незначними.

## Типи анотацій типу — Загальний псевдонім, Об’єднання

Основними вбудованими типами для анотацій типу є Generic Alias і Union.

### Загальний тип псевдоніма

Об’єкти `GenericAlias` зазвичай створюються індексом класу. Найчастіше вони використовуються з контейнерними класами, такими як `list` або `dict`. Наприклад, `list[int]` є об’єктом `GenericAlias`, створеним шляхом підписання класу `list` з аргументом `int`. Об’єкти `GenericAlias` призначені насамперед для використання з анотаціями типу.

Примітка

Як правило, індекс класу можливий, лише якщо клас реалізує спеціальний метод `__class_getitem__()`.

Об’єкт `GenericAlias` діє як проксі для generic type, реалізуючи параметризовані генерики.

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

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

- Якщо `x = re.search('foo', 'foo')`, `x` буде об’єктом re.Match, де повертаються значення `x.group(0 )` і `x[0]` будуть мати тип `str`. Ми можемо представити цей тип об’єктів в анотаціях типу за допомогою `GenericAlias` `re.Match[str]`.

- Якщо `y = re.search(b'bar', b'bar')` (зверніть увагу на `b` для `bytes`), `y` також буде екземпляром `re.Match`, але повертані значення `y.group(0)` і `y[0]` будуть мати тип `bytes`. В анотаціях типів ми б представили цю різноманітність об’єктів re.Match за допомогою `re.Match[bytes]`.

Об’єкти `GenericAlias` є екземплярами класу `types.GenericAlias`, який також можна використовувати для безпосереднього створення об’єктів `GenericAlias`.

T[X, Y, ...]

  Створює `Generic Alias`, що представляє тип `T`, параметризований типами X, Y тощо залежно від `T`, що використовується. Наприклад, функція, яка очікує `list`, що містить елементи `float`:

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

  Інший приклад для об’єктів mapping з використанням `dict`, який є загальним типом, який очікує двох параметрів типу, що представляють тип ключа та тип значення. У цьому прикладі функція очікує `dict` з ключами типу `str` і значеннями типу `int`:

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

Вбудовані функції `isinstance()` і `issubclass()` не приймають типи `GenericAlias` для свого другого аргументу:

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

Середовище виконання Python не вимагає анотацій типу. Це поширюється на загальні типи та їхні параметри типу. Під час створення об’єкта-контейнера з `GenericAlias` елементи в контейнері не перевіряються на їх тип. Наприклад, наступний код не рекомендується, але працюватиме без помилок:

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

Крім того, параметризовані генерики стирають параметри типу під час створення об’єкта:

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

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

Виклик `repr()` або `str()` у загальному показує параметризований тип:

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

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

Метод `__getitem__()` загальних контейнерів викличе виняток, щоб заборонити такі помилки, як `dict[str][str]`:

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

Однак такі вирази дійсні, коли використовуються змінні типу. Індекс має містити стільки елементів, скільки елементів змінних типу в об’єкті `GenericAlias` `__args__`.

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

#### Стандартні загальні класи

Наступні стандартні бібліотечні класи підтримують параметризовані генерики. Цей список не є вичерпним.

- `tuple`

- `list`

- `dict`

- `set`

- `frozenset`

- `type`

- `asyncio.Future`

- `asyncio.Task`

- `collections.deque`

- `collections.defaultdict`

- `collections.OrderedDict`

- `collections.Counter`

- `collections.ChainMap`

- `collections.abc.Awaitable`

- `collections.abc.Coroutine`

- `collections.abc.AsyncIterable`

- `collections.abc.AsyncIterator`

- `collections.abc.AsyncGenerator`

- `collections.abc.Iterable`

- `collections.abc.Iterator`

- `collections.abc.Generator`

- `collections.abc.Reversible`

- `collections.abc.Container`

- `collections.abc.Collection`

- `collections.abc.Callable`

- `collections.abc.Set`

- `collections.abc.MutableSet`

- `collections.abc.Mapping`

- `collections.abc.MutableMapping`

- `collections.abc.Sequence`

- `collections.abc.MutableSequence`

- `collections.abc.MappingView`

- `collections.abc.KeysView`

- `collections.abc.ItemsView`

- `collections.abc.ValuesView`

- `contextlib.AbstractContextManager`

- `contextlib.AbstractAsyncContextManager`

- `dataclasses.Field`

- `functools.cached_property`

- `functools.partialmethod`

- `os.PathLike`

- `queue.LifoQueue`

- `queue.Queue`

- `queue.PriorityQueue`

- `queue.SimpleQueue`

- re.Патерн

- re.Match

- `полиця.BsdDbShelf`

- `полиця.DbfilenameShelf`

- `полиця.Полиця`

- `types.MappingProxyType`

- `weakref.WeakKeyDictionary`

- `weakref.WeakMethod`

- `weakref.WeakSet`

- `weakref.WeakValueDictionary`

#### Спеціальні атрибути об’єктів `GenericAlias`

Усі параметризовані генерики реалізують спеціальні атрибути лише для читання.

genericalias.__origin__

  Цей атрибут вказує на непараметризований загальний клас:

      >>> list[int].__origin__
      <class 'list'>

genericalias.__args__

  Цей атрибут є `tuple` (можливо, довжиною 1) загальних типів, переданих до оригінального `__class_getitem__()` загального класу:

      >>> dict[str, list[int]].__args__
      (<class 'str'>, list[int])

genericalias.__parameters__

  Цей атрибут є ліниво обчисленим кортежем (можливо, порожнім) унікальних змінних типу, знайдених у `__args__`:

      >>> from typing import TypeVar

      >>> T = TypeVar('T')
      >>> list[T].__parameters__
      (~T,)

  Примітка

  Об’єкт `GenericAlias` з параметрами `typing.ParamSpec` може не мати правильних `__parameters__` після заміни, тому що `typing.ParamSpec` призначений насамперед для статичної перевірки типу.

genericalias.__unpacked__

  A boolean that is true if the alias has been unpacked using the `*` operator (see `TypeVarTuple`).

  Added in version 3.11.

Дивись також

PEP 484 - підказки типу

  Представляємо структуру Python для анотацій типів.

PEP 585 - Універсальні підказки типів у стандартних колекціях

  Представляємо можливість нативної параметризації класів стандартної бібліотеки, якщо вони реалізують спеціальний метод класу `__class_getitem__()`.

Узагальнення, визначені користувачем узагальнення і `typing.Generic`

  Документація про те, як реалізувати загальні класи, які можна параметризувати під час виконання та розуміти статичними засобами перевірки типів.

Added in version 3.9.

### Тип союзу

A union object holds the value of the `|` (bitwise or) operation on multiple type objects. These types are intended primarily for type annotations. The union type expression enables cleaner type hinting syntax compared to subscripting `typing.Union`.

X | Y | ...

  Визначає об’єкт об’єднання, який містить типи X, Y і так далі. `X | Y` означає X або Y. Це еквівалентно `typing.Union[X, Y]`. Наприклад, наступна функція очікує аргумент типу `int` або `float`:

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

  Примітка

  The `|` operand cannot be used at runtime to define unions where one or more members is a forward reference. For example, `int | "Foo"`, where `"Foo"` is a reference to a class not yet defined, will fail at runtime. For unions which include forward references, present the whole expression as a string, e.g. `"int | Foo"`.

union_object == other

  Об’єкти об’єднання можна перевірити на рівність з іншими об’єктами об’єднання. Подробиці:

  - Союзи союзів сплощені:

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

  - Зайві типи видаляються:

        int | str | int == int | str

  - Під час порівняння об’єднань порядок ігнорується:

        int | str == str | int

  - It creates instances of `typing.Union`:

        int | str == typing.Union[int, str]
        type(int | str) is typing.Union

  - Необов’язкові типи можуть бути написані як об’єднання з `None`:

        str | None == typing.Optional[str]

isinstance(obj, union_object)

issubclass(obj, union_object)

  Виклики `isinstance()` і `issubclass()` також підтримуються з об’єктом об’єднання:

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

  However, parameterized generics in union objects cannot be checked:

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

The user-exposed type for the union object can be accessed from `typing.Union` and used for `isinstance()` checks:

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

Примітка

The `__or__()` method for type objects was added to support the syntax `X | Y`. If a metaclass implements `__or__()`, the Union may override it:

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

Дивись також

PEP 604 – PEP пропонує `X | Синтаксис Y` і тип Union.

Added in version 3.10.

Змінено в версії 3.14: Union objects are now instances of `typing.Union`. Previously, they were instances of `types.UnionType`, which remains an alias for `typing.Union`.

## Інші вбудовані типи

Інтерпретатор підтримує кілька інших видів об’єктів. Більшість із них підтримує лише одну або дві операції.

### Модулі

Єдиною спеціальною операцією над модулем є доступ до атрибутів: `m.name`, де m — це модуль, а name отримує доступ до імені, визначеного в таблиці символів m. Модулю можна призначити атрибути. (Зауважте, що оператор `import` не є, строго кажучи, операцією над об’єктом модуля; `import foo` не вимагає існування об’єкта модуля з назвою foo, скоріше для цього потрібен (зовнішній) визначення для модуля з назвою foo десь.)

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

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

### Класи та екземпляри класів

Перегляньте Об’єкти, значення та типи і Визначення класів для них.

### Функції

Функціональні об’єкти створюються визначеннями функцій. Єдина операція над об’єктом-функцією – це викликати його: `func(список-аргументів)`.

Насправді існує два види функціональних об’єктів: вбудовані функції та функції, визначені користувачем. Обидва підтримують однакову операцію (виклик функції), але реалізація різна, отже, різні типи об’єктів.

Перегляньте Визначення функцій для отримання додаткової інформації.

### методи

Methods are functions that are called using the attribute notation. There are two flavors: built-in methods (such as `append()` on lists) and class instance method. Built-in methods are described with the types that support them.

If you access a method (a function defined in a class namespace) through an instance, you get a special object: a bound method (also called instance method) object. When called, it will add the `self` argument to the argument list. Bound methods have two special read-only attributes: `m.__self__` is the object on which the method operates, and `m.__func__` is the function implementing the method. Calling `m(arg-1, arg-2, ..., arg-n)` is completely equivalent to calling `m.__func__(m.__self__, arg-1, arg-2, ..., arg-n)`.

Like function objects, bound method objects support getting arbitrary attributes. However, since method attributes are actually stored on the underlying function object (`method.__func__`), setting method attributes on bound methods is disallowed. Attempting to set an attribute on a method results in an `AttributeError` being raised. In order to set a method attribute, you need to explicitly set it on the underlying function object:

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

See Методи екземплярів for more information.

### Об’єкти коду

Code objects are used by the implementation to represent «pseudo-compiled» executable Python code such as a function body. They differ from function objects because they don’t contain a reference to their global execution environment. Code objects are returned by the built-in `compile()` function and can be extracted from function objects through their `__code__` attribute. See also the `code` module.

Accessing `__code__` raises an auditing event `object.__getattr__` with arguments `obj` and `"__code__"`.

Об’єкт коду можна виконати або оцінити, передавши його (замість вихідного рядка) у вбудовані функції `exec()` або `eval()`.

Перегляньте Стандартна ієрархія типів для отримання додаткової інформації.

### Об’єкти типу

Об’єкти типу представляють різні типи об’єктів. Доступ до типу об’єкта здійснюється за допомогою вбудованої функції `type()`. Над типами немає спеціальних операцій. Стандартний модуль `types` визначає імена для всіх стандартних вбудованих типів.

Типи записуються так: `<class 'int'>`.

### Нульовий об’єкт

Цей об’єкт повертають функції, які явно не повертають значення. Він не підтримує ніяких спеціальних операцій. Існує рівно один нульовий об’єкт із назвою `None` (вбудована назва). `type(None)()` створює той самий синглтон.

Він записується як `None`.

### Об’єкт «Еліпсис».

This object is commonly used used to indicate that something is omitted. It supports no special operations. There is exactly one ellipsis object, named `Ellipsis` (a built-in name). `type(Ellipsis)()` produces the `Ellipsis` singleton.

Він записується як `Еліпсис` або `...`.

In typical use, `...` as the `Ellipsis` object appears in a few different places, for instance:

- In type annotations, such as callable arguments or tuple elements.

- As the body of a function instead of a pass statement.

- In third-party libraries, such as Numpy’s slicing and striding.

Python also uses three dots in ways that are not `Ellipsis` objects, for instance:

- Doctest’s `ELLIPSIS`, as a pattern for missing content.

- The default Python prompt of the interactive shell when partial input is incomplete.

Lastly, the Python documentation often uses three dots in conventional English usage to mean omitted content, even in code examples that also use them as the `Ellipsis`.

### Об’єкт NotImplemented

This object is returned from comparisons and binary operations when they are asked to operate on types they don’t support. See Порівняння for more information. There is exactly one `NotImplemented` object. `type(NotImplemented)()` produces the singleton instance.

It is written as `NotImplemented`.

### Внутрішні об’єкти

See Стандартна ієрархія типів for this information. It describes stack frame objects, traceback objects, and slice objects.

## Спеціальні атрибути

Реалізація додає кілька спеціальних атрибутів лише для читання до кількох типів об’єктів, де вони актуальні. Деякі з них не повідомляються вбудованою функцією `dir()`.

definition.__name__

  Ім’я класу, функції, методу, дескриптора або екземпляра генератора.

definition.__qualname__

  qualified name класу, функції, методу, дескриптора або екземпляра генератора.

  Added in version 3.3.

definition.__module__

  The name of the module in which a class or function was defined.

definition.__doc__

  The documentation string of a class or function, or `None` if undefined.

definition.__type_params__

  The type parameters of generic classes, functions, and type aliases. For classes and functions that are not generic, this will be an empty tuple.

  Added in version 3.12.

## Integer string conversion length limitation

CPython has a global limit for converting between `int` and `str` to mitigate denial of service attacks. This limit only applies to decimal or other non-power-of-two number bases. Hexadecimal, octal, and binary conversions are unlimited. The limit can be configured.

The `int` type in CPython is an arbitrary length number stored in binary form (commonly known as a «bignum»). There exists no algorithm that can convert a string to a binary integer or a binary integer to a string in linear time, unless the base is a power of 2. Even the best known algorithms for base 10 have sub-quadratic complexity. Converting a large value such as `int('1' * 500_000)` can take over a second on a fast CPU.

Limiting conversion size offers a practical way to avoid CVE 2020-10735.

The limit is applied to the number of digit characters in the input or output string when a non-linear conversion algorithm would be involved. Underscores and the sign are not counted towards the limit.

When an operation would exceed the limit, a `ValueError` is raised:

    >>> import sys
    >>> sys.set_int_max_str_digits(4300)  # Illustrative, this is the default.
    >>> _ = int('2' * 5432)
    Traceback (most recent call last):
    ...
    ValueError: Exceeds the limit (4300 digits) for integer string conversion: value has 5432 digits; use sys.set_int_max_str_digits() to increase the limit
    >>> i = int('2' * 4300)
    >>> len(str(i))
    4300
    >>> i_squared = i*i
    >>> len(str(i_squared))
    Traceback (most recent call last):
    ...
    ValueError: Exceeds the limit (4300 digits) for integer string conversion; use sys.set_int_max_str_digits() to increase the limit
    >>> len(hex(i_squared))
    7144
    >>> assert int(hex(i_squared), base=16) == i*i  # Hexadecimal is unlimited.

The default limit is 4300 digits as provided in `sys.int_info.default_max_str_digits`. The lowest limit that can be configured is 640 digits as provided in `sys.int_info.str_digits_check_threshold`.

Verification:

    >>> import sys
    >>> assert sys.int_info.default_max_str_digits == 4300, sys.int_info
    >>> assert sys.int_info.str_digits_check_threshold == 640, sys.int_info
    >>> msg = int('578966293710682886880994035146873798396722250538762761564'
    ...           '9252925514383915483333812743580549779436104706260696366600'
    ...           '571186405732').to_bytes(53, 'big')
    ...

Added in version 3.11.

### Affected APIs

The limitation only applies to potentially slow conversions between `int` and `str` or `bytes`:

- `int(string)` with default base 10.

- `int(string, base)` for all bases that are not a power of 2.

- `str(integer)`.

- `repr(integer)`.

- any other string conversion to base 10, for example `f"{integer}"`, `"{}".format(integer)`, or `b"%d" % integer`.

The limitations do not apply to functions with a linear algorithm:

- `int(string, base)` with base 2, 4, 8, 16, or 32.

- `int.from_bytes()` and `int.to_bytes()`.

- `hex()`, `oct()`, `bin()`.

- Міні-мова специфікації формату for hex, octal, and binary numbers.

- `str` to `float`.

- `str` to `decimal.Decimal`.

### Configuring the limit

Before Python starts up you can use an environment variable or an interpreter command line flag to configure the limit:

- `PYTHONINTMAXSTRDIGITS`, e.g. `PYTHONINTMAXSTRDIGITS=640 python3` to set the limit to 640 or `PYTHONINTMAXSTRDIGITS=0 python3` to disable the limitation.

- `-X int_max_str_digits`, e.g. `python3 -X int_max_str_digits=640`

- `sys.flags.int_max_str_digits` contains the value of `PYTHONINTMAXSTRDIGITS` or `-X int_max_str_digits`. If both the env var and the `-X` option are set, the `-X` option takes precedence. A value of -1 indicates that both were unset, thus a value of `sys.int_info.default_max_str_digits` was used during initialization.

From code, you can inspect the current limit and set a new one using these `sys` APIs:

- `sys.get_int_max_str_digits()` and `sys.set_int_max_str_digits()` are a getter and setter for the interpreter-wide limit. Subinterpreters have their own limit.

Information about the default and minimum can be found in `sys.int_info`:

- `sys.int_info.default_max_str_digits` is the compiled-in default limit.

- `sys.int_info.str_digits_check_threshold` is the lowest accepted value for the limit (other than 0 which disables it).

Added in version 3.11.

Застереження

Setting a low limit can lead to problems. While rare, code exists that contains integer constants in decimal in their source that exceed the minimum threshold. A consequence of setting the limit is that Python source code containing decimal integer literals longer than the limit will encounter an error during parsing, usually at startup time or import time or even at installation time - anytime an up to date `.pyc` does not already exist for the code. A workaround for source that contains such large constants is to convert them to `0x` hexadecimal form as it has no limit.

Test your application thoroughly if you use a low limit. Ensure your tests run with the limit set early via the environment or flag so that it applies during startup and even during any installation step that may invoke Python to precompile `.py` sources to `.pyc` files.

### Recommended configuration

The default `sys.int_info.default_max_str_digits` is expected to be reasonable for most applications. If your application requires a different limit, set it from your main entry point using Python version agnostic code as these APIs were added in security patch releases in versions before 3.12.

Приклад:

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

If you need to disable it entirely, set it to `0`.

Виноски

[ 1 ]

Додаткову інформацію про ці спеціальні методи можна знайти в довідковому посібнику Python (Базове налаштування).

[ 2 ]

Як наслідок, список `[1, 2]` вважається рівним `[1.0, 2.0]`, і аналогічно для кортежів.

[ 3 ]

Мабуть, оскільки аналізатор не може визначити тип операндів.

[4] (1,2,3,4)

Регістр символів — це символи загальної категорії, які мають одну з таких властивостей: «Lu» (літера, верхній регістр), «Ll» (літера, нижній регістр) або «Lt» (літера, регістр заголовка).

[5] (1,2)

Щоб відформатувати лише кортеж, ви повинні надати одиночний кортеж, єдиним елементом якого є кортеж, який потрібно відформатувати.