파이썬 매직 메서드 완벽 가이드: 커스텀 연산자와 객체 동작 제어

파이썬 매직 메서드, 즉 던더 메서드는 __init__, __repr__, __len__, __add__처럼 이름 앞뒤에 이중 밑줄이 붙은 특별한 메서드입니다. 직접 만든 클래스가 +, len(), 비교, 반복, 인덱싱 같은 파이썬 문법에 어떻게 반응할지 정의할 때 사용하며, 임의로 호출하기보다 해당 문법을 통해 파이썬이 호출하도록 설계하는 것이 핵심입니다.

Python 데이터 모델에서 특수 메서드 확인하기

1. 매직 메서드는 언제 호출되나요?

던더 메서드는 연산자와 내장 함수가 객체에 요청을 보내는 약속입니다. 예를 들어 len(obj)는 객체 유형의 __len__ 구현을 이용하고, obj1 + obj2는 덧셈 관련 특수 메서드를 확인합니다. 코드에서 obj.__len__()처럼 직접 호출할 수도 있지만 일반적으로는 len(obj)를 사용해야 파이썬 데이터 모델의 일관성을 유지할 수 있습니다.

모든 메서드를 구현할 필요는 없습니다. 객체가 어떤 개념을 나타내고 어떤 문법이 자연스러운지 먼저 정한 뒤 필요한 프로토콜만 선택하는 편이 좋습니다.

2. 객체 생성과 문자열 표현

__init__은 이미 생성된 인스턴스의 초기 상태를 설정합니다. 객체를 실제로 만드는 과정에는 __new__도 관여하지만, 불변형을 상속하는 등 특별한 이유가 없다면 보통 __init__부터 구현합니다.

class Product:
    def __init__(self, name, price):
        self.name = name
        self.price = price

    def __repr__(self):
        return f"Product(name={self.name!r}, price={self.price!r})"

    def __str__(self):
        return f"{self.name}: {self.price:,}원"

__repr__은 가능하다면 객체를 명확히 식별하고 재생성에 도움이 되는 표현을 반환하는 것이 좋습니다. __str__은 최종 사용자에게 보여줄 읽기 쉬운 표현입니다. __str__이 없으면 파이썬은 __repr__을 대신 사용할 수 있습니다. 로그에 객체를 남길 때 표현 메서드가 유용하지만, 비밀번호나 개인정보가 노출되지 않도록 주의해야 합니다.

3. __add__로 커스텀 연산자 구현하기

연산자 오버로딩은 기호의 우선순위를 바꾸는 기능이 아니라, 사용자 정의 객체에 해당 연산의 의미를 제공하는 기능입니다. 금액, 좌표, 벡터처럼 덧셈 의미가 명확한 객체에 적용하면 코드가 읽기 쉬워집니다.

from dataclasses import dataclass

@dataclass(frozen=True)
class Vector:
    x: float
    y: float

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

v1 = Vector(1, 2)
v2 = Vector(3, 4)
print(v1 + v2)  # Vector(x=4, y=6)

호환되지 않는 형식이면 NotImplemented를 반환해야 파이썬이 상대 객체의 __radd__ 같은 역방향 연산을 시도할 수 있습니다. 실제로 지원하지 않는 연산이라면 최종적으로 파이썬이 적절한 TypeError를 발생시킵니다. None을 반환하면 실패가 늦게 드러나므로 피해야 합니다.

자주 쓰는 산술 메서드

• __add__, __sub__, __mul__: 일반 이항 연산
• __radd__, __rsub__: 왼쪽 피연산자가 처리하지 못한 역방향 연산
• __iadd__, __imul__: +=, *= 같은 제자리 연산

4. 객체 비교와 __hash__ 설계

__eq__는 두 객체가 값의 관점에서 같은지 정의합니다. 정렬 비교에는 __lt__, __le__, __gt__, __ge__가 사용됩니다. 모든 비교 메서드를 직접 만들기 전에 객체에 자연스러운 전체 순서가 있는지 판단해야 합니다.

class User:
    def __init__(self, user_id, name):
        self.user_id = user_id
        self.name = name

    def __eq__(self, other):
        if not isinstance(other, User):
            return NotImplemented
        return self.user_id == other.user_id

    def __hash__(self):
        return hash(self.user_id)

같다고 비교되는 객체는 같은 해시값을 가져야 합니다. 또한 딕셔너리 키나 집합 원소로 사용되는 동안 해시에 참여하는 값이 바뀌면 안 됩니다. 따라서 가변 객체에 __hash__를 무리하게 제공하지 않는 편이 안전합니다. __eq__만 재정의하면 해시 가능 여부가 달라질 수 있으므로 딕셔너리와 집합 사용까지 테스트해야 합니다.

5. 내 클래스를 컨테이너처럼 동작시키기

__len__, __getitem__, __contains__, __iter__를 목적에 맞게 구현하면 객체가 파이썬 컨테이너 문법과 자연스럽게 연동됩니다.

class Playlist:
    def __init__(self, songs):
        self._songs = list(songs)

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

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

    def __iter__(self):
        yield from self._songs

playlist = Playlist(["봄", "여름", "가을"])
print(len(playlist))
print(playlist[0])
for song in playlist:
    print(song)

__len__은 0 이상의 정수를 반환해야 합니다. __getitem__에서 슬라이스도 지원하려면 전달된 키가 slice인지 고려해야 합니다. 반복을 직접 구현할 때 __iter__에서 제너레이터를 사용하면 별도 이터레이터 클래스를 만들지 않고도 현재 값을 하나씩 전달할 수 있습니다.

6. with 문과 호출 가능한 객체 만들기

__enter__와 __exit__를 구현하면 객체를 with 문에서 사용할 수 있습니다. __exit__는 예외 형식, 예외 값, 트레이스백을 전달받으며, 참인 값을 반환하면 예외를 억제하므로 특별한 복구 의도가 없다면 함부로 True를 반환하지 않아야 합니다.

class Timer:
    def __enter__(self):
        from time import perf_counter
        self.started = perf_counter()
        return self

    def __exit__(self, exc_type, exc_value, traceback):
        from time import perf_counter
        self.elapsed = perf_counter() - self.started
        print(f"{self.elapsed:.4f}초")
        return False

with Timer():
    total = sum(range(100_000))

__call__을 구현하면 인스턴스를 함수처럼 호출할 수도 있습니다. 설정과 상태를 유지하는 변환기나 검증기에는 유용하지만, 단순 함수로 충분하다면 클래스를 추가하지 않는 편이 더 명료할 수 있습니다.

7. 목적별 매직 메서드 선택표

8. 실수 방지 체크리스트

• 의미가 불분명한 연산자를 편의만으로 추가하지 않았는지 확인합니다.
• 지원하지 않는 이항 연산에서 NotImplemented를 반환하는지 확인합니다.
• __repr__와 로그에 개인정보·비밀값이 노출되지 않는지 점검합니다.
• __eq__를 바꿨다면 __hash__와 집합 동작도 확인합니다.
• __len__이 음수나 정수가 아닌 값을 반환하지 않는지 확인합니다.
• __iter__가 자기 자신을 잘못 재사용해 두 번째 반복을 비우지 않는지 테스트합니다.
• __exit__에서 의도하지 않게 예외를 억제하지 않는지 확인합니다.
• 파이썬이 이미 사용하는 던더 이름을 임의의 일반 메서드 용도로 만들지 않습니다.

공식 출처

• Python 데이터 모델: Special method names
• Python 데이터 모델: __repr__
• Python 데이터 모델: Emulating numeric types
• Python 데이터 모델: Context managers

공식 문서 확인일: 2026년 9월 2일