14 — Magic Methods & Protocols

# ── A production Vector class implementing the full numeric protocol ──
# Demonstrates __repr__, __eq__, __hash__, __add__, __radd__, __mul__,
# __rmul__, __neg__, __abs__, __bool__, and iteration — the complete set
# needed for a value type to behave like a first-class numeric citizen.

import math
from functools import total_ordering

class Vector:
    """2D vector with full operator support, hashing, and iteration."""

    __slots__ = ("_x", "_y")   # no __dict__ — saves ~40% memory per instance

    def __init__(self, x: float, y: float):
        self._x = float(x)
        self._y = float(y)

    # ── Representation: __repr__ for debugging, __str__ for display ──
    def __repr__(self) -> str:
        # Should be unambiguous — ideally eval-able: Vector(repr(v)) == v
        return f"Vector({self._x!r}, {self._y!r})"

    def __str__(self) -> str:
        return f"({self._x:.2f}, {self._y:.2f})"

    # ── Property access: read-only via slots, no setter needed ──
    @property
    def x(self) -> float:
        return self._x

    @property
    def y(self) -> float:
        return self._y

    # ── Equality and hashing: MUST be consistent (a == b ⟹ hash(a) == hash(b)) ──
    def __eq__(self, other: object) -> bool:
        if not isinstance(other, Vector):
            return NotImplemented   # NOT False — lets Python try other.__eq__(self)
        return self._x == other._x and self._y == other._y

    def __hash__(self) -> int:
        # Hash MUST use the same fields as __eq__ — if x/y change, hash must change
        # Since __slots__ + no setter = immutable, this is safe
        return hash((self._x, self._y))

    # ── Arithmetic: __add__ + __radd__ for commutative addition ──
    def __add__(self, other: "Vector") -> "Vector":
        if not isinstance(other, Vector):
            return NotImplemented   # lets Python try other.__radd__(self)
        return Vector(self._x + other._x, self._y + other._y)

    def __radd__(self, other: "Vector") -> "Vector":
        # Called when `other + self` fails (other doesn't know about Vector)
        # For commutative ops, just delegate to __add__
        return self.__add__(other)

    # ── Scalar multiplication: __mul__ (vec * scalar) + __rmul__ (scalar * vec) ──
    def __mul__(self, scalar: float) -> "Vector":
        if not isinstance(scalar, (int, float)):
            return NotImplemented
        return Vector(self._x * scalar, self._y * scalar)

    def __rmul__(self, scalar: float) -> "Vector":
        return self.__mul__(scalar)   # scalar * vec == vec * scalar

    def __neg__(self) -> "Vector":
        return Vector(-self._x, -self._y)

    # ── Built-in function integration ──
    def __abs__(self) -> float:
        return math.hypot(self._x, self._y)   # math.hypot avoids overflow for large values

    def __bool__(self) -> bool:
        return bool(self._x) or bool(self._y)  # zero vector is falsy

    def __iter__(self):
        # Enables unpacking: x, y = vector
        yield self._x
        yield self._y

    def __len__(self) -> int:
        return 2   # dimensionality — enables len(vec)

# ── Usage: the Vector now behaves like a built-in numeric type ──
v1 = Vector(3, 4)
v2 = Vector(1, 2)

print(v1 + v2)         # Vector(4.0, 6.0) — __add__
print(v1 * 2)          # Vector(6.0, 8.0) — __mul__
print(2 * v1)          # Vector(6.0, 8.0) — __rmul__ (int.__mul__ fails, falls back)
print(-v1)             # Vector(-3.0, -4.0) — __neg__
print(abs(v1))         # 5.0 — __abs__ via math.hypot
print(bool(Vector(0, 0)))  # False — zero vector is falsy
print(v1 == Vector(3, 4))  # True — __eq__

# Hashable → usable as dict keys and set members
points = {v1: "origin-ref", v2: "other"}
print(points[Vector(3, 4)])  # "origin-ref" — found via __hash__ + __eq__

# Iterable → unpacking works
x, y = v1
print(x, y)   # 3.0 4.0

class Point:
    def __init__(self, x, y):
        self.x, self.y = x, y

    def __repr__(self):
        return f"Point({self.x}, {self.y})"

    def __eq__(self, other):
        if not isinstance(other, Point):
            return NotImplemented        # not False! lets Python try other.__eq__(self)
        return self.x == other.x and self.y == other.y

p1, p2 = Point(1, 2), Point(1, 2)
print(p1 == p2)      # True — uses __eq__
print(p1 is p2)         # False — different objects in memory

s = {p1}
# print(p2 in s)      # TypeError: unhashable type: 'Point'

class Point:
    def __init__(self, x, y):
        self.x, self.y = x, y

    def __eq__(self, other):
        return isinstance(other, Point) and (self.x, self.y) == (other.x, other.y)

    def __hash__(self):
        return hash((self.x, self.y))     # MUST be consistent with __eq__

p1, p2 = Point(1, 2), Point(1, 2)
s = {p1}
print(p2 in s)   # True — same hash, and __eq__ agrees they're equal

