onyo.lib.commands module

onyo.lib.commands.fsck(repo, tests=None)[source]

Run integrity checks on an Onyo repository and its contents.

The following tests are available:

anchors: directories (outside of .onyo/) have an .anchor file
asset-yaml: asset YAML is valid
clean-tree: git reports no changed (staged or unstaged) or untracked files

Like Git, Onyo ignores files specified in .gitignore.

Parameters:

repo (OnyoRepo) – The repository on which to perform the fsck.
tests (list[str] | None (default: None)) – A list of tests to run. By default, all tests are run.

Raises:

ValueError – A specified test does not exist.
OnyoInvalidRepoError – One or more tests failed.

Return type:

None

onyo.lib.commands.onyo_config(inventory, config_args)[source]

Set, query, and unset Onyo repository configuration options.

Arguments are passed through directly to git config. Those that change the config file location (such as --system) are not allowed.

Parameters:

inventory (Inventory) – The Inventory to configure.
config_args (list[str]) – Options and arguments to pass to the underlying call of git config.

Return type:

None

onyo.lib.commands.onyo_edit(inventory, paths, message, auto_message=None)[source]

Edit the content of assets.

Parameters:

inventory (Inventory) – The Inventory containing the assets to edit.
paths (list[Path]) – Paths of assets to edit.
message (str | None) – Commit message to append to the auto-generated message.
auto_message (bool | None (default: None)) – Generate a commit-message subject line. If None, lookup the config value from onyo.commit.auto-message.

Raises:

ValueError – paths is empty or contains a path to a non-asset.

Return type:

None

onyo.lib.commands.onyo_get(inventory, include=None, exclude=None, depth=0, machine_readable=False, match=None, keys=None, sort=None, types=None)[source]

Query the key-values of inventory items.

All keys, both on-disk YAML and onyo.lib.pseudokeys.PSEUDO-KEYS, can be queried, matched, and sorted. Dictionary subkeys are addressed using a period (e.g. model.name).

Parameters:

inventory (Inventory) – The Inventory to query.
include (list[Path] | None (default: None)) –
Paths under which to query. Default is inventory root.

Passed to onyo.lib.inventory.Inventory.get_items().
exclude (list[Path] | Path | None (default: None)) –
Paths to exclude (i.e. results underneath will not be returned).

Passed to onyo.lib.inventory.Inventory.get_items().
depth (int (default: 0)) –
Number of levels to descend into the directories specified by include. A depth of 0 descends recursively without limit.

Passed to onyo.lib.inventory.Inventory.get_items().
machine_readable (bool (default: False)) – Print results in a machine-friendly format (no headers; separate values with a single tab) rather than a human-friendly output (headers and padded whitespace to align columns).
match (list[Callable[[dict], bool]] | list[list[Callable[[dict], bool]]] | None (default: None)) –
Callables suited for use with builtin filter(). They are passed an onyo.lib.items.Item and are expected to return a bool. All keys can be matched, and are not limited to those specified by keys.

Within a list of Callables, all must return True for an Item to match. When multiple lists are passed, only one list of Callables must match for an Item to match (e.g. each list of Callables is connected with a logical or).

Passed to onyo.lib.inventory.Inventory.get_items().
keys (list[str] | None (default: None)) – Keys to print the values of. Default is asset-name keys and path.
sort (dict[str, Literal['ascending', 'descending']] | None (default: None)) – Dictionary of keys to sort the resulting items. The value specifies which type of sort to use (onyo.lib.consts.SORT_ASCENDING and onyo.lib.consts.SORT_DESCENDING). They are applied in the order they are defined in the dictionary. All keys can be sorted, and are not limited to those specified by keys. Default is {'onyo.path.relative': SORT_ASCENDING}
types (list[Literal['assets', 'directories']] | None (default: None)) –
Types of inventory items to consider. Equivalent to onyo.is.asset=True and onyo.is.directory=True. Default is ['assets'].

Passed to onyo.lib.inventory.Inventory.get_items().

Raises:

ValueError – Invalid argument

Return type:

list[dict]

onyo.lib.commands.onyo_history(inventory, path, interactive=None)[source]

Display the history of a path.

Only one path is accepted due to git log --follow’s limitation.

Parameters:

inventory (Inventory) – The Inventory to display the history of.
path (Path) – Path to display the history of.
interactive (bool | None (default: None)) – Force interactive mode on/off. None autodetects if the TTY is interactive.

