Skip to content

Documents

rn_forge.commons.fs.documents

JSON, YAML, and TOML serialization and round-trip document editing.

Plain reads return regular mappings and discard comments. Round-trip reads use ruamel.yaml or tomlkit to preserve comments and formatting across an edit. YAML also supports multi-document streams.

ConfigFormat

Bases: StrEnum

A configuration document's serialization format.

of(path, override=None) classmethod

Resolve the format from path's suffix, or override if given.

.yml is treated as an alias for yaml.

Raises:

Type Description
DocumentError

The resolved suffix does not match a known format.

DocumentError(message, *message_args, error_code=-1, **error_data)

Bases: AppException

A configuration document cannot be read, parsed, or encoded.

check(value, message, *message_args, **kwargs) classmethod

Raise this exception if value is falsy.

Parameters:

Name Type Description Default
value Any

The value to test.

required
message str

Exception message (supports positional format args).

required
*message_args Any

Forwarded to message.format().

()
**kwargs Any

Forwarded as error_code / error_data to the constructor.

{}

Example::

AppException.check(path.exists(), "Missing file: {}", path, error_code=404)

DocumentUtils

Config documents addressed by path, with an optional round-trip mode.

The plain methods (:meth:loads, :meth:dumps, :meth:read, :meth:write) produce ordinary dict/list/scalar trees and discard comments. The document methods (:meth:read_document, :meth:write_document, :meth:update) keep the backing library's own containers, so comments and formatting survive an edit.

append_to_array(document, key, fields) staticmethod

Append one table built from fields to the array-of-tables at key.

Creates the array if key is absent. Intended for TOML documents — appending to an array-of-tables without disturbing surrounding comments is fiddly enough to be worth solving once.

dumps(data, fmt, *, header=None, multiline_arrays=False) staticmethod

Serialize data in format fmt, in a stable, human-readable form.

Parameters:

Name Type Description Default
data Mapping[str, Any]

The mapping to serialize.

required
fmt ConfigFormat | str

The output format.

required
header str | None

Comment text without markers, written before the document with each line prefixed by #. TOML and YAML only.

None
multiline_arrays bool

Write each non-empty TOML array one element per line. YAML and JSON already do, and ignore it.

False

Raises:

Type Description
DocumentError

header is given for JSON.

loads(text, fmt) staticmethod

Parse text in format fmt into a plain, comment-free mapping.

Raises:

Type Description
DocumentError

text is invalid for fmt, or its root is not a mapping.

multiline_arrays(document, *key_paths) staticmethod

Format arrays of a round-trip TOML document one element per line.

With no key_paths, every non-empty array is formatted, found through tables and the tables of arrays of tables. With key_paths (dotted, as in :meth:DictUtils.get), only the arrays at those paths are formatted; a path that is missing or not a non-empty array is skipped. Inline table elements are rewritten with { key = value } spacing.

Parameters:

Name Type Description Default
document Any

A round-trip TOML document, such as the result of :meth:read_document or tomlkit.parse.

required
*key_paths str

Dotted paths of the arrays to format.

()

read(source, *, missing_ok=False) staticmethod

Read and parse the document at source into a plain mapping.

Parameters:

Name Type Description Default
source str | Path | Traversable

The document file, or a package resource.

required
missing_ok bool

When True, a missing file returns {} instead of raising.

False

Raises:

Type Description
DocumentError

source does not exist (and missing_ok=False), or the document is invalid; the message starts with source.

Example

DocumentUtils.read(files("my_tool").joinpath("defaults.toml"))

read_document(path) staticmethod

Read path as a round-trip document, preserving comments and style.

Raises:

Type Description
DocumentError

The document is invalid for its resolved format or its root is not a mapping.

serialize_document(path, document) staticmethod

The text :meth:write_document would write for a round-trip document.

update(path, updates) staticmethod

Deep-update the document at path with updates, preserving comments.

Creates path (via :meth:write) if it does not yet exist.

Raises:

Type Description
DocumentError

The existing document's root is not a mutable mapping.

write(path, data, *, header=None, multiline_arrays=False) staticmethod

Atomically write data to path, formatted per its suffix.

header and multiline_arrays are as in :meth:dumps.

write_document(path, document) staticmethod

Atomically write a round-trip document without flattening it.

JsonUtils

JSON helpers with dataclass-aware serialisation and file I/O.

load(text, *, root_key=None) staticmethod

Parse a JSON string and return the resulting Python object.

Parameters:

Name Type Description Default
text str

Raw JSON text.

required
root_key str | None

When provided, return only the value at this top-level key from the parsed object.

None

Returns:

Type Description
Any

The parsed Python object, or the value at root_key if given.

Raises:

Type Description
JSONDecodeError

If text is not valid JSON.

KeyError

If root_key is provided but absent from the parsed object.

read_file(path, *, encoding=None) staticmethod

Read and parse a JSON file.

Parameters:

Name Type Description Default
path str | Path

Path to the .json file.

required
encoding str | None

Text encoding passed to :meth:~pathlib.Path.read_text. Defaults to the platform default when None.

None

Returns:

Type Description
Any

The parsed Python object.

