Index
Contents
Chapter 35 · Solutions

Flyweight: Solutions

1. Door and tree kinds, plus walkable_neighbors()

Add door (+, walkable) and tree (T, not walkable) kinds to tile_map.py. Extend Symbol and SPECS to match, then write walkable_neighbors(field, row, col) returning the count of adjacent walkable cells. Confirm the tile pool size still equals the number of kinds on a map of any size.

Where to look

Typing the Symbol Set shows Symbol and SPECS naming the same kinds, so the two grow together. Add the new symbols to Symbol and SPECS, leaving tile() alone. For walkable_neighbors(), visit each of the four adjacent positions that lies inside the grid, and count the cells whose walkable is true.

The shape
# The shape of exercise_1.py
from functools import cache
from typing import Final, Literal
from record import record

type Symbol = Literal[".", "~", "#", "+", "T"]
type TileSpec = tuple[str, bool]

@record
class Tile:
    symbol: Symbol
    name: str
    walkable: bool

    def label(self, row: int, col: int) -> str:
        ...

SPECS: Final[dict[Symbol, TileSpec]] = {
    ".": ("grass", True),
    "~": ("water", False),
    "#": ("rock", False),
    "+": ("door", True),
    "T": ("tree", False),
}

@cache
def tile(symbol: Symbol) -> Tile:
    ...

def to_symbol(char: str) -> Symbol:
    ...

def parse_map(text: str) -> list[list[Tile]]:
    ...

def walkable_neighbors(
    field: list[list[Tile]], row: int, col: int
) -> int:
    ...
Done when

uv run ty check passes on your file (it reports invalid-assignment on SPECS while Symbol lags behind), a map using all five kinds prints five distinct tile objects at any cell count, and on an all-grass 3x3 map walkable_neighbors() returns 2 at a corner, 3 on an edge, and 4 in the center.

Solution

If you add "+" and "T" to SPECS but leave Symbol listing three kinds, the script still runs and prints 24 5. ty rejects the SPECS annotation with an invalid-assignment error, because the dictionary now holds two keys outside Symbol. The solution adds both symbols to the Symbol literal, so the two tables name the same five kinds.

# exercise_1.py
from functools import cache
from typing import Final, Literal
from record import record

type Symbol = Literal[".", "~", "#", "+", "T"]
type TileSpec = tuple[str, bool]

@record
class Tile:
    symbol: Symbol
    name: str
    walkable: bool

    def label(self, row: int, col: int) -> str:
        return f"{self.name} at ({row}, {col})"

SPECS: Final[dict[Symbol, TileSpec]] = {
    ".": ("grass", True),
    "~": ("water", False),
    "#": ("rock", False),
    "+": ("door", True),
    "T": ("tree", False),
}

@cache
def tile(symbol: Symbol) -> Tile:
    name, walkable = SPECS[symbol]
    return Tile(symbol, name, walkable)

def to_symbol(char: str) -> Symbol:
    if char not in SPECS:
        raise KeyError(char)
    return char

def parse_map(text: str) -> list[list[Tile]]:
    return [[tile(to_symbol(char)) for char in line]
            for line in text.split()]

def walkable_neighbors(
    field: list[list[Tile]], row: int, col: int
) -> int:
    count = 0
    for dr, dc in [(-1, 0), (1, 0), (0, -1), (0, 1)]:
        r, c = row + dr, col + dc
        if 0 <= r < len(field) and 0 <= c < len(field[r]):
            if field[r][c].walkable:
                count += 1
    return count

field = parse_map("""
    ..~~+.
    ..~~T#
    ......
    ##..~~
""")
cells = [*row for row in field]
print(len(cells), len({id(t) for t in cells}))
#: 24 5
grass = parse_map("...\n...\n...")
print(walkable_neighbors(grass, 0, 0),
      walkable_neighbors(grass, 0, 1),
      walkable_neighbors(grass, 1, 1))
#: 2 3 4

Name each new kind in both tables. Once both tables name the same kinds, SPECS passes the type checker, which still flags any key outside Symbol. tile() and parse_map() stay as they are.

Confirm one tile per kind. The twenty-four cells refer to five distinct objects, one per kind (grass, water, rock, door, tree). The count stays at five as the map grows, because @cache keys on the symbol alone.

