Docstrings: shared services - #94
Merged
Merged
Conversation
Rewrite the docstrings in osrlib/__init__.py, errors.py, versioning.py, data/__init__.py, messages.py, and persistence.py so a developer reading the published reference can call them without opening the source. Adds attribute docstrings to the Language and LanguageCatalog fields so they render with prose, and a runnable example to every loader and every public function in the services layer. Claude-Session: https://claude.ai/code/session_01GL26QnA6dCrvUc3WmhzFSa
session_state no longer claims the payload shares nothing with the session: a raw event-log entry kept for an unrecognized event type goes in by reference. The languages field no longer claims Common comes first; the shipped file is alphabetical by id. The persistence module docstring now attaches the condition replay_game states, that the party document must predate the session. The data module docstring says again that the JSON files are generated and never edited by hand. format_message scopes its no-raise guarantee to events osrlib built. Claude-Session: https://claude.ai/code/session_01GL26QnA6dCrvUc3WmhzFSa
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
I rewrote the docstrings for the six shared-services files so a developer reading the published reference can write the call and use the result without opening the source. The package docstring is now the reference's front page: it says what osrlib does, then lists every module in all three layers, in the order a reader meets them, with one line each for what goes in and what comes out. The data loaders now say what each catalog is for, which kernel function takes the entry you look up, that the result is cached and frozen, and where the id index for that catalog lives.
messages.pysays where message codes come from and links the message-code reference.persistence.pysays what a save contains, whatschema_versionmeans for someone storing documents, what replay guarantees, and why the party document you replay from has to be taken before the session starts.errors.pynames which functions raise which error and separates a raised error from a rejected command.versioning.pysays what each stamp answers and when to compare it.The quickstart block in the package docstring is unchanged, so it stays byte-identical to the one in README.md, and I made no other change to README.md.
I corrected no docstring for disagreeing with the code. Two claims I checked and kept: the comment at
src/osrlib/messages.py:381said the engine always fills the quest and objective name fields, whichsrc/osrlib/crawl/session.py:1188does, so the fallback to ids is for events that arrive without them; and the module docstring's claim that a load and a replay of the same game reach identical state holds only when the party document predates the session, which is now stated inreplay_game.Every example is runnable and runs under the docs harness. I left the message templates in
_TEMPLATESand the exception message strings untouched: they are the library's user-visible output, the golden files assert on them, and the message-code page publishes the template source as written.uv run ruff format --check && uv run ruff check && uv run pyright && uv run pytest -q && uv run mkdocs build --strictpasses: 0 pyright errors, 2279 tests passed, 73 skipped, strict build clean.https://claude.ai/code/session_01GL26QnA6dCrvUc3WmhzFSa