Skip to content

Generation

rn_forge.commons.generation

Artifact classification and transactional generation APIs.

Action

Bases: StrEnum

What applying an artifact would do.

CONFLICT = 'conflict' class-attribute instance-attribute

Something exists at a managed path that this generator never wrote. Blocking.

CREATE = 'create' class-attribute instance-attribute

The file does not exist and will be written.

DELETE = 'delete' class-attribute instance-attribute

No longer rendered; the file will be backed up and removed.

DRIFT = 'drift' class-attribute instance-attribute

Disk differs from what was last applied — a hand edit. Blocking.

FORGET = 'forget' class-attribute instance-attribute

No longer rendered and nothing to remove; only the state entry goes.

INSERT = 'insert' class-attribute instance-attribute

The block or owned keys are absent and will be inserted; the rest of the file is untouched.

MISSING = 'missing' class-attribute instance-attribute

Recorded as applied, but gone from disk. Blocking.

REMOVE = 'remove' class-attribute instance-attribute

No longer rendered; the block or owned keys will be removed, the rest of the file untouched.

SKIP = 'skip' class-attribute instance-attribute

A seeded artifact that already exists; its content is never inspected.

UNCHANGED = 'unchanged' class-attribute instance-attribute

Disk, last-applied and freshly-rendered content all agree.

UPDATE = 'update' class-attribute instance-attribute

The rendered content differs from what was last applied.

ApplyResult(changes=(), backup_dir=None, dry_run=False) dataclass

What :func:apply did.

written property

Repo-relative write paths, once each in plan order; empty for dry runs.

Artifact(path, kind, content, block=None, keys=None) dataclass

One rendered artifact, ready to classify.

Parameters:

Name Type Description Default
path str

Repo-relative path of the file this artifact lives in.

required
kind ArtifactKind

See :class:ArtifactKind.

required
content str

The rendered content. For a block artifact this is the block body — what goes between the markers — not the whole file.

required
block ManagedBlock | None

The fenced block, required for (and only valid on) a :attr:ArtifactKind.BLOCK artifact.

None
keys Mapping[str, Any] | None

Dotted key path to value, required for (and only valid on) a :attr:ArtifactKind.KEYS artifact. A value is owned whole.

None

content_hash property

SHA-256 of :attr:content — for a block, of the body as written to disk.

A block body is re-terminated when rendered ("value" is written as "value\n"), so the hash is taken of what :meth:ManagedBlock.extract will read back; otherwise an untouched block would plan as drift.

key property

The artifact's state key: its path, plus the block name for a block.

to_entry()

The state entry recording this artifact as applied.

ArtifactKind

Bases: StrEnum

Who owns the bytes at an artifact's path.

BLOCK = 'block' class-attribute instance-attribute

The generator owns one fenced block inside a repository-owned file.

KEYS = 'keys' class-attribute instance-attribute

The generator owns named key paths inside a JSON or TOML document another program also writes.

MANAGED = 'managed' class-attribute instance-attribute

The generator owns the whole file.

SEEDED = 'seeded' class-attribute instance-attribute

Written once if absent, then owned by the repository.

Change(key, path, kind, action, artifact=None, approved=False, intent=None) dataclass

One planned change: an artifact (or a stale state entry) and its action.

effective_action property

The action to execute: :attr:intent once approved, else :attr:action.

intent = None class-attribute instance-attribute

What this change means to do, when :attr:action is a blocking classification that hides it. A stale entry whose file was hand-edited classifies as :attr:Action.DRIFT but still intends to delete the file or remove the block; approving the drift executes that intent instead of dropping the state entry and leaving the content behind.

is_blocking property

Whether this change stops the plan from being applied.

Generator

Bases: Protocol

A source of artifacts, callable as plain Python.

Implementations must not import a CLI framework and must not write to the working tree — rendering is pure, and :func:apply owns every write.

name property

Stable identifier for this generator, used in reporting.

generate(context)

Render every artifact this generator owns for context.

Plan(changes=()) dataclass

The classified result of rendering every artifact, before any write.

blocking property

Changes that must be approved (forced) before this plan can apply.

writes property

Changes that would touch the working tree, in apply order.

check()

Raise if this plan cannot be applied.

Raises:

Type Description
AppException

One or more changes are blocking and unapproved.

StateEntry(path, kind, content_hash=None, begin_marker=None, end_marker=None, key_paths=None) dataclass

Bases: DataclassMixin

One artifact as it was last applied, as recorded in the state file.

