Install
rn_forge.tooling.install
Release sources, workstation installation, and lifecycle operations.
Check = Callable[[ToolHome], Iterable[Finding]]
module-attribute
A product-specific doctor check: inspect the install, report what is true of it.
Report a passing check as an info finding rather than nothing, so doctor
shows that it ran.
CleanupResult(product, kept, removed=list[str](), dry_run=False)
dataclass
Bases: DataclassMixin
What cleanup removed, or would remove.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
product
|
str
|
The product name. |
required |
kept
|
str
|
The active version. |
required |
removed
|
list[str]
|
The versions removed — or, on a dry run, to be removed. |
list[str]()
|
dry_run
|
bool
|
Whether anything was actually removed. |
False
|
__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. |
EnvWrite
Bases: StrEnum
What :func:write_env did.
CURRENT = 'current'
class-attribute
instance-attribute
The file has the same or a newer schema, and was left alone.
FOREIGN = 'foreign'
class-attribute
instance-attribute
The file has no schema line, so it is not ours, and was left alone.
WRITTEN = 'written'
class-attribute
instance-attribute
The file was missing or older, and was written.
GitHubReleases(repo, tag_prefix='v', api_url='https://api.github.com', web_url='https://github.com')
dataclass
Releases published as tags of a GitHub repository.
The archive is GitHub's generated source tarball for the tag. GitHub
publishes no checksum for those, so :meth:checksum returns None and
the download is trusted to TLS; a product that attaches a checksum asset
to its releases implements :class:ReleaseSource to verify it.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
repo
|
str
|
|
required |
tag_prefix
|
str
|
What the tag carries before the version — |
'v'
|
api_url
|
str
|
The GitHub API root, for GitHub Enterprise. |
'https://api.github.com'
|
web_url
|
str
|
The GitHub web root the tarball is served from. |
'https://github.com'
|
checksum(version)
None: GitHub publishes no checksum for a generated tarball.
download(version, destination)
Download the tag's source tarball into destination.
Raises:
| Type | Description |
|---|---|
AppException
|
The download failed. |
download_commit(sha, destination)
Download the source tarball of commit sha into destination.
Raises:
| Type | Description |
|---|---|
AppException
|
The download failed. |
latest()
Return the version of the repository's latest release.
Raises:
| Type | Description |
|---|---|
AppException
|
The request failed, or the latest release's tag does
not carry :attr: |
resolve(ref)
Return the 40-character commit SHA that a branch, tag or SHA names.
Raises:
| Type | Description |
|---|---|
AppException
|
The request failed, the ref does not exist, or the response carries no valid SHA. |
InstallResult(product, outcome, version=None, previous=None, env=None, hint=None)
dataclass
Bases: DataclassMixin
What install, upgrade or uninstall did.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
product
|
str
|
The product name. |
required |
outcome
|
str
|
|
required |
version
|
str | None
|
The version now active, when there is one. |
None
|
previous
|
str | None
|
The version that was active before, when there was one. |
None
|
env
|
str | None
|
What the install did to |
None
|
hint
|
str | None
|
How to source |
None
|
__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. |
InstallStatus(product, version, home, installed=None, versions=list[str](), ref=None, commit=None, package_version=None)
dataclass
Bases: DataclassMixin
Where a product is installed, and at what version.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
product
|
str
|
The product name. |
required |
version
|
str
|
The version of the running code. |
required |
home
|
str
|
The product's directory. |
required |
installed
|
str | None
|
The version |
None
|
versions
|
list[str]
|
Every version directory present. |
list[str]()
|
ref
|
str | None
|
What the install was asked for: a branch, tag or commit SHA, or
the release tag. |
None
|
commit
|
str | None
|
The installed commit's SHA for a ref install, else |
None
|
package_version
|
str | None
|
The package version recorded at install, or |
None
|
__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. |
Link(path, target)
dataclass
A symlink an install puts in place outside the version directory.
The link points through current, never at a version directory, so an
upgrade swaps what it resolves to without touching the link.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
path
|
str
|
Where the link goes, relative to |
required |
target
|
str
|
What it points at, relative to the installed version's root. |
required |
LocalArchive(path, version, sha256=None)
dataclass
One archive already on disk, standing in for a release.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
path
|
Path
|
The archive file. |
required |
version
|
str
|
The version the archive holds. Not inferred from its contents: reading a version out of a tree is the product's convention, not this module's. |
required |
sha256
|
str | None
|
The digest to verify against, when known. |
None
|
checksum(version)
The digest given at construction, if any.
download(version, destination)
Copy the archive into destination.
Raises:
| Type | Description |
|---|---|
AppException
|
version is not the archive's, or the file is missing. |
latest()
The archive's own version — it is the only one there is.
PythonTool(name, version, repo=None, release_source=None, state_schema_version=1)
dataclass
Bases: ToolProduct
A Python tool installed with uv tool install.
The package must declare a console script named :attr:name, and that
script must be a Typer (or Click) command: the build asks it for its zsh
completion script. uv must be on PATH; it is a program, not a
dependency.
source
property
The release source to fetch from.
Raises:
| Type | Description |
|---|---|
AppException
|
Neither release_source nor repo was given. |
artifacts()
The links bin/<name> to the console script and completions/_<name>.
build(release_root, version_dir)
Install the package at release_root into version_dir.
The console script ends up at <version_dir>/bin/<name> and its zsh
completion script at <version_dir>/completions/_<name>.
Raises:
| Type | Description |
|---|---|
AppException
|
|
checks()
Product-specific doctor checks. Default: none.
migrate(frm, to)
Move the product's state from version frm to version to. Default: nothing.
Runs after the new version is built and before it is activated. Raise to abandon the install; the previous version stays active.
preflight()
ReleaseSource
Bases: Protocol
Where a product's releases are published.
checksum(version)
Return the SHA-256 hex digest version's archive must match, if published.
download(version, destination)
Write the archive for version into the directory destination.
Returns:
| Type | Description |
|---|---|
Path
|
The archive file. |
latest()
Return the newest released version.
ToolHome(name, root=None)
The on-disk layout of one product under $RNF_HOME.
Initialize :class:ToolHome.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
name
|
str
|
The product name; its directory under root. |
required |
root
|
str | Path | None
|
The home directory. Defaults to :func: |
None
|
Raises:
| Type | Description |
|---|---|
AppException
|
name is not a single path segment. |
completions_dir
property
<home>/completions/.
current
property
The current symlink. May not exist.
env_path
property
<home>/env.sh, owned by the home rather than the product.
product_dir
property
<home>/<product>/.
state_path
property
<home>/<product>/state.json.
versions_dir
property
<home>/<product>/versions/.
work_dir
property
Scratch space holding unique transaction directories.
A failed restoration retains its displaced version here; cleanup keeps it.
activate(version)
Point current at version, atomically.
The link is relative (versions/<version>), so moving the whole home
does not break it.
current_version()
The version current points at, or None when there is no link.
installed_versions()
Every version directory present, in name order.
lock(*, timeout=30.0)
The lock every lifecycle verb that writes holds for its whole duration.
version_dir(version)
<home>/<product>/versions/<version>/.
Raises:
| Type | Description |
|---|---|
AppException
|
version is not a single path segment — a release
source is remote input, and |
ToolProduct(name, version, repo=None, release_source=None, state_schema_version=1)
dataclass
An installable tool, as the lifecycle verbs see it.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
name
|
str
|
The product's name, and its directory under |
required |
version
|
str
|
The version of the running code — normally the package's
|
required |
repo
|
str | None
|
|
None
|
release_source
|
ReleaseSource | None
|
Where releases come from. Defaults to
:class: |
None
|
state_schema_version
|
int
|
The version of whatever state the product keeps
under its home. |
1
|
source
property
The release source to fetch from.
Raises:
| Type | Description |
|---|---|
AppException
|
Neither release_source nor repo was given. |
artifacts()
What an install puts in place beside the version directory. Default: nothing.
build(release_root, version_dir)
Turn an extracted release into an installed version directory.
The default copies the release tree. Implementations that create path-dependent artifacts must build them directly in version_dir.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
release_root
|
Path
|
The extracted release's root directory. |
required |
version_dir
|
Path
|
The directory to populate. Does not exist yet. |
required |
checks()
Product-specific doctor checks. Default: none.
migrate(frm, to)
Move the product's state from version frm to version to. Default: nothing.
Runs after the new version is built and before it is activated. Raise to abandon the install; the previous version stays active.
preflight()
Called by install before anything is written. Default: nothing.
Raises:
| Type | Description |
|---|---|
AppException
|
To refuse the install. |
cleanup(product, *, home=None, dry_run=False)
Remove every installed version except the active one, and leftover scratch space.
Raises:
| Type | Description |
|---|---|
AppException
|
There is no active version to keep. |
doctor(product, *, home=None)
Inspect the install, then run the product's own checks.
A product that is not installed is a warning, not an error: the same
command runs from a development checkout, where there is nothing under
$RNF_HOME and nothing wrong. The home.* rows are warnings for the
same reason: a development checkout has no hooked-up home. Both they and
the product's checks run either way.
Returns:
| Type | Description |
|---|---|
list[Finding]
|
Every finding, product checks last. Only an |
list[Finding]
|
command. |
env_hint(root)
Return how to source env.sh, or None when <root>/bin is on PATH.
env_schema(root)
Return the schema number on the first line of <root>/env.sh.
Returns:
| Type | Description |
|---|---|
int | None
|
The number, or |
int | None
|
line is not the schema line, so the file is not ours. |
extract_archive(archive, destination, *, filter='data')
Extract a .tar/.zip archive into destination, returning its root dir.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
archive
|
str | Path
|
The archive file. Tar formats ( |
required |
destination
|
str | Path
|
Directory the archive's contents are extracted into. Created if absent. |
required |
filter
|
Literal['data', 'tar', 'fully_trusted']
|
The :func: |
'data'
|
Returns:
| Type | Description |
|---|---|
Path
|
The single top-level directory the archive extracted into. |
Raises:
| Type | Description |
|---|---|
AppException
|
The archive's root does not contain exactly one directory. |
fetch_release(source, version, workdir)
Download version from source into workdir, verify it, and extract it.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
source
|
ReleaseSource
|
Where the release is published. |
required |
version
|
str
|
The version to fetch. |
required |
workdir
|
str | Path
|
A scratch directory; created if absent. The archive and its extracted tree are left here for the caller to clean up. |
required |
Returns:
| Type | Description |
|---|---|
Path
|
The archive's single root directory. |
Raises:
| Type | Description |
|---|---|
AppException
|
The download failed, the archive does not match the published checksum, or it does not have exactly one root directory. |
install(product, *, version=None, source=None, home=None, force=False, ref=None)
Install version of product, or the commit ref names, and make it active.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
product
|
ToolProduct
|
The product to install. |
required |
version
|
str | None
|
The version to install. Defaults to the source's latest. Not combined with ref. |
None
|
source
|
ReleaseSource | None
|
Where to fetch from. Defaults to |
None
|
home
|
ToolHome | None
|
The home to install into. Defaults to the product's. |
None
|
force
|
bool
|
Reinstall even when version is already active. |
False
|
ref
|
str | None
|
A branch, tag or commit SHA of the source's GitHub repository. The install is recorded under the first 12 characters of the commit. |
None
|
Raises:
| Type | Description |
|---|---|
AppException
|
Both version and ref were given, ref was given
for a source that is not a :class: |
BaseException
|
An interruption, re-raised after recovery with any recovery failures and retained path logged at error level. |
rnf_home()
Return $RNF_HOME, or ~/.rn-forge when it is unset or empty.
status(product, *, home=None)
Report the running version and what is installed. Writes nothing.
uninstall(product, *, home=None)
Remove the product's links and its whole directory under the home.
Works over an install that never completed: nothing here assumes
current or state.json exists. A link is removed only when it still
points where this product put it — a path someone has since replaced with
their own file or link is left alone.
upgrade(product, *, source=None, home=None)
Move an existing install forward.
A ref install re-resolves its recorded ref and installs that commit, or
returns already-current when it has not moved. Any other install moves
to the source's latest version.
Raises:
| Type | Description |
|---|---|
AppException
|
The product is not installed, or the install failed. |
write_env(root)
Write <root>/env.sh when it is missing or names a lower schema.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
root
|
Path
|
The home directory; created when absent. |
required |
Returns:
| Type | Description |
|---|---|
EnvWrite
|
Which case applied. A file with the same or a higher schema, or with no |
EnvWrite
|
schema line, is left unchanged. |
Home
rn_forge.tooling.install.home
Filesystem layout and activation for installed tools.
DEFAULT_RNF_HOME = '~/.rn-forge'
module-attribute
The home used when :data:RNF_HOME_ENV is unset or empty.
ENV_SCHEMA = 1
module-attribute
The schema number of the env.sh this package writes.
ENV_TEMPLATE = '# rn-forge home environment, schema 1. Written by rn-forge installers; do not edit.\n# Source it from your shell\'s rc file, before compinit: source "<home>/env.sh"\nexport RNF_HOME="<home>"\ncase ":${PATH}:" in\n *":${RNF_HOME}/bin:"*) ;;\n *) export PATH="${RNF_HOME}/bin:${PATH}" ;;\nesac\nif [ -n "${ZSH_VERSION:-}" ]; then\n fpath=("${RNF_HOME}/completions" "${fpath[@]}")\nfi\n'
module-attribute
The env.sh text, with <home> standing for the home's absolute path.
RNF_HOME_ENV = 'RNF_HOME'
module-attribute
The environment variable that relocates every installed tool.
EnvWrite
Bases: StrEnum
What :func:write_env did.
CURRENT = 'current'
class-attribute
instance-attribute
The file has the same or a newer schema, and was left alone.
FOREIGN = 'foreign'
class-attribute
instance-attribute
The file has no schema line, so it is not ours, and was left alone.
WRITTEN = 'written'
class-attribute
instance-attribute
The file was missing or older, and was written.
ToolHome(name, root=None)
The on-disk layout of one product under $RNF_HOME.
Initialize :class:ToolHome.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
name
|
str
|
The product name; its directory under root. |
required |
root
|
str | Path | None
|
The home directory. Defaults to :func: |
None
|
Raises:
| Type | Description |
|---|---|
AppException
|
name is not a single path segment. |
completions_dir
property
<home>/completions/.
current
property
The current symlink. May not exist.
env_path
property
<home>/env.sh, owned by the home rather than the product.
product_dir
property
<home>/<product>/.
state_path
property
<home>/<product>/state.json.
versions_dir
property
<home>/<product>/versions/.
work_dir
property
Scratch space holding unique transaction directories.
A failed restoration retains its displaced version here; cleanup keeps it.
activate(version)
Point current at version, atomically.
The link is relative (versions/<version>), so moving the whole home
does not break it.
current_version()
The version current points at, or None when there is no link.
installed_versions()
Every version directory present, in name order.
lock(*, timeout=30.0)
The lock every lifecycle verb that writes holds for its whole duration.
version_dir(version)
<home>/<product>/versions/<version>/.
Raises:
| Type | Description |
|---|---|
AppException
|
version is not a single path segment — a release
source is remote input, and |
env_hint(root)
Return how to source env.sh, or None when <root>/bin is on PATH.
env_schema(root)
Return the schema number on the first line of <root>/env.sh.
Returns:
| Type | Description |
|---|---|
int | None
|
The number, or |
int | None
|
line is not the schema line, so the file is not ours. |
render_env(root)
Return :data:ENV_TEMPLATE for the home at root, as an absolute path.
rnf_home()
Return $RNF_HOME, or ~/.rn-forge when it is unset or empty.
write_env(root)
Write <root>/env.sh when it is missing or names a lower schema.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
root
|
Path
|
The home directory; created when absent. |
required |
Returns:
| Type | Description |
|---|---|
EnvWrite
|
Which case applied. A file with the same or a higher schema, or with no |
EnvWrite
|
schema line, is left unchanged. |
Product
rn_forge.tooling.install.product
Product description consumed by tool lifecycle operations.
Check = Callable[[ToolHome], Iterable[Finding]]
module-attribute
A product-specific doctor check: inspect the install, report what is true of it.
Report a passing check as an info finding rather than nothing, so doctor
shows that it ran.
Link(path, target)
dataclass
A symlink an install puts in place outside the version directory.
The link points through current, never at a version directory, so an
upgrade swaps what it resolves to without touching the link.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
path
|
str
|
Where the link goes, relative to |
required |
target
|
str
|
What it points at, relative to the installed version's root. |
required |
ToolProduct(name, version, repo=None, release_source=None, state_schema_version=1)
dataclass
An installable tool, as the lifecycle verbs see it.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
name
|
str
|
The product's name, and its directory under |
required |
version
|
str
|
The version of the running code — normally the package's
|
required |
repo
|
str | None
|
|
None
|
release_source
|
ReleaseSource | None
|
Where releases come from. Defaults to
:class: |
None
|
state_schema_version
|
int
|
The version of whatever state the product keeps
under its home. |
1
|
source
property
The release source to fetch from.
Raises:
| Type | Description |
|---|---|
AppException
|
Neither release_source nor repo was given. |
artifacts()
What an install puts in place beside the version directory. Default: nothing.
build(release_root, version_dir)
Turn an extracted release into an installed version directory.
The default copies the release tree. Implementations that create path-dependent artifacts must build them directly in version_dir.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
release_root
|
Path
|
The extracted release's root directory. |
required |
version_dir
|
Path
|
The directory to populate. Does not exist yet. |
required |
checks()
Product-specific doctor checks. Default: none.
migrate(frm, to)
Move the product's state from version frm to version to. Default: nothing.
Runs after the new version is built and before it is activated. Raise to abandon the install; the previous version stays active.
preflight()
Called by install before anything is written. Default: nothing.
Raises:
| Type | Description |
|---|---|
AppException
|
To refuse the install. |
Python tool
rn_forge.tooling.install.python
A product whose release is a Python package with a console script.
PythonTool(name, version, repo=None, release_source=None, state_schema_version=1)
dataclass
Bases: ToolProduct
A Python tool installed with uv tool install.
The package must declare a console script named :attr:name, and that
script must be a Typer (or Click) command: the build asks it for its zsh
completion script. uv must be on PATH; it is a program, not a
dependency.
source
property
The release source to fetch from.
Raises:
| Type | Description |
|---|---|
AppException
|
Neither release_source nor repo was given. |
artifacts()
The links bin/<name> to the console script and completions/_<name>.
build(release_root, version_dir)
Install the package at release_root into version_dir.
The console script ends up at <version_dir>/bin/<name> and its zsh
completion script at <version_dir>/completions/_<name>.
Raises:
| Type | Description |
|---|---|
AppException
|
|
checks()
Product-specific doctor checks. Default: none.
migrate(frm, to)
Move the product's state from version frm to version to. Default: nothing.
Runs after the new version is built and before it is activated. Raise to abandon the install; the previous version stays active.
preflight()
Release
rn_forge.tooling.install.release
Release sources, download verification, and extraction.
GitHubReleases(repo, tag_prefix='v', api_url='https://api.github.com', web_url='https://github.com')
dataclass
Releases published as tags of a GitHub repository.
The archive is GitHub's generated source tarball for the tag. GitHub
publishes no checksum for those, so :meth:checksum returns None and
the download is trusted to TLS; a product that attaches a checksum asset
to its releases implements :class:ReleaseSource to verify it.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
repo
|
str
|
|
required |
tag_prefix
|
str
|
What the tag carries before the version — |
'v'
|
api_url
|
str
|
The GitHub API root, for GitHub Enterprise. |
'https://api.github.com'
|
web_url
|
str
|
The GitHub web root the tarball is served from. |
'https://github.com'
|
checksum(version)
None: GitHub publishes no checksum for a generated tarball.
download(version, destination)
Download the tag's source tarball into destination.
Raises:
| Type | Description |
|---|---|
AppException
|
The download failed. |
download_commit(sha, destination)
Download the source tarball of commit sha into destination.
Raises:
| Type | Description |
|---|---|
AppException
|
The download failed. |
latest()
Return the version of the repository's latest release.
Raises:
| Type | Description |
|---|---|
AppException
|
The request failed, or the latest release's tag does
not carry :attr: |
resolve(ref)
Return the 40-character commit SHA that a branch, tag or SHA names.
Raises:
| Type | Description |
|---|---|
AppException
|
The request failed, the ref does not exist, or the response carries no valid SHA. |
LocalArchive(path, version, sha256=None)
dataclass
One archive already on disk, standing in for a release.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
path
|
Path
|
The archive file. |
required |
version
|
str
|
The version the archive holds. Not inferred from its contents: reading a version out of a tree is the product's convention, not this module's. |
required |
sha256
|
str | None
|
The digest to verify against, when known. |
None
|
checksum(version)
The digest given at construction, if any.
download(version, destination)
Copy the archive into destination.
Raises:
| Type | Description |
|---|---|
AppException
|
version is not the archive's, or the file is missing. |
latest()
The archive's own version — it is the only one there is.
ReleaseSource
Bases: Protocol
Where a product's releases are published.
checksum(version)
Return the SHA-256 hex digest version's archive must match, if published.
download(version, destination)
Write the archive for version into the directory destination.
Returns:
| Type | Description |
|---|---|
Path
|
The archive file. |
latest()
Return the newest released version.
fetch_release(source, version, workdir)
Download version from source into workdir, verify it, and extract it.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
source
|
ReleaseSource
|
Where the release is published. |
required |
version
|
str
|
The version to fetch. |
required |
workdir
|
str | Path
|
A scratch directory; created if absent. The archive and its extracted tree are left here for the caller to clean up. |
required |
Returns:
| Type | Description |
|---|---|
Path
|
The archive's single root directory. |
Raises:
| Type | Description |
|---|---|
AppException
|
The download failed, the archive does not match the published checksum, or it does not have exactly one root directory. |
Lifecycle
rn_forge.tooling.install.lifecycle
Transactional install, upgrade, removal, status, and diagnostic operations.
CleanupResult(product, kept, removed=list[str](), dry_run=False)
dataclass
Bases: DataclassMixin
What cleanup removed, or would remove.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
product
|
str
|
The product name. |
required |
kept
|
str
|
The active version. |
required |
removed
|
list[str]
|
The versions removed — or, on a dry run, to be removed. |
list[str]()
|
dry_run
|
bool
|
Whether anything was actually removed. |
False
|
__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. |
InstallResult(product, outcome, version=None, previous=None, env=None, hint=None)
dataclass
Bases: DataclassMixin
What install, upgrade or uninstall did.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
product
|
str
|
The product name. |
required |
outcome
|
str
|
|
required |
version
|
str | None
|
The version now active, when there is one. |
None
|
previous
|
str | None
|
The version that was active before, when there was one. |
None
|
env
|
str | None
|
What the install did to |
None
|
hint
|
str | None
|
How to source |
None
|
__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. |
InstallStatus(product, version, home, installed=None, versions=list[str](), ref=None, commit=None, package_version=None)
dataclass
Bases: DataclassMixin
Where a product is installed, and at what version.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
product
|
str
|
The product name. |
required |
version
|
str
|
The version of the running code. |
required |
home
|
str
|
The product's directory. |
required |
installed
|
str | None
|
The version |
None
|
versions
|
list[str]
|
Every version directory present. |
list[str]()
|
ref
|
str | None
|
What the install was asked for: a branch, tag or commit SHA, or
the release tag. |
None
|
commit
|
str | None
|
The installed commit's SHA for a ref install, else |
None
|
package_version
|
str | None
|
The package version recorded at install, or |
None
|
__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. |
cleanup(product, *, home=None, dry_run=False)
Remove every installed version except the active one, and leftover scratch space.
Raises:
| Type | Description |
|---|---|
AppException
|
There is no active version to keep. |
doctor(product, *, home=None)
Inspect the install, then run the product's own checks.
A product that is not installed is a warning, not an error: the same
command runs from a development checkout, where there is nothing under
$RNF_HOME and nothing wrong. The home.* rows are warnings for the
same reason: a development checkout has no hooked-up home. Both they and
the product's checks run either way.
Returns:
| Type | Description |
|---|---|
list[Finding]
|
Every finding, product checks last. Only an |
list[Finding]
|
command. |
install(product, *, version=None, source=None, home=None, force=False, ref=None)
Install version of product, or the commit ref names, and make it active.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
product
|
ToolProduct
|
The product to install. |
required |
version
|
str | None
|
The version to install. Defaults to the source's latest. Not combined with ref. |
None
|
source
|
ReleaseSource | None
|
Where to fetch from. Defaults to |
None
|
home
|
ToolHome | None
|
The home to install into. Defaults to the product's. |
None
|
force
|
bool
|
Reinstall even when version is already active. |
False
|
ref
|
str | None
|
A branch, tag or commit SHA of the source's GitHub repository. The install is recorded under the first 12 characters of the commit. |
None
|
Raises:
| Type | Description |
|---|---|
AppException
|
Both version and ref were given, ref was given
for a source that is not a :class: |
BaseException
|
An interruption, re-raised after recovery with any recovery failures and retained path logged at error level. |
status(product, *, home=None)
Report the running version and what is installed. Writes nothing.
uninstall(product, *, home=None)
Remove the product's links and its whole directory under the home.
Works over an install that never completed: nothing here assumes
current or state.json exists. A link is removed only when it still
points where this product put it — a path someone has since replaced with
their own file or link is left alone.
upgrade(product, *, source=None, home=None)
Move an existing install forward.
A ref install re-resolves its recorded ref and installs that commit, or
returns already-current when it has not moved. Any other install moves
to the source's latest version.
Raises:
| Type | Description |
|---|---|
AppException
|
The product is not installed, or the install failed. |
Archive
rn_forge.tooling.install.archive
Safe extraction of single-root tar and zip release bundles.
extract_archive(archive, destination, *, filter='data')
Extract a .tar/.zip archive into destination, returning its root dir.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
archive
|
str | Path
|
The archive file. Tar formats ( |
required |
destination
|
str | Path
|
Directory the archive's contents are extracted into. Created if absent. |
required |
filter
|
Literal['data', 'tar', 'fully_trusted']
|
The :func: |
'data'
|
Returns:
| Type | Description |
|---|---|
Path
|
The single top-level directory the archive extracted into. |
Raises:
| Type | Description |
|---|---|
AppException
|
The archive's root does not contain exactly one directory. |