class BadBag:
    def __init__(self, items):
        self.items = items                # a MUTABLE list

    def __eq__(self, other):
        return self.items == other.items

    def __hash__(self):
        return hash(tuple(self.items))    # hash depends on MUTABLE state

bag = BadBag([1, 2, 3])
s = {bag}
print(bag in s)   # True

bag.items.append(4)    # mutate AFTER inserting into the set
print(bag in s)   # False! — its hash changed, so the set looks in the WRONG bucket
print(s)   # still contains the (now-unreachable) bag

class Deck:
    def __init__(self):
        self.cards = [f"{rank}{suit}" for suit in "SHDC" for rank in "23456789TJQKA"]

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

    def __getitem__(self, index):
        return self.cards[index]      # also enables slicing, `in`, and iteration for free!

deck = Deck()
print(len(deck))          # 52
print(deck[0])               # "2S"
print(deck[-1])                 # "AC"
print(deck[:3])                    # ['2S', '3S', '4S'] — slicing works automatically
print("AC" in deck)                   # True — falls back to linear __getitem__ scan
for card in deck[:2]:
    print(card)                          # iteration ALSO falls back to __getitem__(0), (1), ... until IndexError

class Countdown:
    def __init__(self, start):
        self.start = start

    def __iter__(self):
        n = self.start
        while n > 0:
            yield n            # __iter__ as a generator function — simplest way to implement it
            n -= 1

for i in Countdown(3):
    print(i)   # 3 2 1

print(list(Countdown(5)))   # [5, 4, 3, 2, 1]
print(list(Countdown(5)))     # [5, 4, 3, 2, 1] — a NEW generator each time __iter__ is called, reusable!

class Vector:
    def __init__(self, x, y):
        self.x, self.y = x, y

    def __repr__(self):
        return f"Vector({self.x}, {self.y})"

    def __add__(self, other):
        return Vector(self.x + other.x, self.y + other.y)

    def __sub__(self, other):
        return Vector(self.x - other.x, self.y - other.y)

    def __mul__(self, scalar):
        return Vector(self.x * scalar, self.y * scalar)

    def __rmul__(self, scalar):            # handles scalar * vector (reflected operand order)
        return self.__mul__(scalar)

    def __neg__(self):
        return Vector(-self.x, -self.y)

    def __eq__(self, other):
        return isinstance(other, Vector) and (self.x, self.y) == (other.x, other.y)

v1, v2 = Vector(1, 2), Vector(3, 4)
print(v1 + v2)     # Vector(4, 6)
print(v1 - v2)       # Vector(-2, -2)
print(v1 * 3)          # Vector(3, 6)   — calls v1.__mul__(3)
print(3 * v1)             # Vector(3, 6)   — v1.__mul__ doesn't apply (int has no __mul__ for Vector),
                            # so Python tries v1.__rmul__(3) instead
print(-v1)                   # Vector(-1, -2)

import time

class Timer:
    def __enter__(self):
        self.start = time.perf_counter()
        return self               # the value bound to `as` in `with ... as x`

    def __exit__(self, exc_type, exc_value, traceback):
        self.elapsed = time.perf_counter() - self.start
        print(f"Elapsed: {self.elapsed:.4f}s")
        return False               # False (or None) means: don't suppress exceptions

with Timer() as t:
    total = sum(range(10_000_000))
print(t.elapsed)   # accessible after the block too, since `t` is still in scope

class SuppressValueError:
    def __enter__(self):
        return self

    def __exit__(self, exc_type, exc_value, traceback):
        if exc_type is ValueError:
            print(f"Suppressed: {exc_value}")
            return True         # True = swallow the ValueError, execution continues after the `with`
        return False              # any other exception propagates normally

with SuppressValueError():
    print("before")
    int("not a number")             # raises ValueError
    print("never reached")

print("after the with block")   # this DOES run — exception was suppressed

class DatabaseConnection:
    def __init__(self, dsn):
        self.dsn = dsn
        self.connection = None

    def __enter__(self):
        print(f"Connecting to {self.dsn}")
        self.connection = object()    # placeholder for a real connection
        return self.connection

    def __exit__(self, exc_type, exc_value, traceback):
        print("Closing connection")
        self.connection = None        # cleanup runs even if the block raised
        return False

with DatabaseConnection("postgres://localhost/app") as conn:
    print("Running query")
    # raise RuntimeError("query failed")   # __exit__ STILL runs cleanup, then re-raises

class Multiplier:
    def __init__(self, factor):
        self.factor = factor

    def __call__(self, x):
        return x * self.factor

double = Multiplier(2)
print(double(5))         # 10 — double(...) is sugar for double.__call__(5)
print(callable(double))    # True
print(callable(5))           # False — plain objects aren't callable by default

class CacheKey:
    def __init__(self, params):
        self.params = params      # a dict of parameters

    def __eq__(self, other):
        return self.params == other.params

    def __hash__(self):
        return hash(tuple(sorted(self.params.items())))

cache = {}
key = CacheKey({"user_id": 42, "page": 1})
cache[key] = "cached result"

key.params["page"] = 2      # params mutated after being used as a cache key
print(cache.get(CacheKey({"user_id": 42, "page": 2})))
print(len(cache))