Python 3.12 MagicMethods - 51 - __rlshift__

Python 3.12 Magic Method - __rlshift__(self, other)

---

__rlshift__ 是 Python 中用于定义 反向左移位运算符 的魔术方法。当左操作数不支持与右操作数的 << 运算时，Python 会尝试调用右操作数的 __rlshift__ 方法，从而实现 other << self 的运算。由于左移运算通常不满足交换律，__rlshift__ 的实现必须独立处理，不能简单地委托给 __lshift__ 。本文将详细解析其定义、底层机制、设计原则，并通过多个示例逐行演示如何正确实现。

---

1. 定义与签名

def __rlshift__(self, other) -> object:
    ...

• 参数 ：
  • self：当前对象（右操作数，因为它是被调用的对象）。
  • other：另一个操作数（左操作数），可以是任意类型。
• 返回值 ：应返回一个新的对象，代表 other << self 的结果。如果运算未定义，应返回单例 NotImplemented 。
• 调用时机 ：当执行 x << y 时 ：
  • 首先尝试调用 x.__lshift__(y) 。
  • 如果 x.__lshift__(y) 返回 NotImplemented，则尝试调用 y.__rlshift__(x) 。
  • 如果两者都返回 NotImplemented，最终抛出 TypeError 。

---

2. 为什么需要 __rlshift__？

左移位运算（<<）通常用于将二进制位向左移动，相当于乘以 2 的幂。该运算不满足交换律 ：x << y 一般不等于 y << x。因此，Python 的运算符分发机制必须能正确处理两种顺序的运算。

考虑一个自定义整数类 MyInt，我们希望它支持与整数的左移：

• MyInt(5) << 2（正向）可以通过 __lshift__ 实现。
• 2 << MyInt(5)（反向）则需要 __rlshift__，因为内置 int 的 __lshift__ 不知道如何处理 MyInt，会返回 NotImplemented。

如果左操作数不支持运算，Python 会调用右操作数的反向方法，让你的类有机会定义 other << self 的语义。这正是 __rlshift__ 的作用------支持左操作数为其他类型的左移运算。

---

3. 底层实现机制

在 CPython 中，左移操作的处理遵循标准的反向运算符查找机制。<< 运算符对应 tp_as_number.nb_lshift 槽位 。当执行 x << y 时，解释器会：

1. 调用 x.__lshift__(y)（C 层对应 nb_lshift）。
2. 如果返回 NotImplemented，则调用 y.__rlshift__(x)（C 层通过交换参数再次调用 nb_lshift，但 Python 会自动将这次调用定向到 __rlshift__ ）。
3. 如果仍返回 NotImplemented，抛出 TypeError。

这种机制确保了非交换运算的正确性。如果直接使用 y.__lshift__(x) 代替反向调用，结果将是错误的，因为 x << y 和 y << x 语义不同 。因此，__rlshift__ 是专门为右操作数设计的独立方法。

---

4. 设计原则与最佳实践

• 独立实现 ：由于左移不满足交换律，__rlshift__ 必须实现 other << self 的语义，不能简单地委托给 __lshift__（除非你明确知道二者等价，但通常不成立）。
• 类型检查 ：应检查 other 的类型是否兼容。如果类型不匹配，返回 NotImplemented 。不要抛出异常，这样给其他类型机会处理。
• 返回新对象 ：左移运算通常应返回新对象，不修改原操作数（除非类是可变的且你使用 <<= 运算符）。
• 处理负数移位 ：内置整数对负数移位会引发 ValueError，自定义类也应模仿这一行为。
• 避免无限递归 ：在 __rlshift__ 中不要调用 self << other 或 other << self 的另一种形式，否则可能导致循环。

---

5. 示例与逐行解析

示例 1：自定义整数类支持反向左移

class MyInt:
    def __init__(self, value):
        self.value = value

    def __lshift__(self, other):
        # 正向：MyInt << 其他类型
        if isinstance(other, MyInt):
            return MyInt(self.value << other.value)
        if isinstance(other, int):
            return MyInt(self.value << other)
        return NotImplemented

    def __rlshift__(self, other):
        # 反向：其他类型 << MyInt
        if isinstance(other, int):
            # 处理负数移位（模仿内置行为）
            if self.value < 0:
                raise ValueError("negative shift count")
            return MyInt(other << self.value)
        return NotImplemented

    def __repr__(self):
        return f"MyInt({self.value})"

逐行解析：

行	代码	解释
1-3	__init__	初始化整数值。
4-10	__lshift__	正向移位，处理同类型和整数。
11-17	__rlshift__	反向移位，处理 int << MyInt。
13-15	负数检查	如果 self.value 为负，抛出 ValueError，与内置行为一致。
16	返回新对象	用计算结果创建新 MyInt。
18-19	__repr__	便于显示。

验证：

a = MyInt(3)
b = MyInt(2)
print(5 << a)        # 5 << 3 = 40 → MyInt(40)
print(5 << -1)       # 抛出 ValueError: negative shift count

运行结果：

