Dunder Methods and Value Types

Dunder Methods and Value Types | CodeSignal Learn

Introduction

Understanding Python's Data Model

Python's elegance comes from its unified data model, where everything is an object that can participate in the language's core operations. When you write len(my_list) or str(my_object), Python isn't calling special-cased functions. Instead, it's invoking dunder methods (short for "double underscore", also called magic methods) that your objects can implement. These dunder methods are Python's way of asking: "How should this object behave when someone calls len() on it? How should it represent itself as a string? How should it compare to other objects?" By implementing the right dunder methods, we can make our custom classes integrate seamlessly with Python's syntax and built-in functions. The beauty of this system is that it creates a contract. When we implement__eq__, we're promising that our object knows how to test equality. When we implement__str__, we're providing a human-readable representation. This consistency is what makes Python code feel so natural and expressive.

Join the 1M+ learners on CodeSignal

Be a part of our community of 1M+ users who develop and demonstrate their skills on CodeSignal

The Foundation: Value Types and Money

To explore these concepts, we'll build a Money class that represents financial amounts with currency information. Money is an excellent example of a value type: an object whose identity is determined entirely by its data, not by where it lives in memory. Consider two $10 bills. Even though they're physically different objects, we consider them equal because they represent the same value. This is exactly how our Money class should behave: two Money instances with the same amount and currency should be considered equal, even if they're separate objects in memory. Pythonfrom decimal import Decimal, ROUND_HALF_EVEN from functools import total_ordering from typing import Any def _to_decimal(value: Any) -> Decimal: """ Convert common numeric inputs to Decimal safely. Uses str conversion to avoid float binary rounding artifacts. """ if isinstance(value, Decimal): return value if isinstance(value, (int, str, float)): return Decimal(str(value)) raise TypeError(f"Unsupported amount type: {type(value)!r}") This helper function handles the tricky business of converting various numeric types to Decimal objects. We use Decimal for financial calculations because it provides exact decimal arithmetic, avoiding the rounding errors that plague floating-point numbers. Notice how we convert floats to strings first: this prevents binary floating-point approximations from contaminating our precise decimal calculations.

Building the Money Class Structure

Our Money class needs to store an amount and a currency, with proper validation for both: Python class Money: """ An immutable-ish value object representing an amount in a currency. - __repr__/__str__ give dev vs user-friendly displays - __eq__/__lt__ implement currency-aware comparisons - __hash__ allows usage in sets and dict keys (value semantics) """ def __init__(self, amount: Any, currency: str) -> None: cur = str(currency).upper() if len(cur) != 3 or not cur.isalpha(): raise ValueError("Currency must be a 3-letter code like 'USD'") dec = _to_decimal(amount) # Normalize to 2 decimal places (cents) using bankers rounding. q = Decimal("0.01") self._amount = dec.quantize(q, rounding=ROUND_HALF_EVEN) self._currency = cur @property def amount(self) -> Decimal: return self._amount @property def currency(self) -> str: return self._currency The constructor does several important things: it validates that the currency is a three-letter alphabetic code, converts the amount to a Decimal, and normalizes it to exactly two decimal places using banker's rounding. This normalization ensures that Money(10) and Money(10.00) are truly identical, which will be crucial for our equality and hashing implementations.

Object Representation: Developer vs User Views

Every object needs two ways to represent itself as text. The __repr__ method provides an unambiguous, developer-focused representation that ideally could recreate the object. The __str__ method gives a clean, user-friendly display. Python def __repr__(self) -> str: return f"Money(Decimal('{self.amount}'), '{self.currency}')" def __str__(self) -> str: return f"{self.amount} {self.currency}" The __repr__ method shows exactly how to construct an equivalent Money object, complete with the Decimal constructor call. This makes debugging much easier because you can see precisely what data an object contains. The __str__ method provides a clean format suitable for displaying to end users, focusing on readability over technical precision. Let's see these representation methods in action: Pythonm1 = Money("10.00", "usd") print(repr(m1)) # Developer representation print(str(m1)) # User-friendly representation textMoney(Decimal('10.00'), 'USD') 10.00 USD Notice how repr() gives us the full technical details while str() provides a clean, readable format. The currency "usd" was automatically normalized to uppercase "USD" during construction.