A seeded entry records presence only: hashing content the repository is supposed to edit would turn every legitimate edit into drift. A keys entry records :attr:key_paths, the sorted dotted paths the generator owned, so a later render that drops one can remove it.

__repr__()

Return an unambiguous ClassName(field=value, ...) representation.

Excluded fields (metadata={"exclude": True}) are omitted. Falls back to :func:object.__repr__ when the class is not a dataclass.

Returns:

Type Description
str

A string of the form ClassName(field1=value1, field2=value2).

__str__()

Return a JSON string representation of this instance.

Equivalent to calling :meth:to_json. Excluded fields are omitted.

Returns:

Type Description
str

A compact JSON string (no indentation).

as_dict(*, exclude_hidden=True)

Convert this dataclass instance to a plain dict.

Parameters:

Name Type Description Default
exclude_hidden bool

When True (default), fields decorated with metadata={"exclude": True} are omitted from the result, recursively throughout nested dataclasses. Pass False to include every field.

True

Returns:

Type Description
dict[str, Any]

A dict mapping field names to their current values. Nested

dict[str, Any]

dataclasses are recursively converted, respecting exclude

dict[str, Any]

metadata at every level.

Raises:

Type Description
TypeError

If the subclass was not decorated with @dataclasses.dataclass.

from_dict(data) classmethod

Create an instance from a dict, recursively rebuilding nested dataclasses.

Only keys that match declared dataclass field names are passed to the constructor. This makes from_dict tolerant of extra data (e.g. when loading from a config file that has fields added in a newer schema version). Nested dataclass-typed fields are reconstructed recursively for common container annotations, via :mod:dacite.

Note a nested dataclass field's own overridden from_dict (if any) is not called — dacite structures nested dataclasses itself.

Parameters:

Name Type Description Default
data dict[str, Any]

A dict whose keys correspond to dataclass field names. Unrecognised keys are silently ignored, or rejected when the class's __dacite_config__ sets strict.

required

Returns:

Type Description
Self

A new instance of this class populated with matching field values.

Raises:

Type Description
AppException

A value does not match its field's declared type, a required field is absent, or an enum-typed field names a member the enum does not define. Under strict, also a key that names no field, at any nesting level; the message lists every such key by its dotted path (repository.archtype).

TypeError

If the subclass was not decorated with @dataclasses.dataclass.

from_json(text) classmethod

Create an instance from a JSON string.

Delegates to :meth:from_dict after parsing, so unknown keys are ignored.

Parameters:

Name Type Description Default
text str

A JSON string representing a dict of field values.

required

Returns:

Type Description
Self

A new instance populated from the parsed JSON.

Raises:

Type Description
JSONDecodeError

If text is not valid JSON.

from_yaml(text) classmethod

Create an instance from a YAML string.

Delegates to :meth:from_dict after parsing, so unknown keys are ignored.

Parameters:

Name Type Description Default
text str

A YAML string representing a mapping of field values.

required

Returns:

Type Description
Self

A new instance populated from the parsed YAML.

Raises:

Type Description
YAMLError

If text is not valid YAML.

to_json(*, indent=None, **kwargs)

Serialise this instance to a JSON string.

Fields excluded via metadata={"exclude": True} are omitted.

Parameters:

Name Type Description Default
indent str | int | None

Indentation level passed to :func:json.dumps. None produces compact output.

None
**kwargs Any

Additional keyword arguments forwarded to :func:json.dumps.

{}

Returns:

Type Description
str

A JSON string representation of this instance.

to_yaml(**kwargs)

Serialise this instance to a YAML string.

Fields excluded via metadata={"exclude": True} are omitted.

Parameters:

Name Type Description Default
**kwargs Any

Additional keyword arguments forwarded to :meth:~rn_forge.commons.fs.documents.YamlUtils.serialize (e.g. sort_keys, default_flow_style).

{}

Returns:

Type Description
str

A YAML string representation of this instance.

classify(root, artifact, entry)

Return the :class:Action applying artifact would take.

Parameters:

Name Type Description Default
root Path

The repository root; artifact's path is relative to it.

required
artifact Artifact

The freshly-rendered artifact.

required
entry StateEntry | None

What was recorded the last time this artifact was applied, or None if it never was.

required

diff(root, change, *, entries=None)

A unified diff from change's content on disk to its rendered content.

A block diffs its body; a missing file diffs from empty; a keys change diffs the whole file, with entries (the previous state) showing dropped paths as removed. Returns "" when the change has no artifact or nothing differs.

disk_content(root, artifact)