Count the neighbors inside the grid. The bounds test in walkable_neighbors() passes over the positions that fall off the map, so on the all-grass 3x3 map a corner cell counts two neighbors, an edge cell three, and the center four.

Before you move on, name what separates your attempt from this one: a different design, a detail, or an equivalent alternative.

2. tracemalloc, shared vs. unshared tiles

Use tracemalloc to measure the memory parse_map() uses on a large map, first with every cell sharing its Tile, then with @cache removed from tile() so each cell gets a new one. How does the ratio change as the map grows?

Where to look

Intrinsic and Extrinsic State compares a map that shares its tiles with one that builds a tile per cell. Write two factories, one with @cache and one without, and build the same map with each between tracemalloc.start() and tracemalloc.get_traced_memory(). Repeat for several map sizes and compare the peaks as a ratio.

The shape
# The shape of exercise_2.py
import tracemalloc
from functools import cache
from typing import Final, Literal
from record import record

type Symbol = Literal[".", "~", "#"]
type TileSpec = tuple[str, bool]

@record
class Tile:
    symbol: Symbol
    name: str
    walkable: bool

SPECS: Final[dict[Symbol, TileSpec]] = {
    ".": ("grass", True),
    "~": ("water", False),
    "#": ("rock", False),
}

@cache
def shared_tile(symbol: Symbol) -> Tile:
    ...

def unshared_tile(symbol: Symbol) -> Tile:
    ...

def to_symbol(char: str) -> Symbol:
    ...

def make_map(size: int) -> str:
    ...
Done when

your file prints one unshared-to-shared peak ratio per map size, and with the record Tile each ratio falls between about six and seven (the solution prints 6.2 at 50x50 and 100x100, and 6.9 at 200x200). If the unshared peak also counts the shared field, each ratio rises by 0.7 to 0.9 (6.9, 7.0, and 7.8 in one run), so compare your ratios with the solution’s size by size.

Solution

If you leave out the tracemalloc.stop() after the shared build, tracing runs straight through both builds. The unshared peak then counts the shared field, which is still alive, on top of its own, so the ratio comes out larger at every size. The solution stops tracing after each build, so each peak measures that build’s allocations alone.

# exercise_2.py
import tracemalloc
from functools import cache
from typing import Final, Literal
from record import record

type Symbol = Literal[".", "~", "#"]
type TileSpec = tuple[str, bool]

@record
class Tile:
    symbol: Symbol
    name: str
    walkable: bool

SPECS: Final[dict[Symbol, TileSpec]] = {
    ".": ("grass", True),
    "~": ("water", False),
    "#": ("rock", False),
}

@cache
def shared_tile(symbol: Symbol) -> Tile:
    name, walkable = SPECS[symbol]
    return Tile(symbol, name, walkable)

def unshared_tile(symbol: Symbol) -> Tile:
    name, walkable = SPECS[symbol]
    return Tile(symbol, name, walkable)

def to_symbol(char: str) -> Symbol:
    if char not in SPECS:
        raise KeyError(char)
    return char

def make_map(size: int) -> str:
    row = "".join(".~#"[i % 3] for i in range(size))
    return "\n".join(row for _ in range(size))

for size in (50, 100, 200):
    text = make_map(size)
    tracemalloc.start()
    shared_field = [[shared_tile(to_symbol(char))
                     for char in line]
                    for line in text.split()]
    _, shared_peak = tracemalloc.get_traced_memory()
    tracemalloc.stop()

    tracemalloc.start()
    unshared_field = [[unshared_tile(to_symbol(char))
                       for char in line]
                      for line in text.split()]
    _, unshared_peak = tracemalloc.get_traced_memory()
    tracemalloc.stop()

    ratio = round(unshared_peak / shared_peak, 1)
    print(size, "ratio unshared/shared:", ratio)
#: 50 ratio unshared/shared: 6.2
#: 100 ratio unshared/shared: 6.2
#: 200 ratio unshared/shared: 6.9

