定制类：Python 特殊方法(Magic Methods)完全指南

在 Python 中，以双下划线 __ 开头和结尾的方法（如 __init__、__str__）被称为魔法方法（或特殊方法）。它们是 Python 类定制的核心，能让我们的自定义类型表现得和内置类型（如列表、字符串）一样自然。本文将梳理常用魔法方法的用法，结合示例带你掌握类定制的技巧。

1. 对象表示方法：让实例「会说话」

当我们打印对象或在交互式环境查看它时，Python 会调用特殊方法来生成字符串表示。最常用的是 __str__ 和 __repr__。

__str__ 和 __repr__

class Student:
    def __init__(self, name):
        self.name = name
        
    def __str__(self):
        # 面向用户的友好表示：print() 或 str() 时调用
        return f"学生对象（姓名：{self.name}）"
    
    def __repr__(self):
        # 面向开发者的精确表示：交互环境直接输入变量名时调用
        return f"Student(name={self.name!r})"
    
    # 若两者内容一致，可简写为：__repr__ = __str__

使用示例：

s = Student("张三")
print(s)          # 调用 __str__：学生对象（姓名：张三）
s                 # 调用 __repr__：Student(name='张三')

💡 最佳实践：

  • __repr__ 应尽可能包含重建对象的信息（如 Student(name='张三') 能直接复制运行）；
  • 若只实现一个，优先选 __repr__——因为 __str__ 未定义时会自动回退到 __repr__。

2. 迭代器协议：让实例「可循环」

要让对象能被 for 循环遍历，需要实现 __iter__ 和 __next__ 两个方法，这就是迭代器协议。

__iter__ 和 __next__

以斐波那契数列生成器为例：

class Fibonacci:
    def __init__(self, max_num=100):
        self.a, self.b = 0, 1
        self.max_num = max_num
        
    def __iter__(self):
        # 迭代器协议要求 __iter__ 返回一个迭代器——这里实例本身就是迭代器
        return self
    
    def __next__(self):
        self.a, self.b = self.b, self.a + self.b
        if self.a > self.max_num:
            # 超过上限时抛出异常，终止迭代
            raise StopIteration()
        return self.a

使用示例：

for num in Fibonacci(20):
    print(num)  # 输出：1 1 2 3 5 8 13

3. 序列协议：让实例「支持下标访问」

如果想让对象像列表一样用 [] 访问（包括索引和切片），需要实现 __getitem__；若要支持修改或删除元素，再加 __setitem__ 和 __delitem__。

__getitem__ 示例

我们给斐波那契类加上下标访问功能：

class IndexedFib:
    def __getitem__(self, n):
        # 处理单个索引
        if isinstance(n, int):
            a, b = 1, 1
            for _ in range(n):
                a, b = b, a + b
            return a
        # 处理切片
        elif isinstance(n, slice):
            start = n.start or 0
            stop = n.stop
            step = n.step or 1
            result = []
            a, b = 1, 1
            for i in range(stop):
                if i >= start and (i - start) % step == 0:
                    result.append(a)
                a, b = b, a + b
            return result
        else:
            raise TypeError("索引必须是整数或切片")

使用示例：

fib = IndexedFib()
fib[5]          # 单个索引：8
fib[1:10:2]     # 切片：[1, 3, 8, 21, 55]

若想支持 len() 函数，再加一个 __len__ 方法即可：

def __len__(self):
    # 这里简单返回前100项的长度，实际可按需实现
    return 100

4. 属性访问控制：动态处理属性

当访问或设置对象不存在的属性时，Python 会调用 __getattr__ 和 __setattr__，我们可以用它们实现动态属性管理。

__getattr__ 和 __setattr__

class DynamicAttrs:
    def __init__(self):
        # 用私有字典存储动态属性
        self._data = {}
        
    def __getattr__(self, name):
        # 访问不存在的属性时调用
        if name in self._data:
            return self._data[name]
        raise AttributeError(f"属性 {name} 不存在")
        
    def __setattr__(self, name, value):
        # 设置属性时调用（注意：所有属性赋值都会触发它！）
        if name == "_data":
            # 避免递归：直接调用父类的 __setattr__
            super().__setattr__(name, value)
        else:
            self._data[name] = value

使用示例：

obj = DynamicAttrs()
obj.age = 18      # 调用 __setattr__，存入 _data
obj.age           # 调用 __getattr__，返回 18

5. 可调用对象：让实例「像函数一样」

实现 __call__ 方法后，类的实例可以像函数一样被调用，这在需要保存状态的「函数」中很有用。

__call__ 示例

做一个带前缀的日志记录器：

class PrefixedLogger:
    def __init__(self, prefix):
        self.prefix = prefix
        
    def __call__(self, message):
        print(f"[{self.prefix}] {message}")

使用示例：

debug_log = PrefixedLogger("DEBUG")
debug_log("这是一条调试信息")  # 输出：[DEBUG] 这是一条调试信息

# 用 callable() 检查是否可调用
callable(debug_log)  # 返回 True

6. 上下文管理器：让实例「支持 with 语句」

with 语句能自动管理资源（如打开/关闭文件），要让类支持它，需要实现 __enter__ 和 __exit__。

__enter__ 和 __exit__ 示例

模拟一个资源管理类：

class Resource:
    def __enter__(self):
        print("获取资源")
        # 返回的对象会赋值给 with 后的 as 变量
        return self
    
    def __exit__(self, exc_type, exc_val, exc_tb):
        # exc_type/val/tb：若有异常，分别是异常类型、值、回溯；否则为 None
        print("释放资源")
        # 返回 False 表示不抑制异常（默认行为），返回 True 则会吞掉异常
        return False

使用示例：

with Resource() as res:
    print("使用资源中...")
# 输出：
# 获取资源
# 使用资源中...
# 释放资源

7. Python 3.x 新增的实用魔法方法

__bytes__：定义转字节序列的行为

class Student:
    def __init__(self, name):
        self.name = name
    def __bytes__(self):
        return self.name.encode("utf-8")

s = Student("李四")
bytes(s)  # 返回 b'李四'

__format__：自定义格式化输出

class Student:
    def __init__(self, name, score):
        self.name = name
        self.score = score
    def __format__(self, format_spec):
        if format_spec == "score":
            return f"{self.name}：{self.score}分"
        return f"{self.name}"

s = Student("王五", 90)
f"{s:score}"  # 返回 "王五：90分"

__class_getitem__（3.7+）：支持泛型类型提示

简单来说，它能让类像 list[int] 一样用于类型注解，比如：

class MyContainer:
    def __class_getitem__(cls, item_type):
        return f"{cls.__name__}[{item_type.__name__}]"

MyContainer[str]  # 返回 "MyContainer[str]"

最佳实践

  1. 保持一致性：魔法方法的行为要和内置类型对齐（比如 __len__ 必须返回非负整数）；
  2. 优先实现 __repr__：它是对象的「官方」表示，能覆盖 __str__ 的缺失；
  3. 避免 __getattribute__ 滥用：所有属性访问都会触发它，容易导致递归，非必要不用；
  4. 性能优先：魔法方法常被隐式调用（比如循环里的 __next__），要保证高效。

总结

Python 的魔法方法就像一套「钩子」，让我们能无缝定制类的行为。从字符串表示到迭代、从属性管理到上下文管理，掌握这些方法，就能写出更简洁、更符合 Python 风格的代码。如果想了解全部魔法方法，可以参考官方文档～