The artifact's current content on disk (block body for a block), or None.

Artifacts

rn_forge.commons.generation.artifacts

Artifact, action, plan, and result models for file generation.

Action

Bases: StrEnum

What applying an artifact would do.

CONFLICT = 'conflict' class-attribute instance-attribute

Something exists at a managed path that this generator never wrote. Blocking.

CREATE = 'create' class-attribute instance-attribute

The file does not exist and will be written.

DELETE = 'delete' class-attribute instance-attribute

No longer rendered; the file will be backed up and removed.

DRIFT = 'drift' class-attribute instance-attribute

Disk differs from what was last applied — a hand edit. Blocking.

FORGET = 'forget' class-attribute instance-attribute

No longer rendered and nothing to remove; only the state entry goes.

INSERT = 'insert' class-attribute instance-attribute

The block or owned keys are absent and will be inserted; the rest of the file is untouched.

MISSING = 'missing' class-attribute instance-attribute

Recorded as applied, but gone from disk. Blocking.

REMOVE = 'remove' class-attribute instance-attribute

No longer rendered; the block or owned keys will be removed, the rest of the file untouched.

SKIP = 'skip' class-attribute instance-attribute

A seeded artifact that already exists; its content is never inspected.

UNCHANGED = 'unchanged' class-attribute instance-attribute

Disk, last-applied and freshly-rendered content all agree.

UPDATE = 'update' class-attribute instance-attribute

The rendered content differs from what was last applied.

ApplyResult(changes=(), backup_dir=None, dry_run=False) dataclass

What :func:apply did.

written property

Repo-relative write paths, once each in plan order; empty for dry runs.

Artifact(path, kind, content, block=None, keys=None) dataclass

One rendered artifact, ready to classify.

Parameters:

Name Type Description Default
path str

Repo-relative path of the file this artifact lives in.

required
kind ArtifactKind

See :class:ArtifactKind.

required
content str

The rendered content. For a block artifact this is the block body — what goes between the markers — not the whole file.

required
block ManagedBlock | None

The fenced block, required for (and only valid on) a :attr:ArtifactKind.BLOCK artifact.

None
keys Mapping[str, Any] | None

Dotted key path to value, required for (and only valid on) a :attr:ArtifactKind.KEYS artifact. A value is owned whole.

None

content_hash property

SHA-256 of :attr:content — for a block, of the body as written to disk.

A block body is re-terminated when rendered ("value" is written as "value\n"), so the hash is taken of what :meth:ManagedBlock.extract will read back; otherwise an untouched block would plan as drift.

key property

The artifact's state key: its path, plus the block name for a block.

to_entry()

The state entry recording this artifact as applied.

ArtifactKind

Bases: StrEnum

Who owns the bytes at an artifact's path.

BLOCK = 'block' class-attribute instance-attribute

The generator owns one fenced block inside a repository-owned file.

KEYS = 'keys' class-attribute instance-attribute

The generator owns named key paths inside a JSON or TOML document another program also writes.

MANAGED = 'managed' class-attribute instance-attribute

The generator owns the whole file.

SEEDED = 'seeded' class-attribute instance-attribute

Written once if absent, then owned by the repository.

Change(key, path, kind, action, artifact=None, approved=False, intent=None) dataclass

One planned change: an artifact (or a stale state entry) and its action.

effective_action property

The action to execute: :attr:intent once approved, else :attr:action.

intent = None class-attribute instance-attribute

What this change means to do, when :attr:action is a blocking classification that hides it. A stale entry whose file was hand-edited classifies as :attr:Action.DRIFT but still intends to delete the file or remove the block; approving the drift executes that intent instead of dropping the state entry and leaving the content behind.

is_blocking property

Whether this change stops the plan from being applied.

Generator

Bases: Protocol

A source of artifacts, callable as plain Python.

Implementations must not import a CLI framework and must not write to the working tree — rendering is pure, and :func:apply owns every write.

name property

Stable identifier for this generator, used in reporting.

generate(context)

Render every artifact this generator owns for context.

Plan(changes=()) dataclass

The classified result of rendering every artifact, before any write.

blocking property

Changes that must be approved (forced) before this plan can apply.

writes property

Changes that would touch the working tree, in apply order.

check()

Raise if this plan cannot be applied.

Raises:

Type Description
AppException

One or more changes are blocking and unapproved.

StateEntry(path, kind, content_hash=None, begin_marker=None, end_marker=None, key_paths=None) dataclass

Bases: DataclassMixin

One artifact as it was last applied, as recorded in the state file.

