osrlib.versioning
The two version stamps on every osrlib document, and the envelope that contains them.
Anything osrlib writes for you to keep is a stamped document: a save, a character, a
party, a content pack. A stamped document is a dict with the same four keys every time.
kind is the type of thing inside, schema_version and engine_version are the two
version stamps, and payload is the serialized content. osrlib calls the four keys the
envelope. stamp_document builds one and
check_document checks one. You rarely call either
yourself: save_game and
load_game call them for saves, and
Character.to_document,
party_to_document, and
ContentPack.to_document call
stamp_document for characters, parties, and content packs.
The members, in the order you use them:
stamp_document: takes a kind and a payload, and returns a stamped document.check_document: takes a stamped document and the kind you expect, and returns the payload.SCHEMA_VERSION: the format version this library writes.engine_version: returns the installed osrlib version.
The two stamps have different purposes.
Use SCHEMA_VERSION to find out whether osrlib can
still read a document. It's one integer shared by every document kind, and it changes only when the format of
stored data changes in a way that would break a reader. osrlib reads a document stamped lower
than the running library's number and upgrades it. For a document stamped higher, it raises
SaveVersionError, because this version can't read what a
later version added.
Use engine_version to find out whether you can still
reproduce a game. It's the installed package version, and it changes with every release, including
releases that change no document format. Rules can change between releases, so a recorded
command log run again under a different engine can resolve differently. When you pass the
recorded version, replay_game raises an error on a mismatch
instead of producing a game that differs with no warning. Loading a save works across engine
versions, because a save contains the state instead of computing it again.
If you store documents, keep both numbers with them. From schema_version you know whether
the installed library can open the file, and from engine_version whether a replay of
it is still valid.
Typical usage:
from osrlib.versioning import SCHEMA_VERSION, check_document, stamp_document
document = stamp_document("note", {"text": "found the crypt"})
print(document["kind"], document["schema_version"] == SCHEMA_VERSION)
# note True
print(check_document(document, "note"))
# {'text': 'found the crypt'}
SCHEMA_VERSION
module-attribute
SCHEMA_VERSION: Final = 4
The schema version this library writes, and the highest it can read.
Every document stamp_document produces includes this
number. osrlib stamps saves, characters, parties, and content packs with it, and the same
number versions the formats of commands and events. There's one schema version for the whole
library, not one per kind.
Compare a stored document's schema_version with this number to know what you can do
with it:
- Lower: the document still loads. osrlib upgrades it when it reads it, through
MIGRATIONSfor a save, so you don't need code of your own for old files. - Equal: it loads as written.
- Higher: a later osrlib wrote it, and reading it raises
SaveVersionError.
The number changes only when a change would break a reader: a field renamed, a field removed, a value that now means something different. Additions don't change it. A document from an earlier release with the same schema version can lack fields that newer documents include, and readers fill those with their defaults.
What each version changes in an older save:
- Version 2 drops the recovered-treasure ledger from the save payload. The session works out the end-of-adventure award from the valuation it records when the party leaves town.
- Version 3 allows only
"open"as a treasure trap'strigger, the one action that springs a cache. The migration rewrites an"enter"trigger to"open", and a content pack gets the same rewrite when it loads. - Version 4 drops
"withdraw"from a battle declaration'smove. The round resolver never acted on that value, so a member who declared it stood still. The migration clears it from each logged declaration that has it. If that declaration's action is"move", the action becomes"hold".
No step drops anything osrlib reads back.
check_document
Check a stamped document's envelope and return the payload inside it.
Call this first when you read a document back, before you read any field of the payload. It confirms that the envelope's keys are there and well formed, that the document is of the kind you expect, and that a later osrlib didn't write it.
It checks the envelope, not the payload. A payload that passes here can still fail when
you validate it into a model. load_game and
party_from_document call this function
and then validate the payload, so call it directly only for a document kind you
stamped yourself with stamp_document.
A document with an older schema version passes, and you upgrade its payload yourself, as
load_game does through MIGRATIONS. The function
ignores extra keys in the envelope, so you can still read a document that a later release
wrote with the same schema version. It doesn't check the engine_version key.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
document
|
Mapping[str, object]
|
A mapping produced by
|
required |
expected_kind
|
str
|
The |
required |
Returns:
| Type | Description |
|---|---|
dict[str, object]
|
A deep copy of the document's payload, still at whatever schema version the document
was written under. It shares nothing with |
Raises:
| Type | Description |
|---|---|
ContentValidationError
|
If the document is not a mapping, is missing |
SaveVersionError
|
If the document's |
Examples:
from osrlib.errors import ContentValidationError
from osrlib.versioning import check_document, stamp_document
document = stamp_document("note", {"text": "found the crypt"})
print(check_document(document, "note"))
# {'text': 'found the crypt'}
try:
check_document(document, "save")
except ContentValidationError as error:
print(error)
# expected a 'save' document, got kind 'note'
engine_version
engine_version() -> str
Return the version of the installed osrlib package.
This is the second stamp on every document, and replay_game uses it to detect that the
rules may have changed. stamp_document calls it for you, so
you usually read the value out of a document instead of calling this function. Pass that
value to replay_game as recorded_engine_version
when you want it to raise an error if the engine version has changed since the log was recorded.
Call it directly to label a bug report, or to compare with a stamp you stored
elsewhere. It isn't the schema version. This number changes with every release, including
releases that change no document format, so you can't use it to tell whether a document
still parses. Use SCHEMA_VERSION for that.
Returns:
| Type | Description |
|---|---|
str
|
The installed package version, as the packaging metadata reports it, like |
Examples:
stamp_document
Wrap a serialized payload in the stamped-document envelope.
Use this when you serialize something of your own and want it stored the way osrlib
documents are, so check_document can check it when
you read it back, and a later reader can tell what's inside. For a save, a party, a
character, or a content pack, call save_game,
party_to_document,
Character.to_document, or
ContentPack.to_document instead.
Each one stamps the right kind and builds the payload for you.
The result is ready for json.dumps if the payload is. Pass a payload you already
turned into JSON-compatible values, which for a pydantic model means
model_dump(mode="json"). This function copies the mapping one level deep and converts
nothing inside it.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
kind
|
str
|
What the document contains, like |
required |
payload
|
Mapping[str, object]
|
The serialized content, in JSON-compatible values. |
required |
Returns:
| Type | Description |
|---|---|
dict[str, object]
|
A new dict with |
Raises:
| Type | Description |
|---|---|
ValueError
|
If |
Examples: