Магические методы Python

Классы в Python позволяют аккуратно объединять данные и поведение. Создавая собственные классы, вы моделируете реальные сущности: пользователей, товары, сотрудников. Магические методы дают вам способ настроить поведение этих классов так, чтобы экземпляры вели себя как встроенные типы Python.

Понимание магических методов

Женщина, дующая конфетти в ладонь

Представьте магические методы (dunder-методы) как скрытые заклинания: Python вызывает их автоматически при определённых операциях с объектом. Они позволяют вам описать, как экземпляр класса должен реагировать на:

создание и инициализацию;
приведение к строке и отладочное представление;
сравнения (<, ==, >);
операции над объектами (+, -, и т.д.);
индексирование и итерацию;
вызов экземпляра как функции;
динамический доступ к атрибутам.

Магические методы — это обычные методы экземпляра с двойным подчёркиванием до и после имени, например init, str, eq.

Основные часто используемые магические методы:

gt — проверяет, больше ли один объект другого (>)
init — конструктор, инициализирует атрибуты при создании экземпляра
str — строковое представление экземпляра для людей
repr — формальное представление, пригодное для отладки и (по возможности) для воспроизведения через eval()
len — возвращает «длину» объекта при вызове len(obj)
eq — сравнение на равенство (==)
lt — реализация операции меньше (<)
add — поведение при операции +
getitem — доступ по индексу или ключу: obj[key]

Реализация магических методов — практика

Лучший способ понять магические методы — применять их. Ниже — короткие, реальные примеры.

Строковое представление объекта

Если не определить str и repr, print(obj) выводит неинформативное представление. Определите str для удобного вывода, repr — для отладки.

class Person:
    def __init__(self, name, age):
        self.name = name
        self.age = age

p1 = Person('John', 25)
print(p1)

По умолчанию получите что-то вроде — не очень удобно.

Стандартное строковое представление объекта

Определим str и repr:

class Person:
    def __init__(self, name, age, height):
        self.name = name
        self.age = age
        self.height = height

    def __str__(self):
        return f'{self.name} is {self.age} years old'

    def __repr__(self):
        return f"Person(name={self.name!r}, age={self.age!r}, height={self.height!r})"

p1 = Person('John', 25, 78)
print(p1)

Кастомное строковое представление объекта

Важно: repr обычно возвращает более «формальное» представление, пригодное для отладки или даже для воссоздания объекта. str — для удобочитаемого вывода пользователям.

Свойство длины объекта

Можно заставить len(obj) возвращать, например, рост человека.

class Person:
    def __init__(self, name, age, height):
        self.name = name
        self.age = age
        self.height = height

    def __len__(self):
        return self.height

p2 = Person('Issac', 25, 89)
print(len(p2))  # 89

Изменённое поведение len

Сравнение объектов

Если эквивалентность ваших объектов логически не совпадает с тождественностью по ссылке, определите eq.

class Person:
    def __init__(self, name, age, height):
        self.name = name
        self.age = age
        self.height = height

    def __eq__(self, other):
        if not isinstance(other, Person):
            return NotImplemented
        return self.name == other.name and self.age == other.age

p1 = Person('John', 25, 56)
p2 = Person('John', 25, 61)
print(p1 == p2)  # True (имя и возраст совпали)

Сравнение двух объектов одного класса

Оператор == будет опираться на eq, а не на id(). Не забывайте возвращать NotImplemented, если сравнение с неподдерживаемым типом.

Продвинутые магические методы

Классы как контейнеры

С помощью len, getitem, setitem, delitem вы можете сделать экземпляр ведёт себя как контейнер.

class Person:
    def __init__(self):
        self.data = []

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

    def __getitem__(self, index):
        return self.data[index]

    def __setitem__(self, index, value):
        self.data[index] = value

    def __delitem__(self, index):
        del self.data[index]

p1 = Person()
p1.data = [10, 2, 7]
print(len(p1))  # 3
p1[0] = 5
print(p1[0])  # 5

Классы, действующие как контейнеры

Это удобно, если вам нужен объект с внутренним списком/мапой, но со скрытой логикой доступа.

Кастомный доступ к атрибутам

getattr вызывается, когда атрибута нет в объекте; getattribute перехватывает все обращения (используйте осторожно).

class Person:
    def __getattr__(self, name):
        if name == 'age':
            return 40
        raise AttributeError(f'No attribute {name}')

p1 = Person()
print(p1.age)  # 40

Изменённый доступ к атрибутам

Для всех остальных имён выбрасывается AttributeError.

Экземпляры как вызываемые объекты

call позволяет вызывать экземпляр как функцию.

class Adder:
    def __call__(self, x, y):
        return x + y

adder = Adder()
print(adder(2, 3))  # 5

Классы, ведующие себя как вызываемые объекты

Перегрузка операторов

Определяя add, mul, sub и т.д., вы задаёте поведение операторов для ваших типов.

class Vector:
    def __init__(self, x, y):
        self.x = x
        self.y = y

    def __add__(self, other):
        if isinstance(other, Vector):
            return Vector(self.x + other.x, self.y + other.y)
        return NotImplemented

    def __str__(self):
        return f'({self.x}, {self.y})'

