onyo.lib.commands module

onyo.lib.commands.fsck(repo, tests=None)

Run a suite of integrity checks on an Onyo repository and its contents.

By default, the following tests are performed:

• anchors: verify that all directories (outside of .onyo/) have an .anchor file

• asset-unique: verify that all asset names are unique

• asset-yaml: verify that all asset contents are valid YAML

• clean-tree: verify that git has no changed (staged or unstaged) or untracked files

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 – If a specified test does not exist.

• OnyoInvalidRepoError – If a test fails.

Return type:

None

onyo.lib.commands.move_asset_or_dir(inventory, source, destination)

Move a source asset or directory to a destination.

Parameters:

• inventory (Inventory) – Inventory to operate on.

• source (Path) – Path object to an asset or directory which to move to the destination.

• destination (Path) – Path object to an asset or directory to which to move source.

Return type:

None

onyo.lib.commands.onyo_cat(inventory, paths)

Print the contents of assets.

The same path can be given multiple times.

If any path is not an asset, nothing is printed. If any asset content is invalid, the content of all assets is still printed.

Parameters:

• inventory (Inventory) – The inventory containing the assets to print.

• paths (list[Path]) – Paths of assets to print the contents of.

Raises:

• ValueError – If a provided asset is not an asset, or if paths is empty.

• OnyoInvalidRepoError – If paths contains an invalid asset (e.g. content is invalid YAML).

Return type:

None

onyo.lib.commands.onyo_config(inventory, config_args)

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)

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) – A custom commit message.

Raises:

ValueError – If a provided asset is not an asset, or if paths is empty.

Return type:

None

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

Query the repository for information about assets.

Parameters:

• inventory (Inventory) – The inventory to query.

• include (list[Path] | None (default: None)) – Limits the query to assets underneath these paths. Paths can be assets and directories. If no paths are specified, the inventory root is used as default.

• exclude (list[Path] | Path | None (default: None)) – Paths to exclude, meaning that assets underneath any of these are not being returned. Defaults to None. Note, that depth only applies to include, not to exclude. depth and exclude are different ways of limiting the results.

• depth (int (default: 0)) – Number of levels to descend into. Must be greater or equal 0. If 0, descend recursively without limit.

• machine_readable (bool (default: False)) – Whether to print the matching assets as TAB-separated lines, where the columns correspond to the keys. If False, print a table meant for human consumption.

• match (list[Callable[[dict], bool]] | None (default: None)) – Callables suited for use with builtin filter. They are passed an asset dictionary and expected to return a bool, where True indicates a match. The result of the query consists of all assets that are matched by all callables in this list. One can match keys that are not in the output.

• keys (list[str] | None (default: None)) – Defines what key-value pairs of an asset a result is composed of. If no keys are given then the asset name keys and path are used. Keys may be repeated.

• sort (dict[str, Literal['ascending', 'descending']] | None (default: None)) – How to sort the results. This is a dictionary, where the keys are the asset keys to sort by (in order of appearances in the sort dictionary). Possible values are onyo.lib.consts.SORT_ASCENDING and onyo.lib.consts.SORT_DESCENDING. If other values are specified an error is raised. Default: {‘path’: SORT_ASCENDING}. One can sort by keys that are not in the output.

Raises:

ValueError – On invalid arguments.

Returns:

A dictionary per matching asset as defined by keys.

Return type:

list of dict

onyo.lib.commands.onyo_mkdir(inventory, dirs, message)

Create new directories in the inventory.

Intermediate directories will be 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 duplicates, onyo will create just one new directory and ignore the duplicates.

All paths in dirs must be new and valid directory paths inside the inventory. However, a path to an existing asset file is valid and means to turn that asset file into an asset dir. At least one valid path is required. If any path specified is invalid no new directories are created, and an error is raised.

Parameters:

• inventory (Inventory) – The inventory in which to create new directories.

• dirs (list[Path]) – Paths to directories which to create.

• message (str | None) – An optional string to overwrite Onyo’s default commit message.

Raises:

ValueError – If dirs is empty.

Return type:

None

onyo.lib.commands.onyo_mv(inventory, source, destination, message=None)

Move assets or directories, or rename a directory.

If destination is an asset file, turns it into an asset dir first.

Parameters:

• inventory (Inventory) – The Inventory in which to move assets or directories.

• source (list[Path] | Path) – A list of source paths that will be moved to the destination. If a single source directory is given and the destination is a non-existing directory, the source will be renamed.

• destination (Path) – The path to which the source(s) will be moved, or a single source directory will be renamed.

• message (str | None (default: None)) – An optional string to overwrite Onyo’s default commit 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, tsv=None, keys=None, edit=False, message=None)

Create new assets and add them to the inventory.

