# `operator` — Standard operators as functions

Вихідний код: Lib/operator.py

Модуль `operator` експортує набір ефективних функцій, що відповідають внутрішнім операторам Python. Наприклад, `operator.add(x, y)` еквівалентний виразу `x+y`. Багато назв функцій використовуються для спеціальних методів без подвійного підкреслення. Для зворотної сумісності багато з них мають варіант із збереженням подвійного підкреслення. Варіанти без подвійного підкреслення є кращими для ясності.

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

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

operator.lt(a, b)
operator.le(a, b)
operator.eq(a, b)
operator.ne(a, b)
operator.ge(a, b)
operator.gt(a, b)
operator.__lt__(a, b)
operator.__le__(a, b)
operator.__eq__(a, b)
operator.__ne__(a, b)
operator.__ge__(a, b)
operator.__gt__(a, b)

  Виконайте «багаті порівняння» між a і b. Зокрема, `lt(a, b)` еквівалентно `a < b`, `le(a, b)` is equivalent to `a <= b`, `eq(a, b)` is equivalent to `a == b`, `ne(a, b)` is equivalent to `a != b`, `gt(a, b)` is equivalent to `a > b`, а `ge(a, b)` еквівалентно `a >= b`. Зауважте, що ці функції можуть повертати будь-яке значення, яке може інтерпретуватися як логічне значення. Перегляньте Порівняння для отримання додаткової інформації про розширені порівняння.

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

operator.not_(obj)
operator.__not__(obj)

  Return the outcome of `not` obj. (Note that there is no `__not__()` method for object instances; only the interpreter core defines this operation. The result is affected by the `__bool__()` and `__len__()` methods.)

operator.truth(obj)

  Повертає `True`, якщо obj має значення true, і `False` в іншому випадку. Це еквівалентно використанню конструктора `bool`.

operator.is_(a, b)

  Повернути `a is b`. Перевіряє ідентичність об’єкта.

operator.is_not(a, b)

  Повернути `a не є b`. Перевіряє ідентичність об’єкта.

Найбільш численні математичні та порозрядні операції:

operator.abs(obj)
operator.__abs__(obj)

  Повертає абсолютне значення obj.

operator.add(a, b)
operator.__add__(a, b)

  Повертає `a + b` для чисел a і b.

operator.and_(a, b)
operator.__and__(a, b)

  Повертає побітове і для a і b.

operator.floordiv(a, b)
operator.__floordiv__(a, b)

  Повернути `a // b`.

operator.index(a)
operator.__index__(a)

  Повернути a, перетворене на ціле число. Еквівалент `a.__index__()`.

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

operator.inv(obj)
operator.invert(obj)
operator.__inv__(obj)
operator.__invert__(obj)

  Повертає побітове обернення числа obj. Це еквівалентно `~obj`.

operator.lshift(a, b)
operator.__lshift__(a, b)

  Повернути a зі зсувом вліво на b.

operator.mod(a, b)
operator.__mod__(a, b)

  Повернути `a % b`.

operator.mul(a, b)
operator.__mul__(a, b)

  Повертає `a * b` для чисел a і b.

operator.matmul(a, b)
operator.__matmul__(a, b)

  Повернути `a @ b`.

  Нове в версії 3.5.

operator.neg(obj)
operator.__neg__(obj)

  Повернути obj відхилено (`-obj`).

operator.or_(a, b)
operator.__or__(a, b)

  Повертає побітове або a і b.

operator.pos(obj)
operator.__pos__(obj)

  Повертає obj позитивний (`+obj`).

operator.pow(a, b)
operator.__pow__(a, b)

  Повертає `a ** b` для чисел a і b.

operator.rshift(a, b)
operator.__rshift__(a, b)

  Повернути a зі зсувом вправо на b.

operator.sub(a, b)
operator.__sub__(a, b)

  Повернути `a - b`.

operator.truediv(a, b)
operator.__truediv__(a, b)

  Повертає `a / b`, де 2/3 дорівнює 0,66, а не 0. Це також відоме як «справжнє» ділення.

operator.xor(a, b)
operator.__xor__(a, b)

  Повертає порозрядне виключне або a і b.

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

operator.concat(a, b)
operator.__concat__(a, b)

  Повертає `a + b` для послідовностей a і b.

operator.contains(a, b)
operator.__contains__(a, b)

  Повертає результат тесту `b в a`. Зверніть увагу на зворотні операнди.

operator.countOf(a, b)

  Повертає кількість входжень b у a.

operator.delitem(a, b)
operator.__delitem__(a, b)

  Видалити значення a в індексі b.

operator.getitem(a, b)
operator.__getitem__(a, b)

  Повертає значення a за індексом b.

