evennia-yaml-reader

A source-agnostic YAML file reader for declarative-content libraries in the Evennia ecosystem.

The library abstracts where the YAML lives — local filesystem, GitHub repo, future sources — behind a uniform Reader interface. Consumers fetch a file by path, get back its raw bytes and parsed YAML, and dispatch on a small set of typed errors when something goes wrong.

Status

Foundational. Reader contract + GitHubReader + LocalReader are in place, ported from evennia-world-builder where the pattern was first proven. 15 unit tests green. See docs/progress.md for the running milestone log.

What's in the box

Both honour the same contract: read(path) returns a ReaderResult with raw_bytes and parsed YAML; failures raise one of ReaderAuthError, ReaderNotFoundError, ReaderNetworkError, or ReaderParseError.

from evennia_yaml_reader import LocalReader

reader = LocalReader(root="/path/to/content")
result = reader.read("subfolder/file.yaml")
print(result.parsed)        # dict / list / scalar / None
print(result.raw_bytes)     # the bytes as they came back from the source

from evennia_yaml_reader import GitHubReader

reader = GitHubReader(repo="owner/content-repo", ref="main", pat="ghp_…")
result = reader.read("subfolder/file.yaml")

The Reader instance is reusable — construct once per source, call read(path) as many times as you need.

Is this for me?

This library is a plumbing dependency — most of its value shows up one layer removed, inside other Evennia-ecosystem libraries that read declarative YAML content, rather than in a gamedir installing it directly. Current examples: evennia-world-builder and evennia-mob-spawner. Each is intended to publish to PyPI the same way this library does; if one hasn't published yet, its GitHub repo linked above is the source in the meantime.

You'd install this library directly if you're building a new Evennia-flavored library that:

• Wants to keep YAML content in a separate repository (e.g. a content repo distinct from your gamedir).
• Wants to develop locally against a working copy of that repo and deploy from GitHub in production — without changing call sites.
• Wants typed errors (not None / empty defaults) when a file is missing, an auth call fails, the network blips, or the YAML is malformed.

If you only ever read YAML from one location with one auth model, open(path) + yaml.safe_load(...) is fine and you do not need this library.

Install

pip install evennia-yaml-reader

Editable install for development against a checkout:

git clone https://github.com/FullCircleMUD/evennia-yaml-reader.git
cd evennia-yaml-reader
python -m venv venv
# Activate the venv (platform-specific)
pip install -e .
python runtests.py

Learn more

• CLAUDE.md — load-bearing principles and orientation for working in the repository.
• docs/INDEX.md — index of design documents.
• docs/reader-api.md — the architectural decisions behind the Reader contract.
• src/evennia_yaml_reader/base.md — Reader and ReaderResult reference, co-located with the code.

License

BSD 3-Clause. See LICENSE.