Materials for Python 3.15 Preview: frozendict (#812)

* Materials for Python 3.15 Preview: frozendict

* Ignore syntax specific to Python 3.15

* Show amount in dedupe output and correct the 1003 explanation

The docstring said orders 1002 and 1003 both survive twice because their
fetched_at timestamps differ. That only holds for 1002. The 1003 rows also
disagree on amount (42.00 vs 99.00), so ignoring fetched_at merges 1002 but
leaves 1003 split, which is what the script already prints.

The output omitted the amount column, so the field that explains the result
was the one field readers couldn't see. Matches the tutorial's output block.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>

* Fix formatting in pyproject.toml

---------

Co-authored-by: Claude Opus 5 (1M context) <noreply@anthropic.com>

Author: bzaczynski

pyproject.toml

@@ -7,8 +7,9 @@ exclude = [
     "migrations",
     "how-to-indent-in-python/sample_code.py",
     "agents-md/run1_main.py",
-    "ai-benchmark",
-    "python315-lazy-imports"
+    "python315-frozendict/",
+    "python315-lazy-imports",
+    "ai-benchmark"
 ]
 
 [tool.ruff.lint]

python315-frozendict/README.md

@@ -0,0 +1,3 @@
+# Python 3.15 Preview: `frozendict`
+
+Supporting code for the Real Python tutorial [Python 3.15 Preview: `frozendict`](https://realpython.com/python315-frozendict/).

python315-frozendict/cache.py

@@ -0,0 +1,12 @@
+from functools import cache
+
+
+@cache
+def render_report(options):
+    print(f"computing report for {options}")
+    return f"<report {sorted(options.items())}>"
+
+
+print(render_report(frozendict(theme="dark", rows=50)))
+print(render_report(frozendict(rows=50, theme="dark")))
+print(render_report.cache_info())

python315-frozendict/const.py

@@ -0,0 +1,7 @@
+ROLE_PERMISSIONS = frozendict(
+    viewer=frozenset({"read"}),
+    editor=frozenset({"read", "write"}),
+    admin=frozenset({"read", "write", "delete", "manage_users"}),
+)
+
+print(ROLE_PERMISSIONS)

python315-frozendict/dedupe_csv.py

@@ -0,0 +1,54 @@
+"""Collapse duplicate CSV rows by putting them in a set of frozendicts.
+
+Each row that csv.DictReader yields is a dict, which is unhashable and so can't
+go in a set. Freezing each row makes the whole deduplication one expression.
+
+Watch orders 1002 and 1003: they survive as two entries each, but for different
+reasons. The 1002 rows differ only in fetched_at, while the 1003 rows also
+differ in amount. Ignoring fetched_at therefore merges 1002 and leaves 1003
+split. That's a lesson about picking the fields that define identity, not a
+bug.
+
+Run with Python 3.15 or later:
+
+    python dedupe_csv.py
+"""
+
+import csv
+import io
+from operator import itemgetter
+
+ORDERS = """\
+order_id,customer,amount,fetched_at
+1001,Ada,250.00,2026-08-13T09:00:00
+1002,Grace,80.50,2026-08-13T09:00:00
+1001,Ada,250.00,2026-08-13T09:00:00
+1003,Linus,42.00,2026-08-13T09:00:00
+1002,Grace,80.50,2026-08-13T09:05:00
+1003,Linus,99.00,2026-08-13T09:05:00
+"""
+
+
+def main():
+    rows = list(csv.DictReader(io.StringIO(ORDERS)))
+    unique_rows = {frozendict(row) for row in rows}
+
+    print(
+        f"Read {len(rows)} rows, kept {len(unique_rows)} after deduplication."
+    )
+    for row in sorted(unique_rows, key=itemgetter("order_id", "fetched_at")):
+        print(
+            f"  {row['order_id']} {row['customer']:<6} "
+            f"{row['amount']:>7} {row['fetched_at']}"
+        )
+
+    identity = itemgetter("order_id", "customer", "amount")
+    by_order = {
+        frozendict(zip(("order_id", "customer", "amount"), identity(row)))
+        for row in rows
+    }
+    print(f"Ignoring fetched_at leaves {len(by_order)} orders.")
+
+
+if __name__ == "__main__":
+    main()

python315-frozendict/events.py

@@ -0,0 +1,21 @@
+from collections import Counter
+
+stats = Counter()
+
+
+def record_event(**labels):
+    stats[frozendict(labels)] += 1
+
+
+record_event(endpoint="/login", outcome="failure", reason="bad_password")
+record_event(reason="bad_password", endpoint="/login", outcome="failure")
+record_event(endpoint="/login", outcome="success")
+record_event(outcome="success", endpoint="/checkout")
+
+num_failures = sum(
+    count
+    for labels, count in stats.items()
+    if labels.get("outcome") == "failure"
+)
+
+print("Number of failed outcomes:", num_failures)

python315-frozendict/exposure.py

@@ -0,0 +1,14 @@
+from decimal import Decimal
+
+
+class BankAccount:
+    def __init__(self):
+        self._balances = {"USD": Decimal("0"), "EUR": Decimal("0")}
+
+    @property
+    def balances(self):
+        return frozendict(self._balances)
+
+
+account = BankAccount()
+account.balances["USD"] = Decimal("1_000_000")

python315-frozendict/memoize.py

@@ -0,0 +1,39 @@
+"""Cache a function that takes a mapping argument.
+
+A plain dict is unhashable, so @cache rejects it. A frozendict hashes, so the
+same call signature becomes cacheable.
+
+Run with Python 3.15 or later:
+
+    python memoize.py
+"""
+
+from functools import cache
+
+
+@cache
+def render_report(options):
+    print(f"computing report for {options}")
+    return f"<report {sorted(options.items())}>"
+
+
+def main():
+    settings = frozendict(theme="dark", rows=50)
+
+    print("First call, nothing cached yet:")
+    render_report(settings)
+
+    print("Second call with an equal frozendict:")
+    render_report(frozendict(rows=50, theme="dark"))
+
+    print(f"Cache statistics: {render_report.cache_info()}")
+
+    print("The same call with a plain dict:")
+    try:
+        render_report({"theme": "dark", "rows": 50})
+    except TypeError as error:
+        print(f"  TypeError: {error}")
+
+
+if __name__ == "__main__":
+    main()

python315-frozendict/planets.py

@@ -0,0 +1,16 @@
+planets = frozendict(
+    {
+        "Mercury": 57_910_000,
+        "Venus": 108_200_000,
+        "Earth": 149_600_000,
+        "Mars": 227_900_000,
+        "Jupiter": 778_500_000,
+        "Saturn": 1_434_000_000,
+        "Uranus": 2_871_000_000,
+        "Neptune": 4_495_000_000,
+    }
+)
+
+for name, distance in planets.items():
+    scaled = round(60 * distance / max(planets.values()))
+    print(" " * scaled + "\N{RINGED PLANET}", name)

python315-frozendict/safe_defaults.py

@@ -0,0 +1,41 @@
+"""Show the mutable default argument bug, then fix it with a frozendict.
+
+The buggy version keeps one dict alive across every call, so an auth token
+supplied to one host leaks into an unrelated request. The frozendict version
+builds a fresh mapping each time.
+
+Run with Python 3.15 or later:
+
+    python safe_defaults.py
+"""
+
+
+def fetch_buggy(url, headers={}, token=None):
+    headers.setdefault("User-Agent", "acme/1.0")
+    if token:
+        headers["Authorization"] = f"Bearer {token}"
+    print(f"GET {url}")
+    print(f"    {headers}")
+
+
+def fetch(url, headers=frozendict(), token=None):
+    headers = frozendict({"User-Agent": "acme/1.0"}) | headers
+    if token:
+        headers |= {"Authorization": f"Bearer {token}"}
+    print(f"GET {url}")
+    print(f"    {headers}")
+
+
+def main():
+    print("With a mutable default argument:")
+    fetch_buggy("https://acme.test/me", token="admin-key")
+    fetch_buggy("https://partner.example/ping")
+
+    print()
+    print("With a frozendict default argument:")
+    fetch("https://acme.test/me", token="admin-key")
+    fetch("https://partner.example/ping")
+
+
+if __name__ == "__main__":
+    main()