Compare the peaks across sizes. Both peaks grow with the number of cells, because both versions build the same nested list of references. The two versions differ in the memory one cell takes. A cell in the shared field takes one reference into a pool of three Tile objects, while a cell in the unshared field takes a reference plus a new Tile, roughly six times as much memory. That difference repeats in every cell, so the bytes saved grow with the map.

Tile is a record, so each unshared Tile is a slotted instance with no __dict__. With @dataclass(frozen=True) in place of @record, the same run reports a ratio near ten, because every unshared Tile then carries a dictionary too.

Before you move on, name what separates your attempt from this one: a different design, a detail, or an equivalent alternative.

3. Replacing @record with @dataclass exposes the sharing bug

Replace @record on Tile with @dataclass and set field[0][0].walkable = False on a parsed map. Write a test that exposes the resulting bug, then restore @record.

Where to look

Freezing the Shared Tile explains why a flyweight must be immutable. The pool holds one object per kind, so assigning to an attribute through one cell is visible through every cell that shares that object. In the test, assign through one cell, then assert on a different cell of the same kind.

The shape
# The shape of exercise_3.py
from dataclasses import dataclass
from functools import cache
from typing import Final

SPECS: Final[dict[str, tuple[str, bool]]] = {
    ".": ("grass", True),
    "~": ("water", False),
    "#": ("rock", False),
}

@dataclass  # Not a record
class MutableTile:
    symbol: str
    name: str
    walkable: bool

@cache
def mutable_tile(symbol: str) -> MutableTile:
    ...
Done when

your test passes with @dataclass on the tile class (MutableTile in the solution), fails with a FrozenInstanceError at the assignment once @record is back, and also fails if you remove @cache from the factory (mutable_tile() in the solution). That last check shows the test detects sharing, not just the assignment it made.

Solution

If you assert on the cell whose walkable you set, the test passes whether or not the cells share a tile. With @cache removed from mutable_tile(), each cell gets its own MutableTile. field[0][0].walkable still reads False after the assignment, so the test passes on code with one tile per cell. The test asserts on a different grass cell, field[1][1], whose walkable turns False only when the cells share one MutableTile.

A solution runs in its own folder, so this solution defines MutableTile, a @dataclass version of the chapter’s Tile, rather than editing a copy of tile_map.py. Its factory, mutable_tile(), takes the place of tile().

# exercise_3.py
from dataclasses import dataclass
from functools import cache
from typing import Final

SPECS: Final[dict[str, tuple[str, bool]]] = {
    ".": ("grass", True),
    "~": ("water", False),
    "#": ("rock", False),
}

@dataclass  # Not a record
class MutableTile:
    symbol: str
    name: str
    walkable: bool

@cache
def mutable_tile(symbol: str) -> MutableTile:
    name, walkable = SPECS[symbol]
    return MutableTile(symbol, name, walkable)

field = [[mutable_tile(char) for char in line]
         for line in "..\n..".split()]
field[0][0].walkable = False  # Meant to change one cell...
print(field[0][1].walkable, field[1][0].walkable,
      field[1][1].walkable)
#: False False False

Expose the shared state. Setting walkable = False on the tile at (0, 0) changes walkable for every other grass cell in the map too, because all four cells share one MutableTile object. The test asserts that the assignment reaches a different cell:

# test_ch35_mutation_leak.py
from dataclasses import dataclass
from functools import cache
from typing import Final

SPECS: Final[dict[str, tuple[str, bool]]] = {
    ".": ("grass", True),
    "~": ("water", False),
    "#": ("rock", False),
}

@dataclass  # Not a record
class MutableTile:
    symbol: str
    name: str
    walkable: bool

@cache
def mutable_tile(symbol: str) -> MutableTile:
    name, walkable = SPECS[symbol]
    return MutableTile(symbol, name, walkable)

def test_mutation_without_frozen_leaks_across_cells(
) -> None:
    field = [[mutable_tile(char) for char in line]
             for line in "..\n..".split()]
    field[0][0].walkable = False
    assert field[1][1].walkable is False  # Bug: cell leaked

If you restore @record, this test fails at its assignment: field[0][0].walkable = False raises a FrozenInstanceError, because a record rejects assignment to every attribute. The bug depends on that assignment, so every cell can share one record safely.

Before you move on, name what separates your attempt from this one: a different design, a detail, or an equivalent alternative.

