Data
Collections
from rn_forge.commons import DictUtils, ListUtils
data = {"users": [{"name": "Alice"}, {"name": "Bob"}]}
name = DictUtils.get(data, "users.1.name")
grouped = ListUtils.group_by(["aa", "ab", "ba"], key_fn=lambda item: item[0])
get returns Any. To read a parsed TOML/YAML/JSON document under a strict
type checker, use the typed reads instead. They never raise: a missing path or a
value of the wrong shape reads as empty (or the given default).
doc = {"tasks": {"build": {"cmds": "echo hi"}}, "dev": ["pytest", {"include-group": "lint"}]}
DictUtils.get_mapping(doc, "tasks.build") # {"cmds": "echo hi"} (dict[str, object])
DictUtils.get_list(doc, "tasks.build.cmds") # ["echo hi"] a lone scalar is one element
DictUtils.get_strings(doc, "dev") # ["pytest"] non-strings dropped
DictUtils.get_str(doc, "tasks.build.cmds") # "echo hi"
DictUtils.get_bool(doc, "strict", default=True) # True
To read a bare value, such as the root of a parsed document that may not be a
mapping, use DictUtils.as_mapping, ListUtils.as_list and
ListUtils.as_strings:
DictUtils.get_mapping(DictUtils.as_mapping(YamlUtils.load(text)), "jobs")
ListUtils.as_strings(["pytest", {"include-group": "lint"}]) # ["pytest"]
Documents
JsonUtils and YamlUtils cover plain (de)serialization and file I/O.
DocumentUtils dispatches on a path's suffix and can edit TOML/YAML in place
without losing comments or formatting.
from rn_forge.commons import DocumentUtils, JsonUtils, YamlUtils
text = JsonUtils.serialize(grouped, indent=2)
yaml_text = YamlUtils.serialize(data)
# comments and formatting in pyproject.toml survive this edit
DocumentUtils.update("pyproject.toml", {"project": {"version": "0.4.0"}})
Plain YAML loads use libyaml. YAML 1.2 rules apply, so on, yes and no load
as strings, not booleans. A GitHub Actions workflow's on: key is the string
"on".
DocumentUtils.read also takes a package resource, such as
files("my_tool").joinpath("defaults.toml"), and names the source in a parse
error. DocumentUtils.dumps and write take header (comment text written
before the document, for TOML and YAML) and multiline_arrays (each non-empty
TOML array on one element per line); DocumentUtils.multiline_arrays formats
the arrays of a round-trip TOML document, all or at given key paths.
Dataclasses
from dataclasses import dataclass
from rn_forge.commons import DataclassMixin
@dataclass
class User(DataclassMixin):
name: str
active: bool = True
user = User.from_dict({"name": "Alice"})
payload = user.to_json()
from_dict() is strict: User.from_dict({"name": "Alice", "active": "yes"})
raises AppException: Invalid User: wrong value type for field "active".
Subclass LenientDataclassMixin for the record that wants the value through
instead — and see that class's docstring for the two annotations dacite cannot
check, which force the same choice.
Unknown keys are ignored by default. Subclass StrictDataclassMixin for a
document whose author should hear about a typo: it rejects any key that names no
field, in nested sections too — whether or not the nested section's own class is
strict, since strictness belongs to the document being read — and names each one
by its dotted path —
AppException: Invalid ProjectConfig: unknown key(s) repository.archtype.