Python 3.12 MagicMethods - 50 - __lshift__

Python 3.12 Magic Method - `lshift(self, other)`

__lshift__ 是 Python 中用于定义左移位运算符 << 的核心魔术方法。它最常见的用途是实现整数的位左移，但也可以被重载用于任何需要"向左移动"语义的操作，例如向容器添加元素（类似 << 在 C++ 中的流输出重载）。正确实现 __lshift__ 可以让自定义类支持 << 运算，并与其他位运算符（如 >>、&、|）保持一致的语义。本文将详细解析其定义、底层机制、设计原则，并通过多个示例逐行演示如何正确实现。

1. 定义与签名

python 复制代码

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

参数：
- self：当前对象（左操作数）。
- other：另一个操作数（右操作数），通常表示移位的位数。
返回值 ：应返回一个新的对象，代表左移运算的结果。如果运算未定义（例如类型不兼容），应返回单例 NotImplemented。
调用时机 ：
- x << y 会首先尝试调用 x.__lshift__(y)。
- 如果 x.__lshift__(y) 返回 NotImplemented，Python 会尝试调用 y.__rlshift__(x)（反向左移）。
- 如果两者都返回 NotImplemented，最终抛出 TypeError。

2. 用途与典型场景

整数位运算 ：自定义整数类型（如大整数、有限域元素）支持 << 运算。
自定义容器 ：模仿 C++ 的 << 流输出语义，用于向容器添加元素（例如 my_list << item）。但需谨慎，因为 Python 中 << 通常保留给位运算。
生成器或流式处理：将数据推入处理管道。
模拟硬件操作：如寄存器移位等。

左移运算通常满足 x << y 与 y << x 不同，因此反向方法需要独立实现。

3. 底层实现机制

在 Python/C API 层面，每个类型对象（PyTypeObject）都有一个 tp_as_number 结构体，其中包含 nb_lshift 槽位，这是一个函数指针，用于处理左移操作。当执行 x << y 时，解释器会：

获取 x 的类型对象的 tp_as_number 结构。
如果存在 nb_lshift，则调用它，传入 x 和 y，返回结果对象或 Py_NotImplemented。
如果 x 的 nb_lshift 返回 Py_NotImplemented，则尝试获取 y 的类型对象的 nb_lshift，并调用它，但此时参数顺序已交换（即调用 y 的 __rlshift__ 对应的 C 函数）。
如果仍然失败，则抛出 TypeError。

对于 Python 层定义的 __lshift__，它会被包装到 nb_lshift 槽位中。反向方法 __rlshift__ 也会在必要时被调用，用于处理左操作数不支持该运算的情况。

4. 设计原则与最佳实践

遵循数学/语义一致性 ：对于整数类型，左移 x << y 应等价于 x * (2 ** y)（前提是结果不溢出）。对于自定义容器，应明确定义语义。
返回新对象 ：__lshift__ 通常不应修改操作数本身，而应返回一个新对象，以保持不可变性（除非你明确设计为就地修改，但通常这不是左移的预期行为）。
类型检查 ：应检查 other 的类型是否兼容，如果类型不匹配，应返回 NotImplemented，而不是抛出异常。这给另一操作数提供尝试反向运算的机会。
与 __rlshift__ 和 __ilshift__ 的协作 ：
- 如果左移满足交换律（例如数值运算？实际上不满足），则 __rlshift__ 不能简单委托给 __lshift__，除非你确定两者等价。
- __ilshift__ 用于就地左移（<<=），通常应修改自身并返回 self，适用于可变对象。
处理负数移位 ：对于整数，负数移位会引发 ValueError，自定义类应模仿这一行为。

5. 示例与逐行解析

示例 1：自定义整数类（支持位左移）

python 复制代码

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):
            # 确保 other 是非负整数？Python 内置允许负数，但会引发 ValueError
            return MyInt(self.value << other)
        return NotImplemented

    def __rlshift__(self, other):
        # 处理 其他类型 << MyInt
        if isinstance(other, int):
            return MyInt(other << self.value)
        return NotImplemented

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

逐行解析：

行	代码	解释
1-3	`__init__`	初始化整数值。
4-10	`__lshift__`	正向左移。
5-7	处理同类型	如果 `other` 是 `MyInt`，使用其 `value` 进行左移，返回新 `MyInt`。
8-9	处理整数	如果 `other` 是整数，直接使用内置左移。
10	返回 `NotImplemented`	类型不支持时返回 `NotImplemented`。
11-15	`__rlshift__`	反向左移，处理 `int << MyInt`。这里直接使用整数左移。
16-17	`__repr__`	便于显示。

验证：

python 复制代码

a = MyInt(5)
b = MyInt(2)
print(a << b)        # MyInt(20)  (5 << 2 = 20)
print(a << 3)        # MyInt(40)
print(10 << a)       # MyInt(320) (10 << 5 = 320) 通过 __rlshift__

为什么这样写？

__lshift__ 通过类型检查处理不同情况。
__rlshift__ 独立实现，因为 int << MyInt 需要计算 other << self.value。
返回新对象，保持不可变性。

运行结果：

复制代码

MyInt(20)
MyInt(40)
MyInt(320)

示例 2：自定义容器（使用 `<<` 添加元素）

python 复制代码

class MyList:
    def __init__(self, items=None):
        self._items = list(items) if items else []

    def __lshift__(self, item):
        # 使用左移语义添加元素：返回一个新列表，原列表不变
        return MyList(self._items + [item])

    def __ilshift__(self, item):
        # 就地左移添加元素：修改自身并返回 self
        self._items.append(item)
        return self

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