4. Modeling chess

Model chess: a frozen Piece (color, kind) and a board that is a dict mapping squares to pieces. A full opening position holds thirty-two piece references. How many Piece objects exist? How do you capture and promote?

Where to look

Intrinsic and Extrinsic State separates what a piece is (color and kind) from where it stands. Share the color and kind through a @cache factory keyed on them, and keep the square as the dict key. A capture or a promotion then puts a different shared Piece on a square, and every Piece object stays as it was.

The shape
# The shape of exercise_4.py
from enum import Enum
from functools import cache
from record import record

class Color(Enum):
    WHITE = "white"
    BLACK = "black"

class Kind(Enum):
    PAWN = "P"
    ROOK = "R"
    KNIGHT = "N"
    BISHOP = "B"
    QUEEN = "Q"
    KING = "K"

@record
class Piece:
    color: Color
    kind: Kind

@cache
def piece(color: Color, kind: Kind) -> Piece:
    ...

type Square = tuple[str, int]

def starting_position() -> dict[Square, Piece]:
    ...

def move(
    board: dict[Square, Piece], src: Square, dst: Square
) -> None:
    # Overwrites dst's old occupant
    ...

def promote(
    board: dict[Square, Piece], square: Square, kind: Kind
) -> None:
    ...
Done when

the opening position holds 32 board entries that refer to 12 distinct Piece objects, a capture leaves 31 entries and still 12 objects, and a promoted pawn reports the new kind while every other pawn of its color still reports pawn.

Solution

If you promote by assigning to the piece, as in board[square].kind = kind, the frozen Piece rejects the assignment with a FrozenInstanceError. If you drop the freeze so the assignment succeeds, promoting the pawn on e4 turns every white pawn into a queen, because every white pawn is the same object. promote() leaves the shared Piece alone and points the square at a different one.

# exercise_4.py
from enum import Enum
from functools import cache
from record import record

class Color(Enum):
    WHITE = "white"
    BLACK = "black"

class Kind(Enum):
    PAWN = "P"
    ROOK = "R"
    KNIGHT = "N"
    BISHOP = "B"
    QUEEN = "Q"
    KING = "K"

@record
class Piece:
    color: Color
    kind: Kind

@cache
def piece(color: Color, kind: Kind) -> Piece:
    return Piece(color, kind)

type Square = tuple[str, int]

def starting_position() -> dict[Square, Piece]:
    board: dict[Square, Piece] = {}
    back_rank = [Kind.ROOK, Kind.KNIGHT, Kind.BISHOP,
                 Kind.QUEEN, Kind.KING, Kind.BISHOP,
                 Kind.KNIGHT, Kind.ROOK]
    for file, kind in zip("abcdefgh", back_rank):
        board[(file, 1)] = piece(Color.WHITE, kind)
        board[(file, 8)] = piece(Color.BLACK, kind)
    for file in "abcdefgh":
        board[(file, 2)] = piece(Color.WHITE, Kind.PAWN)
        board[(file, 7)] = piece(Color.BLACK, Kind.PAWN)
    return board

def move(
    board: dict[Square, Piece], src: Square, dst: Square
) -> None:
    # Overwrites dst's old occupant
    board[dst] = board.pop(src)

def promote(
    board: dict[Square, Piece], square: Square, kind: Kind
) -> None:
    current = board[square]
    # A shared Piece
    board[square] = piece(current.color, kind)

board = starting_position()
print(len(board), len({id(p) for p in board.values()}))
#: 32 12
move(board, ("e", 2), ("e", 4))
print(("e", 2) in board, board[("e", 4)].kind)
#: False Kind.PAWN
promote(board, ("e", 4), Kind.QUEEN)
queen = board[("e", 4)]
print(queen.color, queen.kind)
#: Color.WHITE Kind.QUEEN
pawns = [board[(f, 2)] for f in "abcdfgh"]
print(all(p.kind is Kind.PAWN for p in pawns))
#: True
move(board, ("e", 4), ("e", 7))  # Takes e7's pawn
print(len(board), len({id(p) for p in board.values()}))
#: 31 12

