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

Магические методы (dunder-методы) — специальные методы с двойным подчёркиванием до и после имени, которые Python вызывает автоматически при определённых операциях над объектами. Они позволяют управлять строковым представлением, сравнением, индексированием, вызовами объектов и многим другим. Этот материал объясняет основные и продвинутые приёмы, даёт практические примеры, контрольные сценарии, чек-листы и подсказки для выбора правильного метода.

Лого Python и примеры применения языка

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

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

Женщина, сдувающая блёстки с ладони

Опишите магические методы как «скрытые» вызовы: когда вы пишете len(obj), print(obj) или obj1 + obj2, Python на самом деле вызывает соответствующий специальный метод объекта. Они называются dunder-методами (double underscore), например init или str. Это соглашение даёт возможность контролировать поведение через знакомый синтаксис.

Коротко о типах методов:

Инстансные методы — работают на экземпляре класса (обычно принимают self).
Класс-методы — принимают класс как первый аргумент (cls) и обозначаются @classmethod.
Статические методы — не получают автоматически ни self, ни cls, используются для вспомогательной логики.

Основные dunder-методы, которые часто встречаются:

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

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

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

В этом разделе — практические примеры, скопируйте и запускайте фрагменты в терминале или REPL.

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

Когда вы не определяете str и repr, Python использует стандартное представление <main.Person object at 0x…>. Часто удобнее предоставить более читабельную строку.

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({self.name!r}, {self.age!r}, {self.height!r})'

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

Примечание: repr хорош для отладки и должен по возможности давать строку, из которой объект можно восстановить через eval() (когда это безопасно).

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

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

Если семантически len(obj) соответствует некоторому атрибуту (например, высоте или числу элементов), реализуйте len:

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__

Замечание: len() традиционно возвращает целое неотрицательное значение; если ваш 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

Если метод возвращает NotImplemented для неподдерживаемого типа, Python попытается вызвать зеркальный оператор у другого объекта или вернёт False.

Сравнение экземпляров класса Person

Продвинутые приёмы

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

Реализуйте набор магических методов, чтобы ваш класс вел себя как контейнер (список, словарь, кортеж): len, getitem, setitem, delitem, iter.

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

Контейнерные объекты хорошо интегрируются с for, in, list(), tuple() и другими утилитами, если реализовать iter и/или другие методы итерации.

Класс, веду́щий себя как контейнер

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

getattr вызывается только если атрибут не найден обычными способами. getattribute вызывается для любого доступа — используйте его осторожно.

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

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

Используйте getattr для ленивой генерации атрибутов, проксирования или обратной совместимости.

Демонстрация изменения доступа к атрибуту

Делать экземпляры вызываемыми

call превращает экземпляр в функцию — полезно для объектов-конфигураторов, фабрик и динамических вычислителей.

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

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

Экземпляры, действующие как функции

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

Определяя методы вроде add, sub, mul, вы задаёте смысл операций +, -, *. Пример для векторов:

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)

Результат сложения векторов

Обычно определяют и зеркальные методы (radd), чтобы поддержать выражения, где левый операнд другого типа.

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

Important: Магические методы повышают выразительность, но их чрезмерное или неправильное применение ухудшает читаемость. Рассмотрите альтернативы:

Композиция вместо наследования: храните объект-поле и реализуйте явные методы.
Обычные методы вместо магических, если операция нестандартна и не ожидается разработчиком.
Dataclasses и attrs для классов, где нужны автогенерируемые init, repr, eq.

Counterexample: не реализуйте len для возвращения плавающего числа или неположительного значения, если это сбивает с толку пользователей API.

Методология выбора магического метода

Мини‑методология (шаги):

Определите желаемый синтаксис: len(obj)? obj[key]? obj + other?
Сопоставьте синтаксис с dunder-методом (например, len → len).
Подумайте о граничных случаях и типах аргументов (возвращать NotImplemented при несовместимости).
Добавьте тесты для ожидаемых сценариев и для некорректных типов.
Документируйте поведение в docstring.

Mermaid-поток для выбора метода:

flowchart TD
  A[Нужно ли объекту поддерживать len''?] -->|Да| B[Реализовать __len__]
  A -->|Нет| C{Нужен индекс или ключ?}
  C -->|Да| D[Реализовать __getitem__ и при необходимости __setitem__]
  C -->|Нет| E{Нужен вызов как функцию?}
  E -->|Да| F[Реализовать __call__]
  E -->|Нет| G[Рассмотреть обычный метод или композицию]

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

Для каждого реализованного магического метода проверьте:

Корректные значения на нормальных данных (unit tests).
Корректная реакция на неподдерживаемые типы (NotImplemented или TypeError).
Документированное поведение и отсутствие побочных эффектов.
Производительность и побочные аллокации (при необходимости профилировать).

Пример тест-кейсов:

eq: сравнение с объектом другого класса → False или NotImplemented.
len: отрицательные или нецелые значения → явное поведение (ошибка/преобразование).
getitem: индекс за пределами → IndexError.

Риски и рекомендации по безопасности

Не возвращайте в repr секретные данные (пароли, токены). repr может попасть в логи.
Если getattr динамически получает данные (сеть, база) — учитывайте задержки и ошибки.
Избегайте выполнения произвольного кода в init и repr.

Чек-лист для разработчика и ревьюера

Для разработчика:

Соответствует ли поведение ожидаемому синтаксису?
Есть ли unit-тесты на положительные и негативные сценарии?
Возвращается ли NotImplemented для неподдерживаемых типов?
[ ] repr не раскрывает чувствительные данные?

Для ревьюера:

Код читаемый и понятный без магии?
Документация и docstrings обновлены?
Производительность не критически ухудшена?

Советы по совместимости и миграции

В Python 3 поведение сравнения (cmp отсутствует) заменяется набором методов lt, le, gt, ge, и eq. Для упрощения можно использовать functools.total_ordering.
Для простых моделей данных рассмотрите dataclasses (Python 3.7+), которые генерируют init, repr, eq автоматически.
Проверяйте поведение при сериализации (pickle, json) — некоторые магические методы влияют на совместимость.

Glossary — 1 строка

dunder-метод: метод с двухсторонним подчёркиванием, вызываемый автоматически встроенными операциями.

Краткое резюме

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

Summary: