Обзор магических методов (dunder) в Python [2.9]

1. Что такое магические методы (dunder) и как они “включаются”

Определение

Магические методы — это специальные методы, имена которых начинаются и заканчиваются двойным подчёркиванием: __init__, __len__, __iter__, __add__ и т.д. Python вызывает их автоматически, когда вы используете стандартные конструкции языка.

Например, когда вы пишете len(obj), Python пытается вызвать obj.__len__(). Когда пишете for x in obj, Python ищет obj.__iter__(). Когда пишете a + b — вызывается a.__add__(b) (если он определён).

Почему это “мост” между объектом и синтаксисом

Можно думать о dunder-методах как о “переводчиках”: синтаксис Python (операторы и функции) обращается к вашему объекту через заранее известные имена методов. Поэтому один раз реализовав метод __iter__, вы сразу получаете совместимость с for, list(), tuple(), многими алгоритмами и библиотеками.

Мини-пример: len(), for и оператор +

Ниже — упрощённый пример: класс содержит внутренний список и “прокидывает” к нему поведение. Это очень распространённая техника: оборачивать встроенный тип, добавляя инварианты/правила.

class Box:
    def __init__(self, items):
        self._items = list(items)

    def __len__(self):
        return len(self._items)

    def __iter__(self):
        return iter(self._items)

    def __add__(self, other):
        return Box(self._items + list(other))

2. SortedArray: идея, инварианты и интерфейс

Задача и требования

Построим класс SortedArray, который хранит только целые числа и всегда держит их отсортированными. Это отличный учебный пример, потому что:

• нужно контролировать входные данные (проверка типов);
• нужно поддерживать инвариант (сортировка всегда сохранена);
• хочется, чтобы объект вёл себя “как список”: for, len(), in, [];
• хочется перегрузить операторы: +, ==, <, >.

Инварианты: что класс обязан гарантировать

Инвариант — это правило, которое должно быть истинным всегда после завершения любой публичной операции. Для SortedArray инварианты такие:

• внутри хранятся только значения типа int;
• внутренний список всегда отсортирован по возрастанию.

Магические методы здесь помогают сделать интерфейс естественным, но важно помнить: именно __init__ и методы изменения данных должны “держать” инвариант.

Как будет выглядеть “удобный” API

Хотим, чтобы пользователь мог писать так:

a = SortedArray([3, 1, 4, 2])
print(list(a))          # [1, 2, 3, 4]
print(len(a))           # 4
print(3 in a)           # True
print(a[0], a[-1])      # 1 4

b = a + 10              # прибавить 10 к каждому элементу
c = a + SortedArray([5, -1])  # объединить и отсортировать

3. Жизненный цикл: __init__, приватность и __del__

__init__: проверка типов и сортировка

__init__ — первое место, где мы можем обеспечить корректность. Если пустить “плохие” данные внутрь, дальше придётся защищаться в каждом методе. Поэтому правильно: проверка типов + сортировка в конструкторе.

class SortedArray:
    def __init__(self, arr=None):
        if arr is None:
            arr = []

        # 1) Проверяем тип каждого элемента
        if not all(isinstance(x, int) for x in arr):
            raise ValueError("Список содержит не только целые числа")

        # 2) Сохраняем всегда в отсортированном виде
        self.__arr = sorted(arr)

Опасность arr=[ ] по умолчанию

Почему arr=[ ] плохая идея? Потому что значение по умолчанию создаётся один раз — в момент определения функции, а не при каждом вызове. Если бы мы изменяли этот список (например, делали arr.append(...)), то изменения могли “протекать” между объектами.

Даже если вы не модифицируете список напрямую, привычка использовать None как дефолт — это стандарт де-факто и снижает риск ошибок при будущих изменениях кода.

__arr и “приватность” (name mangling)

Атрибут __arr не просто “соглашение”, как _arr. Python преобразует имя атрибута, чтобы его нельзя было случайно переопределить в наследниках и чтобы к нему сложнее было обращаться снаружи. Это не безопасность, а механизм дисциплины.

__del__: почему почти всегда не нужен

В Python управление памятью автоматическое (сборщик мусора), поэтому __del__ редко нужен. Более того, наличие __del__ иногда усложняет сборку мусора. Если вы работаете с файлами/сокетами — чаще применяют контекстный менеджер (with), а не __del__.

4. Коллекция: итерация, len(), in, индексация и приведение типов

__iter__: for, list(), tuple()

Если ваш объект — “контейнер”, то первое ожидание пользователя: по нему можно пройти циклом. Реализация __iter__ обычно очень простая: вернуть итератор внутреннего контейнера.

class SortedArray:
    # ... __init__

    def __iter__(self):
        return iter(self.__arr)

После этого автоматически работают: for x in obj, list(obj), tuple(obj) и множество функций, которые принимают “итерируемое”.

__len__ и __contains__