Either keys, tsv or edit must be given. If keys and tsv and keys define multiple assets: Number of assets must match. If only one value pair key: Update tsv assets with them. If keys and tsv conflict: raise, there’s no priority overwriting or something. –directory and directory reserved key given -> raise, no priority pseudo-keys must not be given -> PSEUDO_KEYS

TODO: Document special keys (directory, asset dir, template, etc) -> RESERVED_KEYS TODO: ‘directory’ -> relative to inventory root!

• keys vs template: fill up? Write it down!

• edit: TODO: May lead to delay any error until we got the edit result? As in: Can start empty?

• template: if it can be given as a key, do we need a dedicated option?

# TODO: This just copy pasta from StoreKeyValuePair, ATM. To some extend should go into help for –key. # But: description of TSV and special keys required. Every key appearing multiple times in key=value is applied to a new dictionary every time. All keys appearing multiple times, must appear the same number of times (and thereby define the number of dicts to be created). In case of different counts: raise. Every key appearing once in key_values will be applied to all dictionaries.

Parameters:

• inventory (Inventory) – The Inventory in which to create new assets.

• directory (Path | None (default: None)) – The directory to create new asset(s) in. Defaults to CWD. Note, that it technically is not a default (as per signature of this function), because we need to be able to tell whether a path was given in order to check for conflict with a possible ‘directory’ key or table column.

• template (Path | str | None (default: None)) – Path to a template file. If relative, this is allowed to be relative to .onyo/templates/. The template is copied as a base for the new assets to be created.

• clone (Path | None (default: None)) – Path to an asset to clone. Mutually exclusive with template. Note, that a straight clone with no change via keys, tsv or edit would result in the exact same asset, which therefore is bound to fail.

• tsv (Path | None (default: None)) – A path to a tsv table that describes new assets to be created.

• keys (list[Union[Dict, UserDict]] | None (default: None)) – List of dictionaries with key/value pairs that will be set in the newly created assets. The keys used in the onyo.assets.name-format config .onyo/config (e.g. name-format = "{type}_{make}_{model}.{serial}") are used in the asset name and therefore a required.

• edit (bool (default: False)) – If True, newly created assets are opened in the editor before the changes are saved.

• message (str | None (default: None)) – An optional string to overwrite Onyo’s default commit message.

Raises:

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

Return type:

None

onyo.lib.commands.onyo_rm(inventory, paths, message, recursive=False)

Delete assets and/or directories from the inventory.

Parameters:

• inventory (Inventory) – The inventory in which assets and/or directories will be deleted.

• paths (list[Path] | Path) – List of paths to assets and/or directories to delete from the Inventory. If any path given is not valid, none of them gets deleted.

• recursive (bool (default: False)) – Recursively remove a directory with all its content. If not set, fail on non-empty directories.

• message (str | None) – An optional string to overwrite Onyo’s default commit message.

Return type:

None

onyo.lib.commands.onyo_set(inventory, keys, assets, message=None)

Set key-value pairs of assets, and change asset names.

Parameters:

• inventory (Inventory) – The Inventory in which to set key/values for assets.

• assets (list[Path]) – Paths to assets for which to set key-value pairs.

• keys (dict | UserDict) – Key-value pairs that will be set in assets. If keys already exist in an asset, their value will be overwritten. If they do not exist the values are added. Keys that appear in asset names will result in the asset being renamed. The key ‘is_asset_directory’ (bool) can be used to change whether an asset is an asset directory.

• message (str | None (default: None)) – A custom commit message.

Raises:

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

Return type:

str | None

onyo.lib.commands.onyo_tree(inventory, paths, dirs_only=False)

Print the directory tree of paths.

Parameters:

• inventory (Inventory) – The inventory in which the directories to display are located.

• paths (list[tuple[str, Path]]) –

  A list of tuples containing (str, Path) of directories to build a tree of.

  The description is used as a text representation of what path the user requested. This way, regardless of how the user requested a path (relative, absolute, subdir, etc), it is always printed “correctly”.

• dirs_only (bool (default: False)) – Print only directories.

Raises:

ValueError – If paths are invalid.

Return type:

None

onyo.lib.commands.onyo_unset(inventory, keys, assets, message=None)

Remove keys from assets.

Parameters:

• inventory (Inventory) – The Inventory in which to unset key/values for assets.

• keys (Iterable[str]) – The keys that will be unset in assets. If keys do not exist in an asset, a debug message is logged. If keys are specified which appear in asset names an error is raised. If keys is empty an error is raised.

• assets (list[Path]) – Paths to assets for which to unset key-value pairs.

• message (str | None (default: None)) – An optional string to overwrite Onyo’s default commit message.

Raises:

ValueError – If assets are invalid paths, or keys are empty or invalid.

Return type:

None

onyo.lib.commands.raise_on_inventory_state(func)

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)]