A seeded entry records presence only: hashing content the repository is supposed to edit would turn every legitimate edit into drift. A keys entry records :attr:key_paths, the sorted dotted paths the generator owned, so a later render that drops one can remove it.

__repr__()

Return an unambiguous ClassName(field=value, ...) representation.

Excluded fields (metadata={"exclude": True}) are omitted. Falls back to :func:object.__repr__ when the class is not a dataclass.

Returns:

Type Description
str

A string of the form ClassName(field1=value1, field2=value2).

__str__()

Return a JSON string representation of this instance.

Equivalent to calling :meth:to_json. Excluded fields are omitted.

Returns:

Type Description
str

A compact JSON string (no indentation).

as_dict(*, exclude_hidden=True)

Convert this dataclass instance to a plain dict.

Parameters:

Name Type Description Default
exclude_hidden bool

When True (default), fields decorated with metadata={"exclude": True} are omitted from the result, recursively throughout nested dataclasses. Pass False to include every field.

True

Returns:

Type Description
dict[str, Any]

A dict mapping field names to their current values. Nested

dict[str, Any]

dataclasses are recursively converted, respecting exclude

dict[str, Any]

metadata at every level.

Raises:

Type Description
TypeError

If the subclass was not decorated with @dataclasses.dataclass.

from_dict(data) classmethod

Create an instance from a dict, recursively rebuilding nested dataclasses.

Only keys that match declared dataclass field names are passed to the constructor. This makes from_dict tolerant of extra data (e.g. when loading from a config file that has fields added in a newer schema version). Nested dataclass-typed fields are reconstructed recursively for common container annotations, via :mod:dacite.

Note a nested dataclass field's own overridden from_dict (if any) is not called — dacite structures nested dataclasses itself.

Parameters:

Name Type Description Default
data dict[str, Any]

A dict whose keys correspond to dataclass field names. Unrecognised keys are silently ignored, or rejected when the class's __dacite_config__ sets strict.

required

Returns:

Type Description
Self

A new instance of this class populated with matching field values.

Raises:

Type Description
AppException

A value does not match its field's declared type, a required field is absent, or an enum-typed field names a member the enum does not define. Under strict, also a key that names no field, at any nesting level; the message lists every such key by its dotted path (repository.archtype).

TypeError

If the subclass was not decorated with @dataclasses.dataclass.

from_json(text) classmethod

Create an instance from a JSON string.

Delegates to :meth:from_dict after parsing, so unknown keys are ignored.

Parameters:

Name Type Description Default
text str

A JSON string representing a dict of field values.

required

Returns:

Type Description
Self

A new instance populated from the parsed JSON.

Raises:

Type Description
JSONDecodeError

If text is not valid JSON.

from_yaml(text) classmethod

Create an instance from a YAML string.

Delegates to :meth:from_dict after parsing, so unknown keys are ignored.

Parameters:

Name Type Description Default
text str

A YAML string representing a mapping of field values.

required

Returns:

Type Description
Self

A new instance populated from the parsed YAML.

Raises:

Type Description
YAMLError

If text is not valid YAML.

to_json(*, indent=None, **kwargs)

Serialise this instance to a JSON string.

Fields excluded via metadata={"exclude": True} are omitted.

Parameters:

Name Type Description Default
indent str | int | None

Indentation level passed to :func:json.dumps. None produces compact output.

None
**kwargs Any

Additional keyword arguments forwarded to :func:json.dumps.

{}

Returns:

Type Description
str

A JSON string representation of this instance.

to_yaml(**kwargs)

Serialise this instance to a YAML string.

Fields excluded via metadata={"exclude": True} are omitted.

Parameters:

Name Type Description Default
**kwargs Any

Additional keyword arguments forwarded to :meth:~rn_forge.commons.fs.documents.YamlUtils.serialize (e.g. sort_keys, default_flow_style).

{}

Returns:

Type Description
str

A YAML string representation of this instance.

block_from_entry(entry)

Reconstruct the block a state entry recorded, from its exact markers.

canonical_values(values)

The canonical JSON form of a {key path: value} mapping, for hashing.

disk_key_values(root, relative, key_paths)

The values relative holds at key_paths; an absent path is left out.

read_text(path)

Read path without translating its newlines, or "" when it is absent.

:meth:pathlib.Path.read_text opens in universal-newline mode, which silently rewrites a CRLF file as LF — so a read/modify/write cycle would reformat every line of a file this engine only owns a block of. Reading with newline="" keeps the bytes as they are.