operator.indexOf(a, b)

  Повертає індекс першого входження b в a.

operator.setitem(a, b, c)
operator.__setitem__(a, b, c)

  Установіть значення a в індексі b на c.

operator.length_hint(obj, default=0)

  Return an estimated length for the object obj. First try to return its actual length, then an estimate using `object.__length_hint__()`, and finally return the default value.

  Нове в версії 3.4.

The following operation works with callables:

operator.call(obj, /, *args, **kwargs)
operator.__call__(obj, /, *args, **kwargs)

  Return `obj(*args, **kwargs)`.

  Нове в версії 3.11.

Модуль `operator` також визначає інструменти для узагальненого пошуку атрибутів і елементів. Вони корисні для створення швидких екстракторів полів як аргументів для `map()`, `sorted()`, `itertools.groupby()` або інших функцій, які очікують аргумент функції.

operator.attrgetter(attr)
operator.attrgetter(*attrs)

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

  - Після `f = attrgetter('name')` виклик `f(b)` повертає `b.name`.

  - Після `f = attrgetter('name', 'date')` виклик `f(b)` повертає `(b.name, b.date)`.

  - Після `f = attrgetter('name.first', 'name.last')` виклик `f(b)` повертає `(b.name.first, b.name.last)` .

  Дорівнює:

      def attrgetter(*items):
          if any(not isinstance(item, str) for item in items):
              raise TypeError('attribute name must be a string')
          if len(items) == 1:
              attr = items[0]
              def g(obj):
                  return resolve_attr(obj, attr)
          else:
              def g(obj):
                  return tuple(resolve_attr(obj, attr) for attr in items)
          return g

      def resolve_attr(obj, attr):
          for name in attr.split("."):
              obj = getattr(obj, name)
          return obj

operator.itemgetter(item)
operator.itemgetter(*items)

  Return a callable object that fetches item from its operand using the operand’s `__getitem__()` method. If multiple items are specified, returns a tuple of lookup values. For example:

  - Після `f = itemgetter(2)` виклик `f(r)` повертає `r[2]`.

  - Після `g = itemgetter(2, 5, 3)` виклик `g(r)` повертає `(r[2], r[5], r[3])`.

  Дорівнює:

      def itemgetter(*items):
          if len(items) == 1:
              item = items[0]
              def g(obj):
                  return obj[item]
          else:
              def g(obj):
                  return tuple(obj[item] for item in items)
          return g

  The items can be any type accepted by the operand’s `__getitem__()` method. Dictionaries accept any hashable value. Lists, tuples, and strings accept an index or a slice:

      >>> itemgetter(1)('ABCDEFG')
      'B'
      >>> itemgetter(1, 3, 5)('ABCDEFG')
      ('B', 'D', 'F')
      >>> itemgetter(slice(2, None))('ABCDEFG')
      'CDEFG'
      >>> soldier = dict(rank='captain', name='dotterbart')
      >>> itemgetter('rank')(soldier)
      'captain'

  Приклад використання `itemgetter()` для отримання певних полів із запису кортежу:

      >>> inventory = [('apple', 3), ('banana', 2), ('pear', 5), ('orange', 1)]
      >>> getcount = itemgetter(1)
      >>> list(map(getcount, inventory))
      [3, 2, 5, 1]
      >>> sorted(inventory, key=getcount)
      [('orange', 1), ('banana', 2), ('apple', 3), ('pear', 5)]

operator.methodcaller(name, /, *args, **kwargs)

  Повертає викликаний об’єкт, який викликає метод ім’я свого операнда. Якщо надано додаткові аргументи та/або ключові аргументи, вони також будуть надані методу. Наприклад:

  - Після `f = methodcaller('name')` виклик `f(b)` повертає `b.name()`.

  - Після `f = methodcaller('name', 'foo', bar=1)` виклик `f(b)` повертає `b.name('foo', bar=1)`.

  Дорівнює:

      def methodcaller(name, /, *args, **kwargs):
          def caller(obj):
              return getattr(obj, name)(*args, **kwargs)
          return caller

## Відображення операторів у функції

У цій таблиці показано, як абстрактні операції відповідають символам операторів у синтаксисі Python і функціям у модулі `operator`.