Share one piece per color and kind. starting_position() fills thirty-two squares with twelve distinct Piece objects: two colors times six kinds. Every white pawn is the same object, and so is every piece of any other color-and-kind combination. The board’s dict keeps the extrinsic position separate from the intrinsic color-and-kind that @cache shares.

Capture by replacing a reference. Capturing leaves every Piece object alive. @cache keeps the captured piece’s flyweight, which represents “a black knight” in the abstract rather than any particular knight on a square. The twelve Piece objects therefore remain in place through every capture that follows.

Promote by switching flyweights. A frozen Piece keeps its color and kind for life, so promote() changes what the square refers to. The seven other white pawns still refer to the shared pawn Piece, so each one still reports Kind.PAWN.

Before you move on, name what separates your attempt from this one: a different design, a detail, or an equivalent alternative.

5. interned_color.py, rewritten on a weak pool

Rewrite interned_color.py to hold its pool weakly, as weak_pool.py does, and show that building and dropping a palette of colors leaves the pool empty. Say what the rewrite gave up to get there.

Where to look

A Pool That Does Not Leak builds a pool that holds its flyweights in a WeakValueDictionary behind a factory function. Apply that shape to Color. A weak reference needs a __weakref__ slot, which weakref_slot=True adds. record() forwards slots=False alone, so this Color needs the dataclass call written out. To see what the rewrite gives up, compare how callers construct a Color here with Interning in the Constructor.

The shape
# The shape of exercise_5.py
from dataclasses import dataclass
from typing import Final
from weakref import WeakValueDictionary

type RGB = tuple[int, int, int]

@dataclass(frozen=True, slots=True, weakref_slot=True)
class Color:
    red: int
    green: int
    blue: int

def make_color(red: int, green: int, blue: int) -> Color:
    ...
Done when

your file prints the pool’s length as 50 after building a fifty-color palette and 0 after del drops it, two requests for the same components return the same object (is prints True), and you can show with one line a guarantee of interned_color.py that your version lacks.

Solution

If you keep @record on Color, the first make_color() call raises a TypeError at _pool[key] = found, because the WeakValueDictionary cannot create a weak reference to a slotted Color with no __weakref__ slot. The solution writes the dataclass call out with weakref_slot=True. That option adds the __weakref__ slot alone, so the class still has no __dict__.

# exercise_5.py
from dataclasses import dataclass
from typing import Final
from weakref import WeakValueDictionary

type RGB = tuple[int, int, int]

@dataclass(frozen=True, slots=True, weakref_slot=True)
class Color:
    red: int
    green: int
    blue: int

_pool: Final[WeakValueDictionary[RGB, Color]] = (
    WeakValueDictionary())

def make_color(red: int, green: int, blue: int) -> Color:
    key = (red, green, blue)
    found = _pool.get(key)
    if found is None:
        found = Color(red, green, blue)
        _pool[key] = found
    return found

palette = [make_color(r, 0, 0) for r in range(50)]
print(len(_pool))
#: 50
crimson_a = make_color(220, 20, 60)
crimson_b = make_color(220, 20, 60)
print(crimson_a is crimson_b)
#: True
bypass = Color(220, 20, 60)
print(bypass == crimson_a, bypass is crimson_a)
#: True False
del palette, crimson_a, crimson_b
print(len(_pool))
#: 0

Pool colors weakly behind a factory. This listing is weak_pool.py’s shape applied to colors: a factory function, make_color(), and a WeakValueDictionary for the pool. Color is a frozen data class, so it gets a generated __repr__(), __eq__(), and __hash__(), as the record Color in interned_color.py does. Like weak_pool.py’s Name, this Color writes the dataclass call in full, because a weak reference needs weakref_slot=True, and record() forwards slots=False alone.

Empty the pool on release. Once del drops the last references to the fifty-shade palette and both crimson names, Python frees those Color objects. The WeakValueDictionary then drops their entries on its own.

The rewrite gives up the constructor syntax, and with it the guarantee that every Color(...) call returns the pooled object. Color(220, 20, 60) still runs and builds a second object equal to the pooled one. A direct Tile(...) call makes the same bypass in the chapter.