render_keys(root, change, previous)

The text of a keys file with change applied, leaving other keys alone.

Sets every owned path unless the change removes them, and deletes the paths a previous keys entry recorded that the artifact no longer owns.

Raises:

Type Description
AppException

An owned path runs through a non-table on disk.

resolve_within(root, relative)

Resolve a repo-relative artifact path, refusing anything outside root.

Guards the declared escape (../../.ssh/config, an absolute path) and the symlink escape (a path whose parent resolves outside the repository) alike. Called before staging and again before the file is touched, since the tree can change between the two.

Raises:

Type Description
AppException

relative is absolute or resolves outside root.

Templated

rn_forge.commons.generation.templated

Artifacts rendered from Jinja templates.

TemplateArtifact(path, kind=ArtifactKind.MANAGED, template=None, block=None, enabled=True, context=None) dataclass

One artifact to render: its path, its ownership and its template.

Parameters:

Name Type Description Default
path str

Repo-relative path of the rendered artifact.

required
kind ArtifactKind

Who owns its bytes; see ArtifactKind.

MANAGED
template str | None

Template name; None means f"{path}.j2".

None
block ManagedBlock | None

The fenced block, for an ArtifactKind.BLOCK artifact.

None
enabled bool

False leaves the artifact out.

True
context Mapping[str, object] | None

Replaces the shared context for this artifact alone.

None

render_artifacts(engine, context, artifacts)

Render each enabled artifact, in order.

Raises:

Type Description
RenderError

A template failed; the message starts with the artifact's path.

ValueError

From Artifact, when block does not match kind.

Plan

rn_forge.commons.generation.plan

Classify generated artifacts without modifying the working tree.

classify(root, artifact, entry)

Return the :class:Action applying artifact would take.

Parameters:

Name Type Description Default
root Path

The repository root; artifact's path is relative to it.

required
artifact Artifact

The freshly-rendered artifact.

required
entry StateEntry | None

What was recorded the last time this artifact was applied, or None if it never was.

required

diff(root, change, *, entries=None)

A unified diff from change's content on disk to its rendered content.

A block diffs its body; a missing file diffs from empty; a keys change diffs the whole file, with entries (the previous state) showing dropped paths as removed. Returns "" when the change has no artifact or nothing differs.

disk_content(root, artifact)

The artifact's current content on disk (block body for a block), or None.

plan(root, artifacts, entries, *, force=())

Classify every artifact and every stale state entry, writing nothing.

Parameters:

Name Type Description Default
root str | Path

The repository root.

required
artifacts Iterable[Artifact]

Every artifact the generators produced for this run.

required
entries Mapping[str, StateEntry]

The state recorded by the previous apply, keyed by :attr:Artifact.key.

required
force Iterable[str]

Repo-relative paths (or artifact keys) whose blocking action the caller has explicitly approved.

()

Apply

rn_forge.commons.generation.apply

Transactional application of generation plans.

apply(root, planned, store, *, staging_dir, backup_dir, entries=None, verify=None, dry_run=False)

Apply planned transactionally: stage everything, then swap it in.

Every new file is rendered into staging_dir and every file about to be overwritten or deleted is copied under a timestamped directory in backup_dir before the first replacement happens. If any write, or the verify callback, raises, the working tree and the state file are restored to what they were.

Parameters:

Name Type Description Default
root str | Path

The repository root.

required
planned Plan

The plan to apply. Checked first; an unapproved blocking change aborts before anything is written.

required
store StateStore[StateEntry]

Where the applied state is recorded. Written last, and excluded from the artifacts it records — a state file that hashed itself could never be consistent.

required
staging_dir str | Path

Directory rendered content is staged into. Derived data; callers gitignore it.

required
backup_dir str | Path

Directory backups are written under, as <backup_dir>/<UTC timestamp>/<repo-relative path>.

required
entries Mapping[str, StateEntry] | None

The previous state, used to recover block markers for :attr:Action.REMOVE. Defaults to store.load().

None
verify Callable[[], None] | None

Called after every write and before the state file is written. Raise from it to roll the whole apply back.

None
dry_run bool

Classify and report, write nothing.

False

Raises:

Type Description
AppException

The plan has unapproved blocking changes, an artifact path escapes root, or a write failed (after the working tree has been restored).

BaseException

An interruption (:exc:KeyboardInterrupt, :exc:SystemExit) during the apply is re-raised unchanged, once the working tree and the state file have been restored. Converting it to an :class:AppException would let a caller catch it and carry on as though the run had merely failed.