Python's Data Model: Dunder Methods & Operator Overloading

# The simplest demonstration: what Python actually does behind the scenes
class Reveal:
    """A class that prints every dunder call it receives."""

    def __len__(self):
        print("  __len__ was called")
        return 42

    def __getitem__(self, key):
        print(f"  __getitem__ was called with key={key!r}")
        return f"item_{key}"

    def __add__(self, other):
        print(f"  __add__ was called with other={other!r}")
        return "addition result"

    def __str__(self):
        print("  __str__ was called")
        return "I am a Reveal object"


r = Reveal()

print("--- len(r) ---")
result = len(r)           # calls r.__len__()
print(f"result: {result}")

print("\n--- r[5] ---")
item = r[5]               # calls r.__getitem__(5)
print(f"result: {item!r}")

print("\n--- r + 99 ---")
total = r + 99            # calls r.__add__(99)
print(f"result: {total!r}")

print("\n--- str(r) ---")
s = str(r)                # calls r.__str__()
print(f"result: {s!r}")

class Vector:
    """An immutable 2D mathematical vector."""

    def __init__(self, x: float, y: float) -> None:
        self.x = x
        self.y = y

    def __repr__(self) -> str:
        # Should look like valid Python that recreates the object
        return f"Vector({self.x!r}, {self.y!r})"

    def __str__(self) -> str:
        # Human-friendly: show magnitude and direction hint
        magnitude = (self.x ** 2 + self.y ** 2) ** 0.5
        return f"<Vector ({self.x}, {self.y}), |v|={magnitude:.2f}>"


v = Vector(3, 4)

# In a container -- Python uses __repr__ for items inside lists/dicts
print([v])
# [Vector(3, 4)]

# Direct print -- Python uses __str__
print(v)
# <Vector (3, 4), |v|=5.00>

# REPL / repr() call -- uses __repr__
print(repr(v))
# Vector(3, 4)

# f-string without !r -- uses __str__
print(f"My vector: {v}")
# My vector: <Vector (3, 4), |v|=5.00>

# f-string with !r -- uses __repr__
print(f"Debug: {v!r}")
# Debug: Vector(3, 4)

from functools import total_ordering

@total_ordering
class Temperature:
    """A physical temperature with unit conversion."""

    ABSOLUTE_ZERO_C = -273.15

    def __init__(self, celsius: float) -> None:
        if celsius < self.ABSOLUTE_ZERO_C:
            raise ValueError(f"Temperature below absolute zero: {celsius}°C")
        self.celsius = celsius

    @property
    def fahrenheit(self) -> float:
        return self.celsius * 9 / 5 + 32

    @property
    def kelvin(self) -> float:
        return self.celsius - self.ABSOLUTE_ZERO_C

    def __repr__(self) -> str:
        return f"Temperature({self.celsius!r})"

    def __str__(self) -> str:
        return f"{self.celsius:.1f}°C ({self.fahrenheit:.1f}°F)"

    def __eq__(self, other: object) -> bool:
        if not isinstance(other, Temperature):
            return NotImplemented
        return self.celsius == other.celsius

    def __lt__(self, other: "Temperature") -> bool:
        if not isinstance(other, Temperature):
            return NotImplemented
        return self.celsius < other.celsius

    # total_ordering provides __le__, __gt__, __ge__ for free!


# Test comparisons
boiling = Temperature(100)
freezing = Temperature(0)
body = Temperature(37)

print(boiling > freezing)     # True  (from __gt__, derived by total_ordering)
print(freezing < body)        # True  (from __lt__, defined directly)
print(boiling == Temperature(100))  # True

# Works with sorted() and min()/max() because ordering is defined
temps = [boiling, freezing, body, Temperature(-40)]
print(sorted(temps))          # [Temperature(-40), Temperature(0), Temperature(37), Temperature(100)]
print(f"Coldest: {min(temps)}")   # -40.0°C (-40.0°F)
print(f"Hottest: {max(temps)}")   # 100.0°C (212.0°F)

import math