The factory function, not the weak references, gives up the constructor syntax. As Choosing a Flyweight and Its Pool says, __new__() can look in a WeakValueDictionary as easily as in a dict. A Color that interns in __new__() keeps its constructor syntax and needs the same @dataclass(frozen=True, slots=True, weakref_slot=True) line as exercise_5.py’s Color.

Before you move on, name what separates your attempt from this one: a different design, a detail, or an equivalent alternative.

6. Constraining interned_color.py’s components

Constrain red, green, and blue to 0-255 in interned_color.py. Raise ValueError from __new__() for an out-of-range component, and write a test for it.

Where to look

Interning in the Constructor puts the pool lookup in __new__(). Check each component against the range at the top of __new__(), before the lookup, so an invalid Color stays out of the pool. The test uses pytest.raises(ValueError) once for a component above the range and once for one below it.

The shape
# The shape of exercise_6.py
from typing import ClassVar
from exceptions import expect
from record import record

type RGB = tuple[int, int, int]

@record
class Color:
    _pool: ClassVar[dict[RGB, Color]] = {}
    red: int
    green: int
    blue: int

    def __new__(
        cls, red: int, green: int, blue: int
    ) -> Color:
        ...
Done when

your test passes, Color(256, 0, 0) and Color(0, -1, 0) each raise a ValueError naming the bad component, Color(255, 255, 255) still succeeds, and len(Color._pool) reads the same after a rejected call as before it.

Solution

If you validate the components in __post_init__(), Color(300, 0, 0) still raises a ValueError, but only after __new__() has pooled the instance. Color._pool then keeps an out-of-range Color(red=300, green=0, blue=0). The solution checks the components at the top of __new__(), before the lookup, so an invalid Color stays out of the pool.

# exercise_6.py
from typing import ClassVar
from exceptions import expect
from record import record

type RGB = tuple[int, int, int]

@record
class Color:
    _pool: ClassVar[dict[RGB, Color]] = {}
    red: int
    green: int
    blue: int

    def __new__(
        cls, red: int, green: int, blue: int
    ) -> Color:
        components = (("red", red), ("green", green),
                      ("blue", blue))
        for name, value in components:
            if not (0 <= value <= 255):
                raise ValueError(
                    f"{name}={value} out of range 0-255")
        key: RGB = (red, green, blue)
        if key not in cls._pool:
            cls._pool[key] = super().__new__(cls)
        return cls._pool[key]

print(Color(255, 255, 255))
#: Color(red=255, green=255, blue=255)
before = len(Color._pool)
expect(ValueError, Color, 300, 0, 0)
#: [ValueError] red=300 out of range 0-255
print(before, len(Color._pool))
#: 1 1
# test_ch35_out_of_range.py
from typing import ClassVar
import pytest
from record import record

type RGB = tuple[int, int, int]

@record
class Color:
    _pool: ClassVar[dict[RGB, Color]] = {}
    red: int
    green: int
    blue: int

    def __new__(
        cls, red: int, green: int, blue: int
    ) -> Color:
        components = (("red", red), ("green", green),
                      ("blue", blue))
        for name, value in components:
            if not (0 <= value <= 255):
                raise ValueError(
                    f"{name}={value} out of range 0-255")
        key: RGB = (red, green, blue)
        if key not in cls._pool:
            cls._pool[key] = super().__new__(cls)
        return cls._pool[key]

def test_out_of_range_component_raises() -> None:
    with pytest.raises(ValueError):
        Color(256, 0, 0)
    with pytest.raises(ValueError):
        Color(0, -1, 0)

Validate before the pool lookup. Every Color that __new__() pools or returns has in-range components.

Data Classes as Types makes the same parse, don’t validate move with __post_init__(). Here the class validates in __new__(), because __post_init__() runs after __new__() has pooled the instance.

Before you move on, name what separates your attempt from this one: a different design, a detail, or an equivalent alternative.

7. tile_map.py rebuilt on the enum

Rewrite tile_map.py on top of tile_enum.py’s Tile, so parse_map() returns list[list[Tile]] of enum members and to_symbol() disappears. What does the type checker still catch that the Literal version caught, and what does it catch that the Literal version did not?

Where to look

