examples.01_value_equality_and_hash

 1"""Demonstrates how equality and hashing work between instances of the same
 2`Value` subclass, and how they behave in sets and dictionaries.
 3
 4This example shows:
 5  * Two `Value` objects with the same underlying data are equal (`==`) and
 6    share the same hash.
 7  * Distinct values are not equal and yield different hashes.
 8  * How Python collections (sets, dicts) handle these objects.
 9  * Two `Value` instances with the same wrapped data are considered equal,
10  * so only one is kept in sets or dicts. In a dictionary, inserting a second
11  * equal key replaces the existing entry.
12  * How subclassing `Value` with different type parameters affects equality.
13
14Run directly:
15
16    python examples/01_value_equality_and_hash.py
17
18Expected output:
19
20    a == b: True
21    a == c: False
22    hash(a) == hash(b): True
23    set size (should be 2): 2
24    dict size (should be 2): 2
25    dict[a] = second
26    IntValue(5) == StrValue('5'): False
27"""
28
29import sys
30import pathlib
31
32# ---------------------------------------------------------------------------
33# Make the repo root importable when running this file directly
34# ---------------------------------------------------------------------------
35sys.path.insert(0, str(pathlib.Path(__file__).resolve().parents[1]))
36
37from constrained_values import Value
38
39
40def main() -> None:
41    """Run the equality and hashing demonstration.
42
43    This function creates several instances of :class:`Value` and its subclasses
44    to show how equality (`__eq__`) and hashing (`__hash__`) interact with
45    Python collections.
46
47    Examples:
48        >>> a = Value(10)
49        >>> b = Value(10)
50        >>> a == b
51        True
52        >>> hash(a) == hash(b)
53        True
54
55    Prints:
56        Results of equality and hashing comparisons, and the sizes of a set
57        and dict containing Value instances.
58    """
59    a = Value(10)
60    b = Value(10)
61    c = Value(20)
62
63    print("a == b:", a == b)
64    print("a == c:", a == c)
65    print("hash(a) == hash(b):", hash(a) == hash(b))
66
67    s = {a, b, c}
68    print("set size (should be 2):", len(s))
69
70    d = {a: "first", b: "second", c: "third"}
71    print("dict size (should be 2):", len(d))
72    print("dict[a] =", d[a])
73
74    class IntValue(Value[int]):
75        """A Value subclass specialized for integers.
76
77        Demonstrates how subclassing `Value` allows type-specific variants that
78        still participate in equality and hashing based on contained data.
79        """
80        pass
81
82    class StrValue(Value[str]):
83        """A Value subclass specialized for strings."""
84        pass
85
86    print("IntValue(5) == StrValue('5'):", IntValue(5) == StrValue("5"))
87
88
89if __name__ == "__main__":
90    main()