class Vector:
    """A 2D vector supporting full arithmetic."""

    def __init__(self, x: float, y: float) -> None:
        self.x = x
        self.y = y

    def __repr__(self) -> str:
        return f"Vector({self.x!r}, {self.y!r})"

    # --- Arithmetic ---

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

    def __sub__(self, other: "Vector") -> "Vector":
        if not isinstance(other, Vector):
            return NotImplemented
        return Vector(self.x - other.x, self.y - other.y)

    def __mul__(self, scalar: float) -> "Vector":
        """Vector * scalar."""
        if not isinstance(scalar, (int, float)):
            return NotImplemented
        return Vector(self.x * scalar, self.y * scalar)

    def __rmul__(self, scalar: float) -> "Vector":
        """scalar * Vector -- delegates to __mul__ since multiplication is commutative."""
        return self.__mul__(scalar)

    def __truediv__(self, scalar: float) -> "Vector":
        if scalar == 0:
            raise ZeroDivisionError("Cannot divide a vector by zero")
        return Vector(self.x / scalar, self.y / scalar)

    def __neg__(self) -> "Vector":
        """Unary negation: -v."""
        return Vector(-self.x, -self.y)

    def __abs__(self) -> float:
        """abs(v) returns the Euclidean magnitude."""
        return math.sqrt(self.x ** 2 + self.y ** 2)

    def __iadd__(self, other: "Vector") -> "Vector":
        """In-place addition: v += other. Avoids creating a new object."""
        if not isinstance(other, Vector):
            return NotImplemented
        self.x += other.x
        self.y += other.y
        return self  # must return self for in-place ops


# Test all arithmetic operations
v1 = Vector(3, 4)
v2 = Vector(1, 2)

print(v1 + v2)       # Vector(4, 6)
print(v1 - v2)       # Vector(2, 2)
print(v1 * 3)        # Vector(9, 12)    -- __mul__
print(3 * v1)        # Vector(9, 12)    -- __rmul__
print(v1 / 2)        # Vector(1.5, 2.0)
print(-v1)           # Vector(-3, -4)   -- __neg__
print(abs(v1))       # 5.0              -- __abs__

# In-place: modifies v2 instead of creating a new object
v2 += Vector(10, 10)
print(v2)            # Vector(11, 12)

class Matrix:
    """A 2D matrix with full container protocol support."""

    def __init__(self, rows: list[list[float]]) -> None:
        if not rows:
            raise ValueError("Matrix must have at least one row")
        ncols = len(rows[0])
        if any(len(row) != ncols for row in rows):
            raise ValueError("All rows must have the same number of columns")
        # Store as a flat list for efficiency
        self._rows = len(rows)
        self._cols = ncols
        self._data = [cell for row in rows for cell in row]

    def __repr__(self) -> str:
        rows = [
            [self._data[r * self._cols + c] for c in range(self._cols)]
            for r in range(self._rows)
        ]
        return f"Matrix({rows!r})"

    def __len__(self) -> int:
        """len(m) returns the number of rows."""
        return self._rows

    def __getitem__(self, key: int) -> list[float]:
        """m[row] returns the row as a list; supports m[row][col]."""
        if key < 0 or key >= self._rows:
            raise IndexError(f"Row index {key} out of range [0, {self._rows})")
        start = key * self._cols
        return self._data[start : start + self._cols]

    def __setitem__(self, key: int, value: list[float]) -> None:
        """m[row] = new_row — replace an entire row."""
        if len(value) != self._cols:
            raise ValueError(f"Expected {self._cols} values, got {len(value)}")
        start = key * self._cols
        self._data[start : start + self._cols] = value

    def __contains__(self, item: float) -> bool:
        """item in m — check if any cell equals item."""
        return item in self._data

    def __iter__(self):
        """for row in m — yields rows one at a time."""
        for r in range(self._rows):
            yield self[r]


m = Matrix([[1, 2, 3], [4, 5, 6], [7, 8, 9]])

print(f"Rows: {len(m)}")      # 3
print(f"Row 0: {m[0]}")       # [1, 2, 3]
print(f"Cell [1][2]: {m[1][2]}")  # 6

print(f"5 in m: {5 in m}")    # True
print(f"99 in m: {99 in m}")  # False

# Iteration works because __iter__ is defined
for row in m:
    print(row)