In A Known Set: Enum, the language holds the pool, so Tile(symbol) is the lookup. Move the spec table into the member values and delete to_symbol(). For the comparison, consider where each version reports a wrong symbol: a misspelled member, and a symbol that arrives as data.

The shape
# The shape of exercise_7.py
from enum import Enum
from exceptions import expect

class Tile(Enum):
    GRASS = (".", True)
    WATER = ("~", False)
    ROCK = ("#", False)

    walkable: bool

    def __new__(cls, symbol: str, walkable: bool) -> Tile:
        ...

def parse_map(text: str) -> list[list[Tile]]:
    ...
Done when

tile_map_demo.py’s map prints 24 3, parse_map("?") raises ValueError: '?' is not a valid Tile, and uv run ty check reports missing-attribute on a member missing from the enum, such as Tile.DOOR. You can then say which wrong-symbol mistakes the type checker catches in each version and which stay runtime failures in both.

Solution
# exercise_7.py
from enum import Enum
from exceptions import expect

class Tile(Enum):
    GRASS = (".", True)
    WATER = ("~", False)
    ROCK = ("#", False)

    walkable: bool

    def __new__(cls, symbol: str, walkable: bool) -> Tile:
        member = object.__new__(cls)
        member._value_ = symbol
        member.walkable = walkable
        return member

def parse_map(text: str) -> list[list[Tile]]:
    return [[Tile(char) for char in line]
            for line in text.split()]

field = parse_map("""
    ..~~..
    ..~~.#
    ......
    ##..~~
""")
cells = [*row for row in field]
print(len(cells), len({id(t) for t in cells}))
#: 24 3
print(field[0][2] is field[3][5], field[0][2].walkable)
#: True False
expect(ValueError, parse_map, "?")
#: [ValueError] '?' is not a valid Tile

Let the enum hold the pool. SPECS, tile(), and to_symbol() all disappear. The member tuples are the spec table, and Tile(s) is the pool lookup. Tile(s) checks membership at runtime against the value-to-member table that the metaclass builds. to_symbol() makes the same check in its own body.

The type checker still catches each Literal-version mistake that the enum leaves possible. It reports invalid-implicit-return when a match over Tile leaves out a member, as it does when a match over Symbol leaves out a symbol. The Literal version’s SPECS annotation guards against a key outside Symbol. The enum makes that mismatch impossible, because it declares the set once instead of twice.

The enum adds one check. A misspelled or missing member, such as Tile.DOOR, is a missing-attribute error. In the Literal version, the wrapper that @cache returns takes any hashable argument in place of tile()’s Symbol, so the matching mistake, tile("+"), passes the type checker and fails at runtime with a KeyError.

An unknown symbol that arrives as data is a runtime failure in both versions. The type checker passes Tile("?"), and the call raises a ValueError.

The enum gives up a named place to fail. to_symbol() raises a KeyError at a named boundary, while Tile("?") raises a ValueError from deep inside parse_map()’s comprehension. If the boundary matters, keep a to_tile() wrapper that catches the ValueError and re-raises it with the offending line and column.

Before you move on, name what separates your attempt from this one: a different design, a detail, or an equivalent alternative.

8. Four threads on a cold key

Make tile()’s body slow, with a time.sleep(0.05) before it builds the Tile, and call it from four threads with the same, previously unseen symbol. How many Tile objects does the run build, and how many distinct objects do the four threads hold? Fix it two ways: populate the pool eagerly at import, and guard the factory with a threading.Lock.

Where to look

Sharing, Not Caching says a flyweight’s factory exists to guarantee identity. Interning in the Constructor says @cache checks the key and stores the result in separate steps. The time.sleep() widens the gap between those steps, so every thread can miss before any thread stores. For the fixes, build every Tile into a table before starting any thread, and separately wrap the call to tile() in a threading.Lock.

The shape
# The shape of exercise_8.py
import threading
import time
from collections.abc import Callable
from functools import cache
from typing import Final, Literal
from record import record

type Symbol = Literal[".", "~", "^", "*"]

@record
class Tile:
    symbol: Symbol
    name: str
    walkable: bool

SPECS: Final[dict[Symbol, tuple[str, bool]]] = {
    ".": ("grass", True),
    "~": ("water", False),
    "^": ("hill", True),
    "*": ("sand", True),
}

