Skip to content

osrlib.core.frozen

The read-only mapping in the frozen content models, like the numbers in a monster ability's params.

The class, monster, item, spell, and table models that osrlib.data loads are frozen, and each loader returns one cached catalog that every caller in the process shares. A field of those models that maps names to values, like MonsterAbility.params, is a FrozenMap, so nothing in a catalog can be changed at any depth. A change to the troll's regeneration would otherwise change every troll in every session. An Adventure is shared the same way by every session you start from it, so its mapping fields, like a level's edges, are FrozenMaps too.

You read a FrozenMap the way you read a dict. When you build a model, you pass a dict for the field, and the model stores a FrozenMap of it. model_dump gives you a dict again. To change an entry, build a new model. Either dump the one you have, change the dump, and validate it, or copy it with model_copy(update=...). Every osrlib model validates a copy that has an update, so the copy stores a FrozenMap of a dict you pass, and it raises pydantic.ValidationError for a value that building the model would refuse.

Typical usage:

from osrlib.core.monsters import MonsterTemplate
from osrlib.data import load_monsters

troll = load_monsters().get("troll")
print(troll.ability("regeneration").params["per_round"])
# 3

# A bog troll that regenerates faster, built from a dump of the troll.
document = troll.model_dump()
for ability in document["abilities"]:
    if ability["tag"] == "regeneration":
        ability["params"]["per_round"] = 5
bog_troll = MonsterTemplate.model_validate(
    {**document, "id": "bog_troll", "name": "Bog Troll", "display_name": "bog troll", "family_id": "bog_troll"}
)
print(bog_troll.ability("regeneration").params["per_round"], troll.ability("regeneration").params["per_round"])
# 5 3

# The same change to the ability alone, as a copy.
regeneration = troll.ability("regeneration")
faster = regeneration.model_copy(update={"params": {**regeneration.params, "per_round": 5}})
print(faster.params["per_round"], type(faster.params).__name__)
# 5 FrozenMap

FrozenMap

FrozenMap(entries: Mapping[K, V] | Iterable[tuple[K, V]] = ())

Bases: Mapping[K, V]

A mapping whose entries can't be changed, the type of each mapping field in the content models.

The content models are the class, monster, item, spell, and table models that osrlib.data loads, the EffectDefinition that an effect runs from, and the models an Adventure or a ContentPack contains. A session's state, like its dungeon state and its flags, isn't content, and its mappings are dicts you can change.

Read one the way you read a dict: index it, call get, iterate it, or test a key with in. Assigning or deleting an entry raises TypeError, and it has no update, pop, or clear. It compares equal to a dict with the same entries, so ability.params == {"per_round": 3} is True. It's hashable when its values are, and copy.deepcopy and pickle copy it.

You rarely build one yourself. A model field annotated Annotated[Mapping[K, V], FrozenMap] accepts any mapping, like a dict, and stores a FrozenMap of it, both when you build the model and when you copy it with model_copy(update=...). The type checker reads the field as a Mapping, which has no methods that change it. The field's model_dump value is a new dict, which you can change and pass to model_validate to build a new model. For a dict you can change without building a model, call dict() on the mapping.

To give a model of your own a mapping field that can't be changed, annotate it the same way, and use FrozenMap() as the default for an empty one.

Examples:

from osrlib.data import load_monsters

params = load_monsters().get("troll").ability("regeneration").params
print(params["per_round"], params["delay_rounds"], params["blocked_by"])
# 3 3 ('fire', 'acid')
print(params == {"blocked_by": ("fire", "acid"), "delay_rounds": 3, "per_round": 3, "revive": "2d6"})
# True

mine = dict(params)  # a dict of your own, which you can change
mine["per_round"] = 5
print(mine["per_round"], params["per_round"])
# 5 3

Copy the entries of a mapping, or of an iterable of key and value pairs, into a new FrozenMap.

Parameters:

Name Type Description Default
entries Mapping[K, V] | Iterable[tuple[K, V]]

The entries, like a dict. A later change to it doesn't change the FrozenMap. Leave it out for an empty one.

()

get

get(key: K) -> V | None
get(key: K, default: V) -> V
get(key: K, default: T) -> V | T
get(key: K, default: Any = None) -> Any

Return the value for key, or default when the mapping has no entry for it.

keys

keys() -> KeysView[K]

Return a read-only view of the keys, in the order the entries were given.

values

values() -> ValuesView[V]

Return a read-only view of the values, in the order the entries were given.

items

items() -> ItemsView[K, V]

Return a read-only view of the key and value pairs, in the order the entries were given.