# [1, 2, 3]
# [4, 5, 6]
# [7, 8, 9]

# Mutate a row
m[0] = [10, 20, 30]
print(m[0])  # [10, 20, 30]

class CountDown:
    """An iterable that counts down from n to 1."""

    def __init__(self, start: int) -> None:
        self.start = start

    def __iter__(self) -> "CountDownIterator":
        """Return a fresh iterator each time iteration starts."""
        return CountDownIterator(self.start)

    def __repr__(self) -> str:
        return f"CountDown({self.start!r})"


class CountDownIterator:
    """The actual iterator that tracks state."""

    def __init__(self, current: int) -> None:
        self.current = current

    def __iter__(self) -> "CountDownIterator":
        """Iterators must also implement __iter__ -- they return themselves."""
        return self

    def __next__(self) -> int:
        if self.current <= 0:
            raise StopIteration  # signal that we are done
        value = self.current
        self.current -= 1
        return value


# For loop: Python calls iter(cd) -> CountDownIterator, then next() repeatedly
cd = CountDown(5)
for n in cd:
    print(n, end=" ")
print()
# 5 4 3 2 1

# You can iterate again because __iter__ creates a fresh iterator each time
print(list(cd))   # [5, 4, 3, 2, 1]

# Manual stepping
it = iter(cd)
print(next(it))   # 5
print(next(it))   # 4

class FibSequence:
    """Yields the first n Fibonacci numbers. Iterable + iterator in one class."""

    def __init__(self, n: int) -> None:
        self.n = n
        self._count = 0
        self._a = 0
        self._b = 1

    def __iter__(self) -> "FibSequence":
        self._count = 0
        self._a, self._b = 0, 1
        return self

    def __next__(self) -> int:
        if self._count >= self.n:
            raise StopIteration
        value = self._a
        self._a, self._b = self._b, self._a + self._b
        self._count += 1
        return value


for fib in FibSequence(8):
    print(fib, end=" ")
# 0 1 1 2 3 5 8 13

class Multiplier:
    """A callable object that multiplies its input by a fixed factor."""

    def __init__(self, factor: float) -> None:
        self.factor = factor
        self._call_count = 0

    def __call__(self, value: float) -> float:
        self._call_count += 1
        return value * self.factor

    def __repr__(self) -> str:
        return f"Multiplier(factor={self.factor!r}, calls={self._call_count})"


# Create specialized "functions" with baked-in configuration
double = Multiplier(2)
triple = Multiplier(3)
scale_down = Multiplier(0.1)

print(double(5))        # 10.0
print(triple(7))        # 21.0
print(scale_down(100))  # 10.0

# State is preserved between calls
double(10)
double(20)
print(repr(double))  # Multiplier(factor=2, calls=3)

# Works wherever functions are accepted (map, filter, sorted key, etc.)
data = [1, 2, 3, 4, 5]
print(list(map(double, data)))   # [2, 4, 6, 8, 10]

class SimpleLinearLayer:
    """A stripped-down version of PyTorch's nn.Linear logic."""

    def __init__(self, in_features: int, out_features: int) -> None:
        self.in_features = in_features
        self.out_features = out_features
        # Weights initialized to small values (in real PyTorch, Kaiming init)
        self.weight = [[0.1 * (i + j) for j in range(in_features)]
                       for i in range(out_features)]
        self.bias = [0.0] * out_features

    def __call__(self, x: list[float]) -> list[float]:
        """Forward pass: output = weight @ x + bias."""
        output = []
        for i in range(self.out_features):
            total = sum(self.weight[i][j] * x[j] for j in range(self.in_features))
            output.append(total + self.bias[i])
        return output

    def __repr__(self) -> str:
        return f"SimpleLinearLayer(in={self.in_features}, out={self.out_features})"


layer = SimpleLinearLayer(3, 2)
x = [1.0, 2.0, 3.0]
print(layer(x))  # Callable just like a function!

import time