@cache
def tile(symbol: Symbol) -> Tile:
    # Widen the window between miss and store
    ...

def gather(
    factory: Callable[[Symbol], Tile], symbol: Symbol
) -> list[Tile]:
    "Call factory(symbol) from four threads at once."
    ...

EAGER: Final[dict[Symbol, Tile]] = {
    s: Tile(s, *spec) for s, spec in SPECS.items()}

def eager_tile(symbol: Symbol) -> Tile:
    ...

def locked_tile(symbol: Symbol) -> Tile:
    ...
Done when

four threads calling the slow tile() on a cold symbol print 4 4 (four results, four distinct objects), and each fixed version leaves the four threads holding 1 distinct object. Give each fix a fresh symbol, since a warm cache entry hides the race.

Solution

If you put the lock inside tile(), around the sleep and the build, the listing’s last line prints 4 instead of 1. @cache checks the key before the body runs, so all four threads miss and then take turns building their own Tile. The lock puts the builds in order, but all four still run. The solution wraps the call to tile(), so the lookup, the build, and the store all run under one lock.

# exercise_8.py
import threading
import time
from collections.abc import Callable
from functools import cache
from typing import Final, Literal
from record import record

type Symbol = Literal[".", "~", "^", "*"]

@record
class Tile:
    symbol: Symbol
    name: str
    walkable: bool

SPECS: Final[dict[Symbol, tuple[str, bool]]] = {
    ".": ("grass", True),
    "~": ("water", False),
    "^": ("hill", True),
    "*": ("sand", True),
}

@cache
def tile(symbol: Symbol) -> Tile:
    # Widen the window between miss and store
    time.sleep(0.05)
    name, walkable = SPECS[symbol]
    return Tile(symbol, name, walkable)

def gather(
    factory: Callable[[Symbol], Tile], symbol: Symbol
) -> list[Tile]:
    "Call factory(symbol) from four threads at once."
    out: list[Tile] = []
    lock = threading.Lock()

    def worker() -> None:
        found = factory(symbol)
        with lock:
            out.append(found)

    threads = [threading.Thread(target=worker)
               for _ in range(4)]
    for t in threads:
        t.start()
    for t in threads:
        t.join()
    return out

raced = gather(tile, "^")
print(len(raced), len({id(t) for t in raced}))
#: 4 4

EAGER: Final[dict[Symbol, Tile]] = {
    s: Tile(s, *spec) for s, spec in SPECS.items()}

def eager_tile(symbol: Symbol) -> Tile:
    return EAGER[symbol]

print(len({id(t) for t in gather(eager_tile, "*")}))
#: 1

guard = threading.Lock()

def locked_tile(symbol: Symbol) -> Tile:
    with guard:
        return tile(symbol)

print(len({id(t) for t in gather(locked_tile, "~")}))
#: 1

Expose the cold-key race. @cache looks up the key, misses, calls the function, and stores the result. No lock spans those steps. Four threads that miss on the same cold key therefore all run the body. Each thread keeps the Tile it built, so the four results are four distinct objects. Each store overwrites the one before it, so the cache keeps the last thread’s Tile. Every later caller gets that one object, while the other three threads hold Tile objects that the cache has dropped.

@cache works as designed here. A cache that holds a lock across the call serializes every miss in the program. Serializing every miss is a worse default than occasionally building a value twice. For an ordinary memoized computation, a duplicate build wastes time and leaves the results correct. For a Flyweight, the duplicate is a bug, because the pattern exists to make tile("^") is tile("^") hold.

Fill the pool eagerly. Only a miss can start a race. The eager fix builds every value before any thread exists, so every lookup hits. Each lookup is one dict index and takes no lock. Eager filling is the better answer whenever the whole value set fits in one small table. An Enum works under the same condition.

Guard the factory with a lock. The lock fix handles an unbounded value set. Every lookup now serializes, including the hits, which are the overwhelming majority once the pool is warm. If that serialization matters, write your own pool and lock only on the miss path. Check the key again inside the lock, since another thread may have filled that entry while this one waited.

Before you move on, name what separates your attempt from this one: a different design, a detail, or an equivalent alternative.