Операція | Синтаксис | функція
--- | --- | ---
Доповнення | `a + b` | `add(a, b)`
Конкатенація | `seq1 + seq2` | `concat(seq1, seq2)`
Тест на утримання | `obj in seq` | `contains(seq, obj)`
Поділ | `a / b` | `truediv(a, b)`
Поділ | `a // b` | `floordiv(a, b)`
Порозрядне І | `а і б` | `і_(a, b)`
Порозрядне виняткове або | `a ^ b` | `xor(a, b)`
Побітова інверсія | `~ a` | `invert(a)`
Побітове або | `a | b` | `або_(a, b)`
Піднесення до степеня | `a ** b` | `pow(a, b)`
Ідентичність | `a є b` | `is_(a, b)`
Ідентичність | `a не є b` | `is_not(a, b)`
Індексоване призначення | `obj[k] = v` | `setitem(obj, k, v)`
Індексоване видалення | `del obj[k]` | `виділення(obj, k)`
Індексація | `obj[k]` | `getitem(obj, k)`
Ліворуч | `a << b` | `lshift(a, b)`
Модуло | `a % b` | `mod(a, b)`
Множення | `a * b` | `mul(a, b)`
Множення матриць | `a @ b` | `matmul(a, b)`
Заперечення (арифметика) | `- a` | `neg(a)`
Заперечення (логічне) | `не` | `not_(a)`
Позитивний | `+ a` | `pos(a)`
Правий Shift | `a >> b` | `rshift(a, b)`
Призначення фрагмента | `seq[i:j] = значення` | `setitem(seq, slice(i, j), values)`
Видалення фрагмента | `del seq[i:j]` | `delitem(seq, slice(i, j))`
Нарізка | `seq[i:j]` | `getitem(seq, slice(i, j))`
Форматування рядка | `s % obj` | `mod(s, obj)`
Віднімання | `а - б` | `під(a, b)`
Тест на правду | `obj` | `truth(obj)`
Замовлення | `a < b` | `lt(a, b)`
Замовлення | `a <= b` | `le(a, b)`
Рівність | `a == b` | `eq(a, b)`
Різниця | `a != b` | `ne(a, b)`
Замовлення | `a >= b` | `ge(a, b)`
Замовлення | `a > b` | `gt(a, b)`

## Оператори на місці

Багато операцій мають версію «на місці». Нижче наведено функції, які забезпечують примітивніший доступ до операторів на місці, ніж звичайний синтаксис; наприклад, раз (statement) `x += y` еквівалентний `x = operator.iadd(x, y)`. Інший спосіб сказати, що `z = operator.iadd(x, y)` еквівалентно складеному оператору `z = x; z += y`.

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

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

    >>> a = 'hello'
    >>> iadd(a, ' world')
    'hello world'
    >>> a
    'hello'

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

    >>> s = ['h', 'e', 'l', 'l', 'o']
    >>> iadd(s, [' ', 'w', 'o', 'r', 'l', 'd'])
    ['h', 'e', 'l', 'l', 'o', ' ', 'w', 'o', 'r', 'l', 'd']
    >>> s
    ['h', 'e', 'l', 'l', 'o', ' ', 'w', 'o', 'r', 'l', 'd']

operator.iadd(a, b)
operator.__iadd__(a, b)

  `a = iadd(a, b)` еквівалентно `a += b`.

operator.iand(a, b)
operator.__iand__(a, b)

  `a = iand(a, b)` еквівалентно `a &= b`.

operator.iconcat(a, b)
operator.__iconcat__(a, b)

  `a = iconcat(a, b)` еквівалентно `a += b` для послідовностей a і b.

operator.ifloordiv(a, b)
operator.__ifloordiv__(a, b)

  `a = ifloordiv(a, b)` еквівалентно `a //= b`.

operator.ilshift(a, b)
operator.__ilshift__(a, b)

  `a = ilshift(a, b)` еквівалентно `a <<= b`.

operator.imod(a, b)
operator.__imod__(a, b)

  `a = imod(a, b)` еквівалентно `a %= b`.

operator.imul(a, b)
operator.__imul__(a, b)

  `a = imul(a, b)` еквівалентно `a *= b`.

operator.imatmul(a, b)
operator.__imatmul__(a, b)

  `a = imatmul(a, b)` еквівалентно `a @= b`.

  Нове в версії 3.5.

operator.ior(a, b)
operator.__ior__(a, b)

  `a = ior(a, b)` еквівалентно `a |= b`.

operator.ipow(a, b)
operator.__ipow__(a, b)

  `a = ipow(a, b)` еквівалентно `a **= b`.

operator.irshift(a, b)
operator.__irshift__(a, b)

  `a = irshift(a, b)` еквівалентно `a >>= b`.

operator.isub(a, b)
operator.__isub__(a, b)

  `a = isub(a, b)` еквівалентно `a -= b`.

operator.itruediv(a, b)
operator.__itruediv__(a, b)

  `a = itruediv(a, b)` еквівалентно `a /= b`.

operator.ixor(a, b)
operator.__ixor__(a, b)

  `a = ixor(a, b)` еквівалентно `a ^= b`.