class Timer:
    """A context manager for timing code blocks."""

    def __enter__(self) -> "Timer":
        """Called at the start of the with block. Return value binds to 'as' clause."""
        self._start = time.perf_counter()
        return self  # bound to `t` in `with Timer() as t:`

    def __exit__(self, exc_type, exc_val, exc_tb) -> bool:
        """Called when the with block ends -- exception or not.

        exc_type/exc_val/exc_tb are None if no exception occurred.
        Return True to suppress the exception; False/None to re-raise it.
        """
        self.elapsed = time.perf_counter() - self._start
        print(f"Elapsed: {self.elapsed:.6f}s")
        return False  # do not suppress exceptions

    @property
    def elapsed_ms(self) -> float:
        return self.elapsed * 1000


with Timer() as t:
    total = sum(range(1_000_000))
print(f"Sum: {total}, took {t.elapsed_ms:.2f}ms")

class ManagedResource:
    """Simulated database connection that guarantees cleanup."""

    def __init__(self, name: str) -> None:
        self.name = name
        self._connected = False
        self._queries: list[str] = []

    def __enter__(self) -> "ManagedResource":
        print(f"[CONNECT] Opening connection to '{self.name}'")
        self._connected = True
        return self

    def __exit__(self, exc_type, exc_val, exc_tb) -> bool:
        print(f"[CLOSE] Closing connection to '{self.name}' "
              f"(ran {len(self._queries)} queries)")
        self._connected = False
        if exc_type is not None:
            print(f"[ERROR] Exception during session: {exc_val}")
        return False  # propagate any exception

    def query(self, sql: str) -> list[dict]:
        if not self._connected:
            raise RuntimeError("Cannot query: not connected")
        self._queries.append(sql)
        print(f"  [QUERY] {sql}")
        return [{"id": 1}, {"id": 2}]


# Safe usage -- __exit__ is called no matter what
with ManagedResource("ml_training.db") as db:
    rows = db.query("SELECT * FROM samples LIMIT 100")
    print(f"  Got {len(rows)} rows")
# [CONNECT] Opening connection to 'ml_training.db'
#   [QUERY] SELECT * FROM samples LIMIT 100
#   Got 2 rows
# [CLOSE] Closing connection to 'ml_training.db' (ran 1 queries)

class LoggedObject:
    """An object that logs every attribute write."""

    def __setattr__(self, name: str, value: object) -> None:
        """Called on EVERY self.x = value, including inside __init__."""
        print(f"  [SETATTR] {name} = {value!r}")
        # MUST call super().__setattr__ -- otherwise the value never gets stored!
        super().__setattr__(name, value)

    def __getattr__(self, name: str) -> str:
        """Called ONLY when normal attribute lookup fails (name not in __dict__)."""
        print(f"  [GETATTR] {name!r} not found, returning default")
        return f"<missing:{name}>"


obj = LoggedObject()
obj.x = 10         # [SETATTR] x = 10
obj.label = "hi"   # [SETATTR] label = 'hi'
print(obj.x)       # 10  (normal lookup, __getattr__ NOT called)
print(obj.missing) # [GETATTR] 'missing' not found, returning default -> <missing:missing>

class LazyModel:
    """Loads a large model only when first accessed."""

    def __init__(self, path: str) -> None:
        self._path = path
        self._model = None  # not loaded yet

    def __getattr__(self, name: str):
        """Called only when attribute is not found via normal lookup."""
        if name == "model":
            print(f"  [LAZY] Loading model from {self._path}...")
            self._model = {"weights": [0.1, 0.2, 0.3]}  # simulate loading
            return self._model
        raise AttributeError(f"{type(self).__name__!r} has no attribute {name!r}")

    @property
    def is_loaded(self) -> bool:
        return self._model is not None


m = LazyModel("/models/bert.pt")
print(m.is_loaded)   # False -- model not loaded yet
print(m.model)       # [LAZY] Loading model... -> {'weights': [...]}
print(m.is_loaded)   # True

import math
from functools import total_ordering
from typing import Iterator