Raises:

ValueError – The configuration key is not set or the configured history program cannot be found by which.

Return type:

None

onyo.lib.commands.onyo_mkdir(inventory, dirs, message=None, auto_message=None)[source]

Create directories or convert Asset Files into Asset Directories.

Intermediate directories are created as needed (i.e. parent and child directories can be created in one call).

An empty .anchor file is added to each directory, to ensure that git tracks them even when empty.

If dirs contains a path that is already a directory or a protected path, then no new directories are created and an error is raised.

At least one path is required.

Parameters:

inventory (Inventory) – The Inventory in which to create directories or convert asset files.
dirs (list[Path]) – Paths of directories to create.
message (str | None (default: None)) – Commit message to append to the auto-generated message.
auto_message (bool | None (default: None)) – Generate a commit-message subject line. If None, lookup the config value from onyo.commit.auto-message.

Raises:

NoopError – dirs is empty.

Return type:

None

onyo.lib.commands.onyo_mv(inventory, source, destination, message=None, auto_message=None)[source]

Move assets and/or directories, or rename a directory.

If the destination is an asset file, it is converted into an Asset Directory first, and then the source(s) moved into it.

If a single source directory is given and the destination is a non-existing directory, the source will be renamed.

Parameters:

inventory (Inventory) – The Inventory in which to move assets and/or directories.
source (list[Path] | Path) – A list of source paths to move to destination.
destination (Path) – The path to which source(s) will be moved (or the new name, if a single source directory).
message (str | None (default: None)) – Commit message to append to the auto-generated message.
auto_message (bool | None (default: None)) – Generate a commit-message subject line. If None, lookup the config value from onyo.commit.auto-message.

Raises:

ValueError – If multiple source paths are specified to be renamed.

Return type:

None

onyo.lib.commands.onyo_new(inventory, directory=None, template=None, clone=None, keys=None, edit=False, message=None, auto_message=None)[source]

Create new assets and add them to the inventory.

Destination directories are created if they are missing.

Asset contents are populated in a waterfall pattern and can overwrite values from previous steps:

clone or template
keys
edit (i.e. manual user input)

The keys that comprise the asset filename are required (configured by onyo.assets.name-format).

Parameters:

inventory (Inventory) – The Inventory in which to create new assets.
directory (Path | None (default: None)) –
The directory to create new asset(s) in. This cannot be used with the directory Reserved Key.

If None and the directory Reserved Key is not found, it defaults to CWD.
template (Path | str | None (default: None)) –
Path to a template to populate the contents of new assets.

Relative paths are resolved relative to .onyo/templates.
clone (Path | None (default: None)) – Path of an asset to clone. Cannot be used with the template argument nor the template Reserved Key.
keys (list[Union[Dict, UserDict]] | None (default: None)) –
List of dictionaries with key/value pairs to set in the new assets.

Each key can be defined either 1 or N times (where N is the number of assets to be created). A key that is declared once will apply to all new assets, otherwise each will be applied to each new asset in the order they were declared.

Dictionary subkeys can be addressed using a period (e.g. model.name, model.year, etc.)
edit (bool (default: False)) – Open newly created assets in an editor before they are saved.
message (str | None (default: None)) – Commit message to append to the auto-generated message.
auto_message (bool | None (default: None)) – Generate a commit-message subject line. If None, lookup the config value from onyo.commit.auto-message.

Raises:

ValueError – If information is invalid, missing, or contradictory.

Return type:

None

onyo.lib.commands.onyo_rm(inventory, paths, message=None, recursive=False, auto_message=None)[source]

Delete assets and/or directories from an inventory.

Parameters:

inventory (Inventory) – The Inventory in which assets and/or directories will be deleted.
paths (list[Path] | Path) – Path or List of Paths of assets and/or directories to delete from the inventory. If any path is invalid or encounters a problem, none are deleted.
recursive (bool (default: False)) – Remove directories recursively.
message (str | None (default: None)) – Commit message to append to the auto-generated message.
auto_message (bool | None (default: None)) – Generate a commit-message subject line. If None, lookup the config value from onyo.commit.auto-message.

Return type:

None

onyo.lib.commands.onyo_rmdir(inventory, dirs, message=None, auto_message=None)[source]