逐行解析：

行	代码	解释
1-3	`__init__`	初始化内部列表。
4-6	`__lshift__`	返回一个新列表，包含原列表元素和新元素。不修改原对象。
7-10	`__ilshift__`	就地添加元素，修改自身并返回 `self`。
11-12	`__repr__`	便于显示。

验证：

python 复制代码

lst = MyList([1, 2])
new_lst = lst << 3 << 4   # 注意：<< 是左结合，实际等价于 (lst << 3) << 4
print(lst)                # MyList([1, 2])  原列表不变
print(new_lst)            # MyList([1, 2, 3, 4])

lst <<= 5                  # 就地修改
print(lst)                # MyList([1, 2, 5])

为什么这样写？

这里 __lshift__ 用于不可变操作，返回新对象；__ilshift__ 用于可变操作。这种设计分离了两种语义。
注意 << 是左结合的，因此 lst << 3 << 4 先执行 lst << 3 返回新列表，再对新列表执行 << 4。这符合预期。

运行结果：

复制代码

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

示例 3：模拟位移寄存器

python 复制代码

class ShiftRegister:
    def __init__(self, width, value=0):
        self.width = width
        self.value = value & ((1 << width) - 1)

    def __lshift__(self, bits):
        """左移 bits 位，低位补0，丢弃超出宽度的位"""
        new_val = (self.value << bits) & ((1 << self.width) - 1)
        return ShiftRegister(self.width, new_val)

    def __ilshift__(self, bits):
        self.value = (self.value << bits) & ((1 << self.width) - 1)
        return self

    def __repr__(self):
        return f"ShiftRegister(width={self.width}, value={bin(self.value)})"

解析：

这里 __lshift__ 和 __ilshift__ 都实现了有限宽度的位移，模拟硬件寄存器行为。

验证：

python 复制代码

reg = ShiftRegister(8, 0b1010)  # 8 位寄存器，初始值 00001010
print(reg)
print(id(reg))

reg <<= 2
print(reg)  # ShiftRegister(width=8, value=0b101000)
print(id(reg))

new_reg = reg << 1
print(new_reg)  # ShiftRegister(width=8, value=0b1010000) 注意高位丢弃
print(id(new_reg))

运行结果：

复制代码

ShiftRegister(width=8, value=0b1010)
1950464170496
ShiftRegister(width=8, value=0b101000)
1950464170496
ShiftRegister(width=8, value=0b1010000)
1950464170544

示例 4：处理负数移位（模仿内置行为）

Python 中 5 << -1 会引发 ValueError。自定义类也应如此。

python 复制代码

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

    def __lshift__(self, other):
        if isinstance(other, int):
            if other < 0:
                raise ValueError("negative shift count")
            return MyInt(self.value << other)
        return NotImplemented

验证：

python 复制代码

m1 =  MyInt(4)
m2 = m1 << -2

运行结果：

复制代码

Traceback (most recent call last):
  File "\py_magicmethods_lshift_04.py", line xx, in <module>
    m2 = m1 << -2
         ~~~^^~~~
  File "\py_magicmethods_lshift_04.py", line xx, in __lshift__
    raise ValueError("negative shift count")
ValueError: negative shift count

6. 与 `rlshift` 和 `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 ：__lshift__ 应返回新对象，除非你明确设计为就地修改（但通常使用 __ilshift__ 实现就地语义）。
正确使用 NotImplemented ：当类型不兼容时返回 NotImplemented，而不是抛出异常。这给另一侧机会处理。
负数移位 ：内置整数对负数移位会引发 ValueError，自定义类应保持一致。
与 >> 的关系：通常左移和右移应相互对应，但非必须。
避免无限递归 ：在 __rlshift__ 中不要调用 self << other，应直接实现运算逻辑。

8. 总结

特性	说明
角色	定义左移位运算符 `<<`
签名	`__lshift__(self, other) -> object`
返回值	新对象，或 `NotImplemented`
调用时机	`x << y`，以及反向尝试
底层	C 层的 `nb_lshift` 槽位
与 `__rlshift__` 的关系	反向左移，用于 `other << self`，需独立实现
与 `__ilshift__` 的关系	就地左移 `<<=`，通常修改自身并返回 `self`
最佳实践	返回新对象、类型检查、使用 `NotImplemented`、处理负数移位

掌握 __lshift__ 可以实现自定义类对左移运算的支持，无论是数学上的位运算还是具有特殊语义的"推送"操作。通过理解其底层机制和设计原则，你可以构建出与 Python 内置类型一样自然、健壮的类。

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

Python 3.12 MagicMethods - 50 - __lshift__

Python 3.12 Magic Method - __lshift__(self, other)

1. 定义与签名

2. 用途与典型场景

3. 底层实现机制

4. 设计原则与最佳实践

5. 示例与逐行解析

示例 1：自定义整数类（支持位左移）

示例 2：自定义容器（使用 << 添加元素）

示例 3：模拟位移寄存器

示例 4：处理负数移位（模仿内置行为）

6. 与 __rlshift__ 和 __ilshift__ 的关系

7. 注意事项与陷阱

8. 总结

Python 3.12 MagicMethods - 50 - lshift

Python 3.12 Magic Method - `lshift(self, other)`

示例 2：自定义容器（使用 `<<` 添加元素）

6. 与 `rlshift` 和 `ilshift` 的关系