@total_ordering
class Matrix2x2:
    """A 2x2 matrix supporting arithmetic, indexing, comparison, iteration, and calling."""

    def __init__(self, a: float, b: float, c: float, d: float) -> None:
        """[[a, b], [c, d]]"""
        self._data = [float(a), float(b), float(c), float(d)]

    # --- String representations ---
    def __repr__(self) -> str:
        return f"Matrix2x2({self._data[0]}, {self._data[1]}, {self._data[2]}, {self._data[3]})"

    def __str__(self) -> str:
        return (f"[[{self._data[0]:.2f}, {self._data[1]:.2f}]\n"
                f" [{self._data[2]:.2f}, {self._data[3]:.2f}]]")

    # --- Container protocol ---
    def __len__(self) -> int:
        return 2  # two rows

    def __getitem__(self, row: int) -> list[float]:
        if row not in (0, 1):
            raise IndexError(f"Row index {row} out of range for 2x2 matrix")
        return self._data[row * 2 : row * 2 + 2]

    def __iter__(self) -> Iterator[list[float]]:
        yield self._data[:2]
        yield self._data[2:]

    # --- Comparison ---
    def __eq__(self, other: object) -> bool:
        if not isinstance(other, Matrix2x2):
            return NotImplemented
        return self._data == other._data

    def __lt__(self, other: "Matrix2x2") -> bool:
        """Order by determinant (useful for ranking transformations)."""
        if not isinstance(other, Matrix2x2):
            return NotImplemented
        return self.det() < other.det()

    def __hash__(self) -> int:
        return hash(tuple(self._data))

    # --- Arithmetic ---
    def __add__(self, other: "Matrix2x2") -> "Matrix2x2":
        if not isinstance(other, Matrix2x2):
            return NotImplemented
        return Matrix2x2(*(a + b for a, b in zip(self._data, other._data)))

    def __sub__(self, other: "Matrix2x2") -> "Matrix2x2":
        if not isinstance(other, Matrix2x2):
            return NotImplemented
        return Matrix2x2(*(a - b for a, b in zip(self._data, other._data)))

    def __mul__(self, other):
        """Matrix * scalar or Matrix @ Matrix (matrix product)."""
        if isinstance(other, (int, float)):
            return Matrix2x2(*(v * other for v in self._data))
        if isinstance(other, Matrix2x2):
            a, b, c, d = self._data
            e, f, g, h = other._data
            return Matrix2x2(a*e + b*g, a*f + b*h, c*e + d*g, c*f + d*h)
        return NotImplemented

    def __rmul__(self, scalar: float) -> "Matrix2x2":
        return self.__mul__(scalar)

    # --- Callable: apply matrix to a 2D vector ---
    def __call__(self, vec: list[float]) -> list[float]:
        """Apply this matrix as a linear transformation to a 2D vector."""
        if len(vec) != 2:
            raise ValueError("Matrix2x2 can only transform 2D vectors")
        a, b, c, d = self._data
        return [a * vec[0] + b * vec[1], c * vec[0] + d * vec[1]]

    # --- Helper methods ---
    def det(self) -> float:
        """Compute the determinant: ad - bc."""
        a, b, c, d = self._data
        return a * d - b * c

    def trace(self) -> float:
        """Sum of diagonal elements."""
        return self._data[0] + self._data[3]


# -- Demo --
I = Matrix2x2(1, 0, 0, 1)   # identity
R90 = Matrix2x2(0, -1, 1, 0) # 90° rotation
S2 = Matrix2x2(2, 0, 0, 2)   # scale by 2

print("Identity matrix:")
print(I)
print()

print(f"Rotation matrix det: {R90.det():.1f}")  # 1.0 (rotation preserves area)
print(f"Scale matrix det: {S2.det():.1f}")       # 4.0 (area scales by 4)

# Arithmetic
print("\nI + S2:")
print(I + S2)

print("\n3 * R90:")
print(3 * R90)

# Apply as a linear transformation (callable!)
point = [1.0, 0.0]
rotated = R90(point)
print(f"\nRotate {point} by 90°: {rotated}")  # [0.0, 1.0]

# Indexing and iteration
print(f"\nFirst row: {R90[0]}")   # [0, -1]
print("All rows:")
for row in R90:
    print(f"  {row}")

# Comparison (by determinant)
matrices = [S2, I, R90, Matrix2x2(3, 1, 1, 3)]
print(f"\nSorted by determinant: {sorted(matrices)}")