MyInt(40)
Traceback (most recent call last):
  File "\py_magicmethods_rlshfit_01.py", line 49, in <module>
    print(5 << -1)       # 抛出 ValueError: negative shift count
          ~~^^~~~
ValueError: negative shift count

为什么这样写？

• __rlshift__ 独立实现，不能调用 self << other，因为顺序相反。
• 类型检查确保只有整数被处理，其他类型返回 NotImplemented 。
• 负数移位检查保持与内置 int 一致。

示例 2：处理混合类型（自定义类作为右操作数）

class MyList:
    def __init__(self, items):
        self.items = items

    def __rlshift__(self, other):
        # 当左操作数是整数时，解释为：将整数添加到列表开头
        if isinstance(other, int):
            return MyList([other] + self.items)
        return NotImplemented

    def __repr__(self):
        return f"MyList({self.items})"

验证：

ml = MyList([2, 3, 4])
result = 1 << ml      # 调用 ml.__rlshift__(1)
print(result)         # MyList([1, 2, 3, 4])

解析 ：

这里我们赋予了 << 新的语义：整数左移列表表示将整数插入列表头部。虽然这不是标准的移位含义，但展示了 __rlshift__ 的灵活性。注意，正向 ml << 1 未定义，所以 1 << ml 触发了反向调用。

运行结果：

MyList([1, 2, 3, 4])

示例 3：与 __ilshift__ 配合的完整类

class Buffer:
    def __init__(self, data):
        self.data = data

    def __lshift__(self, other):
        # 返回新 buffer，数据左移（丢弃左边元素）
        return Buffer(self.data[other:] + [0] * other)

    def __rlshift__(self, other):
        # other 是整数，将整数插入 buffer 左侧（非标准，但演示用）
        if isinstance(other, int):
            return Buffer([other] + self.data)
        return NotImplemented

    def __ilshift__(self, other):
        # 就地左移
        self.data = self.data[other:] + [0] * other
        return self

    def __repr__(self):
        return f"Buffer({self.data})"

验证：

b = Buffer([1, 2, 3, 4])
result = 0 << b      # 调用 __rlshift__
print(result)        # Buffer([0, 1, 2, 3, 4])

解析 ：

这里 0 << b 触发了反向调用，将 0 插入到 buffer 开头。这种用法虽然不符合常规，但体现了运算符重载的自由度。

运行结果：

Buffer([0, 1, 2, 3, 4])

示例 4：处理非交换场景的正确实现

对于数值左移，必须保证反向运算的正确性：

class MyInt:
    def __init__(self, value):
        self.value = value

    def __lshift__(self, other):
        # 正向：self << other
        return MyInt(self.value << other)

    def __rlshift__(self, other):
        # 反向：other << self
        return MyInt(other << self.value)

    def __repr__(self):
        return f"MyInt({self.value})"

解析 ：

正向和反向分别计算，结果不同，符合预期。

验证：

a = MyInt(2)
print(3 << a)   # 3 << 2 = 12
print(a << 3)   # 2 << 3 = 16 (正向)

运行结果：

MyInt(12)
MyInt(16)

---

6. 与 __lshift__ 和 __ilshift__ 的关系

方法	作用	典型返回值	调用时机
__lshift__(self, other)	正向左移 self << other	新对象	x << y
__rlshift__(self, other)	反向左移 other << self	新对象	正向返回 NotImplemented 时
__ilshift__(self, other)	就地左移 self <<= other	self	x <<= y

关键区别：

• __rlshift__ 用于左操作数不支持运算时的反向调用，由于左移不满足交换律，必须独立实现。
• __ilshift__ 用于原地修改对象，应返回 self，适用于可变对象。

---

7. 注意事项与陷阱

• 不要调用 self << other ：在 __rlshift__ 中调用 self << other 会再次触发 __lshift__，可能导致无限递归（如果 __lshift__ 返回 NotImplemented）。应直接实现运算逻辑。
• 正确处理 NotImplemented ：当类型不兼容时返回 NotImplemented，而不是抛出异常 。
• 负数移位 ：内置整数对负数移位会引发 ValueError，自定义类应模仿这一行为。
• 与 __lshift__ 的一致性 ：确保 other << self 的结果符合数学定义，并与 self << other 不同（除非运算交换）。

---

8. 总结

特性	说明
角色	定义反向左移位运算符 other << self
签名	__rlshift__(self, other) -> object
调用时机	左操作数的 __lshift__ 返回 NotImplemented 时
返回值	新对象，或 NotImplemented
底层	由 Python 的运算符分发机制在 C 层处理，通过交换参数调用右操作数的 __rlshift__
与 __lshift__ 的关系	独立实现，不满足交换律
最佳实践	类型检查、返回 NotImplemented、直接实现运算逻辑、处理负数移位

掌握 __rlshift__ 是实现自定义类与 Python 运算符生态无缝集成的关键，尤其是在处理混合类型运算时。通过理解其底层机制和设计原则，你可以让类支持更自然的左移语义，提升代码的可读性和可用性。

如果在学习过程中遇到问题，欢迎在评论区留言讨论!