Чтобы работало len(obj), реализуют __len__. Чтобы работало x in obj (оператор принадлежности), реализуют __contains__. Если не реализовать __contains__, Python иногда пытается перебором через итерацию, но лучше сделать явно.

class SortedArray:
    # ...
    def __len__(self):
        return len(self.__arr)

    def __contains__(self, item):
        return item in self.__arr

__getitem__: индексация и срезы

Метод __getitem__ отвечает за obj[index]. Важно: в Python индекс может быть не только числом, но и срезом slice, например obj[1:4].

class SortedArray:
    # ...
    def __getitem__(self, index):
        return self.__arr[index]

__int__, __float__, __bool__: смысловые преобразования

Приведение типов — это соглашение: вы сами выбираете смысл. Главное — чтобы преобразование выглядело логично и не удивляло пользователя.

• __int__: часто “обобщающая характеристика” — например сумма или количество.
• __float__: может быть среднее значение, медиана и т.д.
• __bool__: чаще всего “пустой/непустой”.

class SortedArray:
    # ...
    def __int__(self):
        return sum(self.__arr)

    def __float__(self):
        return sum(self.__arr) / len(self.__arr) if self.__arr else 0.0

    def __bool__(self):
        return len(self.__arr) > 0

__repr__ и __str__: отладка vs “красиво вывести”

Два метода часто путают:

• __str__ — человекочитаемый вывод (то, что печатается в print(obj)).
• __repr__ — отладочное представление (то, что видите в консоли/логах).

Хорошее правило: __repr__ должен быть максимально информативным и по возможности похожим на код, который создаёт объект (не всегда возможно, но это полезная цель).

class SortedArray:
    # ...
    def __str__(self):
        return str(self.__arr)

    def __repr__(self):
        return f"SortedArray({self.__arr!r})"

5. Перегрузка операторов: сравнения и арифметика

__eq__ и сравнения: как делать корректно

Сравнение — важный элемент интерфейса. Но у него есть тонкость: что считать “равенством”? В нашем примере (как в учебной задаче) равенство зависит от среднего значения, то есть два разных массива могут быть “равны”, если их среднее одинаковое.

В реальных проектах чаще сравнивают либо полный набор элементов (как списки), либо уникальный ключ. Но для демонстрации dunder-методов вариант со средним подходит.

Почему лучше возвращать NotImplemented

Когда оператор встречает неизвестный тип справа, хорошей практикой считается вернуть NotImplemented, а не бросать исключение. Тогда Python попробует выполнить “обратную” операцию (например, вызвать метод другого объекта). Если и там не получится — Python сам выдаст корректный TypeError.

class SortedArray:
    # ...
    def __eq__(self, other):
        if not isinstance(other, SortedArray):
            return NotImplemented
        return float(self) == float(other)

    def __lt__(self, other):
        if not isinstance(other, SortedArray):
            return NotImplemented
        return float(self) < float(other)

    def __gt__(self, other):
        if not isinstance(other, SortedArray):
            return NotImplemented
        return float(self) > float(other)

__add__ и __radd__: поддержка obj + x и x + obj

__add__ определяет поведение obj + other. Но если вы хотите, чтобы работало ещё и other + obj (например, 3 + SortedArray([...])), вам нужен __radd__ — “reverse add”.

class SortedArray:
    # ...
    def __add__(self, other):
        if isinstance(other, int):
            return SortedArray([x + other for x in self.__arr])
        if isinstance(other, SortedArray):
            return SortedArray(self.__arr + list(other))
        return NotImplemented

    def __radd__(self, other):
        # Позволяет писать: 3 + SortedArray([1,2,3])
        return self.__add__(other)

6. Шпаргалка: самые полезные dunder-методы

Группы методов

• Жизненный цикл: __init__, __del__
• Строки и отладка: __str__, __repr__
• Контейнер: __iter__, __len__, __contains__, __getitem__
• Сравнения: __eq__, __lt__, __gt__, __le__, __ge__
• Арифметика: __add__, __sub__, __mul__, ...

Таблица “синтаксис → метод”

7. Практика: частые ошибки и улучшения SortedArray

Типичные ошибки

Как защитить инвариант “всегда отсортировано”

Самая частая проблема: пользователь может захотеть “вставить элемент” или “изменить по индексу”. Если вы добавите __setitem__ без контроля, можно легко разрушить сортировку.

Поэтому часто делают так:

• либо вообще не дают изменять элементы по индексу (нет __setitem__),
• либо разрешают только безопасные операции, которые сохраняют сортировку (например, метод add(x)).

Идеи расширения

Если захочется сделать класс ещё “взрослее”, можно добавить:

• метод вставки с сохранением сортировки через модуль bisect;
• __iadd__ для +=;
• __mul__ для умножения (например, повторить элементы или масштабировать значения);
• поддержку срезов, возвращающих новый SortedArray, а не обычный список.

8. Самопроверка (чек-лист)

Таблица с чекбоксами