Raises:

Type Description
FileNotFoundError

If path does not exist.

JSONDecodeError

If the file content is not valid JSON.

serialize(obj, **kwargs) staticmethod

Serialise obj to a JSON string.

Dataclasses are automatically converted via dataclasses.asdict(). Other non-serialisable objects fall back to repr().

Parameters:

Name Type Description Default
obj Any

The Python object to serialise.

required
**kwargs Any

Forwarded to :func:json.dumps (e.g. indent, sort_keys).

{}

Returns:

Type Description
str

A JSON string representation of obj.

write_file(obj, path, *, indent='\t', encoding=None, **kwargs) staticmethod

Serialise obj to JSON and write to path, creating parents as needed.

Parameters:

Name Type Description Default
obj Any

The Python object to serialise.

required
path str | Path

Destination file path.

required
indent str | int

Indentation for pretty-printing. Defaults to a tab character ("\t").

'\t'
encoding str | None

Text encoding for the output file. Defaults to the platform default when None.

None
**kwargs Any

Additional keyword arguments forwarded to :meth:JsonUtils.serialize.

{}

Returns:

Type Description
Path

The resolved :class:~pathlib.Path that was written.

YamlUtils

YAML helpers with multi-document support and file I/O.

Backed by ruamel.yaml in typ="safe" mode: only standard YAML tags are loaded and emitted, so untrusted input cannot instantiate arbitrary Python objects. Use :class:DocumentUtils when comments and formatting must survive a round trip.

load(text, *, root_key=None) staticmethod

Parse a YAML string and return the resulting Python object.

Parameters:

Name Type Description Default
text str

Raw YAML text.

required
root_key str | None

When provided, return only the value at this top-level key from the parsed document.

None

Returns:

Type Description
Any

The parsed Python object, or the value at root_key if given.

Any

An empty document yields None.

Raises:

Type Description
YAMLError

If text is not valid YAML.

KeyError

If root_key is provided but absent from the parsed document.

load_all(text) staticmethod

Parse a multi-document YAML string.

Parameters:

Name Type Description Default
text str

Raw YAML text containing one or more ----separated documents.

required

Returns:

Type Description
list[Any]

A list of parsed Python objects, one per non-empty document.

Raises:

Type Description
YAMLError

If text is not valid YAML.

read_file(path, *, root_key=None, encoding=None) staticmethod

Read and parse a YAML file.

Parameters:

Name Type Description Default
path str | Path

Path to the .yaml / .yml file.

required
root_key str | None

When provided, return only the value at this top-level key from the parsed document.

None
encoding str | None

Text encoding passed to :meth:~pathlib.Path.read_text. Defaults to the platform default when None.

None

Returns:

Type Description
Any

The parsed Python object, or the value at root_key if given.

Raises:

Type Description
FileNotFoundError

If path does not exist.

read_file_all(path, *, encoding=None) staticmethod

Read and parse a multi-document YAML file.

Parameters:

Name Type Description Default
path str | Path

Path to the .yaml / .yml file.

required
encoding str | None

Text encoding passed to :meth:~pathlib.Path.read_text. Defaults to the platform default when None.

None

Returns:

Type Description
list[Any]

A list of parsed Python objects, one per non-empty YAML document

list[Any]

in the file.

Raises:

Type Description
FileNotFoundError

If path does not exist.

serialize(obj, *, sort_keys=False, **kwargs) staticmethod

Serialise obj to a YAML string.

Parameters:

Name Type Description Default
obj Any

The Python object to serialise. Only standard YAML types are supported; dataclasses must be converted first (e.g. via :meth:~rn_forge.commons.lang.dataclasses.DataclassMixin.as_dict).

required
sort_keys bool

Sort mapping keys in the output. Defaults to False, preserving insertion order.

False
**kwargs Any

Set as attributes on the underlying ruamel.yaml.YAML instance (e.g. indent, width, allow_unicode, default_flow_style).

{}

Returns:

Type Description
str

The YAML representation of obj, block-style by default.

Raises:

Type Description
YAMLError

If obj contains a type the safe representer cannot emit.

serialize_all(*objs, sort_keys=False, **kwargs) staticmethod

Serialise objs to a single multi-document YAML string.

Parameters:

Name Type Description Default
*objs Any

The Python objects to serialise, one document each.

()
sort_keys bool

Sort mapping keys in the output. Defaults to False.

False
**kwargs Any

Set as attributes on the underlying ruamel.yaml.YAML instance.

{}

Returns:

Type Description
str

The ----separated YAML representation of objs.

Raises:

Type Description
YAMLError

If any object contains a type the safe representer cannot emit.

write_file(obj, path, *, encoding=None, **kwargs) staticmethod

Serialise obj to YAML and write to path, creating parents as needed.

Parameters:

Name Type Description Default
obj Any

The Python object to serialise.

required
path str | Path

Destination file path.

required
encoding str | None

Text encoding for the output file. Defaults to the platform default when None.

None
**kwargs Any

Additional keyword arguments forwarded to :meth:YamlUtils.serialize.

{}

Returns:

Type Description
Path

The resolved :class:~pathlib.Path that was written.