Welcome to The Python Data Model & Protocols! This is the first lesson in our "Python Power Tools: Exploring Advanced Language Features" learning path, and we're excited to begin this journey together as we explore Python's most powerful and elegant features. This learning path consists of five progressive courses that will transform you into an advanced Python practitioner:

1. The Python Data Model & Protocols - Master Python's data model by implementing custom types that integrate seamlessly with Python's core features.
2. Class Machinery: Dataclasses, Descriptors, Metaclasses - Build better classes using dataclasses, descriptors, and metaclasses for reusable, self-validating code.
3. Functional Patterns & Pattern Matching - Write more expressive, declarative Python using functional programming patterns and modern control flow.
4. Concurrency & Async I/O - Unlock concurrent programming in Python, mastering threads, processes, and asyncio for high-performance pipelines.
5. Building an Async CLI Tool for ETL Pipelines in Python - Integrate all advanced Python features to build a complete, production-ready asynchronous ETL tool.

By the end of this path, you'll have the skills to write Python code that's not just functional, but genuinely Pythonic. You'll understand how to make your objects work seamlessly with built-in functions, operators, and language constructs. Most importantly, you'll have built a complete, professional-grade application that showcases these advanced techniques.

Note that we expect you to already be comfortable with Python fundamentals: basic syntax, classes, inheritance, and exception handling. You should understand how to define methods, work with properties, and feel confident reading and writing intermediate Python code. In case you don't feel comfortable with these topics, feel free to check out one of our beginner-level course paths!

Today, we're focusing on dunder semantics and value behavior. We'll learn how to implement the special methods that make custom objects feel like native Python types, starting with a robust class that handles representation, equality, ordering, and hashing correctly.

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.

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.

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.

Our Money class needs to store an amount and a currency, with proper validation for both:

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.

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.

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:

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.

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.

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:

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.

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.

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:

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.

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:

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.

Let's see ordering in action with amounts in the same currency:

The amounts are correctly sorted in ascending order. Now let's see what happens when we try to compare amounts in different currencies:

The comparison raises a clear error, preventing us from accidentally comparing incompatible currency amounts.

We've built a robust Money class that demonstrates the core principles of Python's data model. By implementing the right dunder methods, we've created objects that integrate seamlessly with Python's built-in functions and operators. Our Money instances can be compared, sorted, stored in sets, used as dictionary keys, and displayed meaningfully to both developers and users.

The patterns we've explored here — value semantics through __eq__ and __hash__, meaningful representations through __repr__ and __str__, and constrained ordering through __lt__ — form the foundation of well-behaved Python objects. These same principles apply whether you're building financial types, geometric objects, or any other value-oriented classes.

In the upcoming practice section, you'll apply these concepts hands-on, implementing similar dunder methods for different types and debugging common pitfalls that arise when these methods don't work together correctly. Happy coding!