Value Equality: The eq Method

For value types like Money, equality should be based on the actual values, not object identity. Two Money objects with the same amount and currency should be equal regardless of when or how they were created. Python def __eq__(self, other: object) -> bool: if not isinstance(other, Money): return NotImplemented return (self.currency, self.amount) == (other.currency, other.amount) This implementation follows Python's best practices for equality comparison. When comparing to non- Money objects, we return NotImplemented rather than False . This allows Python's comparison machinery to try the other object's__eq__method, enabling more sophisticated comparison protocols. For Money objects, we compare both currency and amount as a tuple, ensuring that 10 USD is not equal to 10 EUR. Let's test equality with objects created in different ways: Python m1 = Money("10.00", "usd") m2 = Money(Decimal("10"), "USD") print(m1 == m2) text True Even though m1 was created with a string amount and lowercase currency while m2 used a Decimal and uppercase currency, they're equal because both normalize to the same internal representation: 10.00 USD.

Making Objects Hashable: The hash Method

If objects can be equal, they need consistent hash values to work properly in sets and as dictionary keys. The hash function must guarantee that equal objects have equal hashes, though the reverse isn't required. Python def __hash__(self) -> int: # Hash on canonical "cents" to ensure 10.0 == 10.00 -> same hash cents = int((self.amount * Decimal("100")).to_integral_value()) return hash((self.currency, cents)) We convert the amount to cents (an integer) before hashing to ensure that amounts like 10.00 and 10.0 produce identical hash values, since they're equal after our decimal normalization. We then hash the tuple of currency and cents, creating a robust hash function that respects our equality implementation. Now that our Money objects are hashable, they can be used in sets and as dictionary keys: Pythonm1 = Money("10.00", "usd") m2 = Money(Decimal("10"), "USD") m4 = Money("7.25", "USD") # Money objects can be used in sets s = {m1, m2, m4} print(len(s)) # Money objects can be used as dictionary keys d = {m1: "A", m4: "B"} print(d[m2]) text2 A The set contains only 2 elements because m1 and m2 are equal and have the same hash, so they're deduplicated. Similarly, we can use m2 as a key to look up the value stored under m1 in the dictionary, since they're considered the same key.

Ordering with Rich Comparisons

The @total_ordering decorator is a powerful tool that generates all comparison methods from just __eq__ and one ordering method. We'll implement __lt__ (less than) and get >, <=, and >= automatically: Python@total_ordering class Money: [...] def __lt__(self, other: Any) -> bool: if not isinstance(other, Money): return NotImplemented if self.currency != other.currency: raise TypeError( f"Cannot order amounts in different currencies: " f"{self.currency} vs {other.currency}" ) return self.amount < other.amount This method enforces a crucial business rule: we can only compare money amounts in the same currency. Attempting to compare $10 USD with €8 EUR raises a TypeError with a clear explanation. This prevents subtle bugs where currency differences might be overlooked in financial calculations.

Total Ordering in Action

Let's see ordering in action with amounts in the same currency: Python m1 = Money("10.00", "USD") m4 = Money("7.25", "USD") m5 = Money("12.00", "USD") # Ordering within same currency ordered = sorted([m5, m4, m1]) for x in ordered: print(str(x)) text 7.25 USD 10.00 USD 12.00 USD The amounts are correctly sorted in ascending order. Now let's see what happens when we try to compare amounts in different currencies: Python m1 = Money("10.00", "USD") m3 = Money("9.50", "EUR") try:_ = m1 < m3 except TypeError as e: print(str(e)) text Cannot order amounts in different currencies: USD vs EUR The comparison raises a clear error, preventing us from accidentally comparing incompatible currency amounts.

Dunder Methods and Value Types

Introduction

Understanding Python's Data Model

Join the 1M+ learners on CodeSignal

The Foundation: Value Types and Money

Building the Money Class Structure

Object Representation: Developer vs User Views

Value Equality: The __eq__ Method

Making Objects Hashable: The __hash__ Method

Ordering with Rich Comparisons

Total Ordering in Action

Conclusion and Next Steps

Value Equality: The eq Method

Making Objects Hashable: The hash Method