Delete empty directories or convert empty Asset Directories into Asset Files.

If the directory does not exist, the path is protected, or the asset is already an Asset File, then an error is raised nothing is modified.

Parameters:

inventory (Inventory) – The Inventory in which to delete directories or convert asset directories.
dirs (list[Path] | Path) – Paths of directories to delete or convert.
message (str | None (default: None)) – Commit message to append to the auto-generated message.
auto_message (bool | None (default: None)) – Generate a commit-message subject line. If None, lookup the config value from onyo.commit.auto-message.

Raises:

NoopError – dirs is empty.

Return type:

None

onyo.lib.commands.onyo_set(inventory, keys, assets, message=None, auto_message=None)[source]

Set key-value pairs in assets.

Modifying the values of keys used in the asset name will rename the Asset File/Directory.

Parameters:

inventory (Inventory) – The Inventory in which to modify assets.
assets (list[Path]) – Paths of assets to modify.
keys (dict | UserDict) –
Key-value pairs to set in assets. Keys that already exist in an asset will have their their values overwritten. Keys that do not exist will be added and the value set.

Dictionary subkeys can be addressed using a period (e.g. model.name, model.year, etc.)
message (str | None (default: None)) – Commit message to append to the auto-generated message.
auto_message (bool | None (default: None)) – Generate a commit-message subject line. If None, lookup the config value from onyo.commit.auto-message.

Raises:

ValueError – If a given path is invalid or if keys is empty.

Return type:

str | None

onyo.lib.commands.onyo_show(inventory, paths, base)[source]

Serialize assets and/or directories into a multidocument YAML stream.

The same path can be given multiple times.

The filesystem hierarchy is encoded in pseudokeys (e.g. onyo.path.parent). Directories are included in the stream as needed.

Parameters:

inventory (Inventory) – The Inventory containing the paths to serialize.
paths (list[Path]) – Paths of assets and/or directories to serialize.
base (Path) – Base path that pseudokey-paths are relative to.

Raises:

ValueError – The paths is empty, base is unset, or a path is outside of the repository.

Return type:

None

onyo.lib.commands.onyo_tree(inventory, path, description=None, dirs_only=False)[source]

Print a directory’s child assets and directories in a tree-like format.

Parameters:

inventory (Inventory) – The Inventory in which the directory is located.
path (Path) – The directory to build a tree of.
description (str | None (default: None)) – The string to represent the root node. Usually the verbatim path requested by the user (relative, absolute, subdir, etc).
dirs_only (bool (default: False)) – Print only directories.

Raises:

ValueError – If path is not an inventory directory.

Return type:

None

onyo.lib.commands.onyo_tsv_to_yaml(tsv)[source]

Convert a TSV file to YAML.

Convert a tabular file (e.g. TSV, CSV) to YAML suitable for passing to onyo new and onyo set.

The header declares the key names to be populated. The values to populate documents are declared with one line per YAML document.

The output is printed to stdout as a multiple document YAML file (each document is separated by a --- line).

Parameters:: tsv (Path) – Path to a TSV file.
Raises:: ValueError – If information is invalid, missing, or contradictory.
Return type:: None

onyo.lib.commands.onyo_unset(inventory, keys, assets, message=None, auto_message=None)[source]

Remove keys from assets.

Keys that are used in asset names (see the onyo.assets.name-format configuration option) cannot be unset.

Parameters:

inventory (Inventory) – The Inventory in which to modify assets.
keys (Iterable[str]) –
List of keys to unset in assets.

Dictionary subkeys can be addressed using a period (e.g. model.name, model.year, etc.).
assets (list[Path]) – Paths of assets to modify.
message (str | None (default: None)) – Commit message to append to the auto-generated message.
auto_message (bool | None (default: None)) – Generate a commit-message subject line. If None, lookup the config value from onyo.commit.auto-message.

Raises:

ValueError – If assets contains invalid paths, keys is empty, or an keys in an asset’s name are attempted to be unset.

Return type:

None

onyo.lib.commands.raise_on_inventory_state(func)[source]

Raise if the Inventory state is unsafe to run an onyo command.

Decorator for Onyo commands. Requires an Inventory to be among the arguments of the decorated function.

Assesses whether the worktree is clean and there are no pending operations in an Inventory.

Return type:: Callable[[ParamSpec(P, bound= None)], TypeVar(T)]