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: |
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: |
None
|
keys
|
Mapping[str, Any] | None
|
Dotted key path to value, required for (and only valid on) a
:attr: |
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 |
__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
|
Returns:
| Type | Description |
|---|---|
dict[str, Any]
|
A dict mapping field names to their current values. Nested |
dict[str, Any]
|
dataclasses are recursively converted, respecting |
dict[str, Any]
|
metadata at every level. |
Raises:
| Type | Description |
|---|---|
TypeError
|
If the subclass was not decorated with
|
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 |
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 |
TypeError
|
If the subclass was not decorated with
|
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: |
None
|
**kwargs
|
Any
|
Additional keyword arguments forwarded to
:func: |
{}
|
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: |
{}
|
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
|
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: |
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: |
None
|
keys
|
Mapping[str, Any] | None
|
Dotted key path to value, required for (and only valid on) a
:attr: |
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 |
__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
|
Returns:
| Type | Description |
|---|---|
dict[str, Any]
|
A dict mapping field names to their current values. Nested |
dict[str, Any]
|
dataclasses are recursively converted, respecting |
dict[str, Any]
|
metadata at every level. |
Raises:
| Type | Description |
|---|---|
TypeError
|
If the subclass was not decorated with
|
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 |
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 |
TypeError
|
If the subclass was not decorated with
|
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: |
None
|
**kwargs
|
Any
|
Additional keyword arguments forwarded to
:func: |
{}
|
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: |
{}
|
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
|
block
|
ManagedBlock | None
|
The fenced block, for an ArtifactKind.BLOCK artifact. |
None
|
enabled
|
bool
|
|
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 |
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
|
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: |
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
|
required |
entries
|
Mapping[str, StateEntry] | None
|
The previous state, used to recover block markers for
:attr: |
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: |