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 |
()
|
**kwargs
|
Any
|
Forwarded as |
{}
|
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 |
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: |
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 |
False
|
Raises:
| Type | Description |
|---|---|
DocumentError
|
source does not exist (and |
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 |
required |
encoding
|
str | None
|
Text encoding passed to :meth: |
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: |
{}
|
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'
|
encoding
|
str | None
|
Text encoding for the output file. Defaults to the
platform default when |
None
|
**kwargs
|
Any
|
Additional keyword arguments forwarded to
:meth: |
{}
|
Returns:
| Type | Description |
|---|---|
Path
|
The resolved :class: |
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 |
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 |
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 |
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: |
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 |
required |
encoding
|
str | None
|
Text encoding passed to :meth: |
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: |
required |
sort_keys
|
bool
|
Sort mapping keys in the output. Defaults to |
False
|
**kwargs
|
Any
|
Set as attributes on the underlying |
{}
|
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
|
**kwargs
|
Any
|
Set as attributes on the underlying |
{}
|
Returns:
| Type | Description |
|---|---|
str
|
The |
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
|
**kwargs
|
Any
|
Additional keyword arguments forwarded to
:meth: |
{}
|
Returns:
| Type | Description |
|---|---|
Path
|
The resolved :class: |