v1 = Vector(2, 3)
v2 = Vector(1, 4)
v3 = v1 + v2
print(v3)  # (3, 7)

Результат перегрузки оператора

Когда магические методы не подходят

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

Не используйте len для возвращения значения, не связанного с «размером» объекта в логическом смысле.
Не перегружайте операторы, если смысл операции неочевиден (например, сложение, возвращающее удалённый ресурс).
Не злоупотребляйте getattribute — он перехватывает всё и может легко привести к рекурсивным багам.

Альтернативы и паттерны

Для простого API используйте обычные методы (to_str(), equals(other)), если операция специфична.
Для сериализации предпочтите dataclasses, attrs или pydantic — они упрощают repr, сравнение и валидацию.
Для коллекций используйте коллекции из collections.abc (MutableSequence, Mapping) и наследуйте их, чтобы получить стандартизованное поведение.

Эмпирические правила (heuristics)

Возвращайте NotImplemented при сравнении с неподдерживаемым типом.
repr должен помогать дебагу; str — человеку.
Документируйте любые нестандартные применения магических методов.
Пишите тесты для каждого магического метода — изменения в них легко ломают контракт.

Важно: Магические методы — это контракт. Другие разработчики (и ваш будущий вы) будут ожидать «производное» поведение от стандартных операций. Документируйте и тестируйте.

Чит‑шит: часто используемые магические методы (подсказка)

init(self, …) — конструктор
new(cls, …) — выделение памяти и создание экземпляра (редко нужно)
repr(self) — формальное представление
str(self) — удобочитаемое представление
len(self) — длина
getitem(self, key) — доступ по индексу/ключу
setitem(self, key, value) — присвоение по индексу
delitem(self, key) — удаление по индексу
iter(self) — возвращает итератор
contains(self, item) — оператор in
eq/lt/gt/le/ge/ne — сравнения
add/sub/mul/truediv — арифметика
call(self, …) — делает экземпляр вызываемым
getattr/getattribute — динамический доступ к атрибутам

Чек‑лист по ролям (кратко)

Разработчик:
- Документируй поведение магических методов.
- Возвращай NotImplemented, если тип не поддерживается.
- Покрой тестами крайние случаи.
Архитектор:
- Убедись, что перегрузка операторов соответствует доменной модели.
- Предпочти композицию наследованию, когда поведение сложное.
Тестировщик:
- Напиши тесты на сравнения, сериализацию и граничные случаи.
- Тестируй совместимость с неизменяемыми и изменяемыми типами.

Критерии приёмки

Все магические методы покрыты тестами (unit tests).
Документация класса описывает ожидаемое поведение операций (+, len(), == и т.д.).
Для сравнения с внешними типами возвращается NotImplemented.
Нет скрытой побочной логики в getattr или call.

Мини‑методология внедрения магических методов

Определите поведение, которое хотите получить (печать, сравнение, индексирование).
Выберите соответствующий магический метод.
Реализуйте метод, соблюдая инварианты и возвращая NotImplemented для неподдерживаемых типов.
Документируйте контракт метода в docstring.
Добавьте unit-тесты для позитивных и негативных сценариев.
Проведите ревью API на предмет принципа наименьшего удивления.

Decision flow: нужен ли магический метод?

flowchart TD
  A[Нужно ли объекту вести себя как встроенный тип?] -->|Да| B[Какое поведение?]
  A -->|Нет| Z[Обычный метод предпочтительнее]
  B --> C{Показать данные пользователю?}
  C -->|Да| D[__str__ + __repr__]
  C -->|Нет| E{Нужно индексирование?}
  E -->|Да| F[__getitem__/__setitem__/__len__]
  E -->|Нет| G{Нужно сравнение?}
  G -->|Да| H[__eq__/__lt__/__gt__]
  G -->|Нет| I{Нужно вызывать экземпляр как функцию?}
  I -->|Да| J[__call__]
  I -->|Нет| Z

Тесты и сценарии приёмки (примеры)

len(obj) возвращает ожидаемое число для пустого и заполненного состояния.
obj1 == obj2 корректно сравнивает ключевые поля и возвращает False для иных типов.
При вызове obj(key) (если поддерживается) получаем ожидаемый результат и проверяем обработку неверных аргументов.

Примеры ошибок и антишаблонов

len возвращает значение из несвязанного атрибута (сбивает ожидания).
getattr молча создаёт новые атрибуты и изменяет состояние — это ведёт к трудноуловимым багам.
Перегрузка + для типов, где «сложение» не имеет смысла.

Локальные советы для русскоязычных проектов

В документации на русском чётко опишите семантику: «len() возвращает количество X».
В CLI/логах выводьте str, но в дебаге используйте repr.

Резюме

Магические методы дают удобные и мощные способы интегрировать ваши классы с синтаксисом Python. Применяйте их осознанно: документируйте поведение, возвращайте NotImplemented при несопоставимых типах и покрывайте тестами. Если семантика операции неочевидна — выберите явный метод вместо магии.

Иллюстрация концепции OOP и магических методов