onyo.lib.inventory module

class onyo.lib.inventory.Inventory(repo)

Bases: object

Representation of an inventory of an Onyo repository.

Provides all functionality necessary to query, modify, create, or remove inventory items.

operations

List of all pending InventoryOperations.

repo

The OnyoRepo this Inventory represents.

__init__(repo)

Instantiate an Inventory object based on repo.

Parameters:

repo (OnyoRepo) – The OnyoRepo to represent.

add_asset(asset)

Create an asset.

Parameters:

asset (Item) – The Item to create as an asset.

Raises:

ValueError – item['onyo.path.absolute'] cannot be generated, is invalid, or the destination already exists.

Return type:

list[InventoryOperation]

add_directory(item)

Create a directory or convert an Asset File to an Asset Directory.

Parameters:

item (Item) – The Item to make a directory of.

Raises:

• NoopError – item['onyo.path.absolute'] is already a directory.

• ValueError – item['onyo.path.absolute'] is invalid.

Return type:

list[InventoryOperation]

commit(message)

Execute pending operations and commit the results.

Return type:

None

diff()

Yield the textual diffs of all operations.

Return type:

Generator[str, None, None]

generate_asset_name(asset)

Generate an asset’s file or directory name.

The asset name format is defined by the configuration onyo.assets.name-format.

Parameters:

asset (Item) – Asset Item to generate the name for.

Raises:

ValueError – The configuration ‘onyo.assets.name-format’ is missing or asset does not contain all keys/values needed to generate the asset name.

Return type:

str

get_faux_serials(num=1, length=8)

Generate a set of unique faux serials.

The generated faux serials are unique within the set and repository.

The minimum serial length of 5 offers a serial space of 36^5 (~60.5 million). That is (arbitrarily) determined to be the highest acceptable risk of collisions between independent checkouts of a repo generating serials at the same time.

Parameters:

• num (int (default: 1)) – Number of serials to generate.

• length (int (default: 8)) – String length of the serials to generate. Must be >= 5.

Raises:

ValueError – num or length is invalid.

Return type:

set[str]

get_history(path=None, n=None)

Yield the history of Inventory Operations for a path.

Parameters:

• path (Path | None (default: None)) – The Path to get the history of. Defaults to the repo root.

• n (int | None (default: None)) – Limit history to n commits. None for no limit (default).

Return type:

Generator[UserDict, None, None]

get_item(path)

Get the Item of path.

Parameters:

path (Path) – Path to get as an Item.

Return type:

Item

get_items(include=None, exclude=None, depth=0, match=None, types=None, intermediates=True)

Yield all Items matching paths and filters.

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

Parameters:

• include (Optional[Iterable[Path]] (default: None)) –

  Paths under which to look for Items. Default is inventory root.

  Passed to onyo.lib.onyo.OnyoRepo.get_item_paths().

• exclude (Union[Iterable[Path], Path, None] (default: None)) –

  Paths to exclude (i.e. Items underneath will not be returned).

  Passed to onyo.lib.onyo.OnyoRepo.get_item_paths().

• depth (int | None (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.onyo.OnyoRepo.get_item_paths().

• match (list[Callable[[Item], bool]] | list[list[Callable[[Item], 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.

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

• 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.onyo.OnyoRepo.get_item_paths().

• intermediates (bool (default: True)) – Return intermediate directory items. If False, the only directories explicitly contained in the returned list are leaves.

Return type:

Union[Generator[Item, None, None], filter]

get_templates(template, recursive=False)

Get templates as Items.

Return type:

Generator[Item, None, None]

template:

Path to generate a template from. If relative, this is interpreted as relative to the repository’s template dir.

recursive:

Recursive into template directories.

modify_asset(asset, new_asset)

Modify an asset.

Parameters:

• asset (Item) – Original asset Item to modify.

• new_asset (Item) – New asset Item to apply to asset.

Raises:

• NoopError – No modifications would result from applying new_asset to asset.

• ValueError – asset is not an asset, or new_asset changes read-only pseudo-keys.

Return type:

list[InventoryOperation]

move_asset(src, dst)

Move an asset to a new parent directory.

To rename an asset under the same parent, see rename_asset().

Parameters:

• src (Item) – The Path to move.

• dst (Item) – The absolute Path of the new parent directory.

Raises:

• NotAnAssetError – asset is not an asset.

• ValueError – dst is the same parent, the target already exists, or dst would be an invalid location.

Return type:

list[InventoryOperation]

move_directory(src, dst)

Move a directory to a new parent directory.

To rename a directory under the same parent, see rename_directory().

Parameters:

• src (Item) – The Item to move.

• dst (Item) – The new parent directory.

Raises:

• InvalidInventoryOperationError – src and dst share the same parent.

• ValueError – src is not an inventory directory, the target already exists, or dst would be an invalid location.

Return type:

list[InventoryOperation]

operations_pending()

Return whether there’s something to commit.

Return type:

bool

operations_summary()

Get a textual summary of all operations.

Return type:

str

raise_empty_keys(asset)

Raise if asset has empty keys.

A validation helper.

Parameters:

asset (Item) – The asset Item to check.

Return type:

None

raise_required_key_empty_value(asset)

Raise if asset has an empty value for a required key.

A validation helper. This checks only asset name keys.

Parameters:

asset (Item) – The asset Item to check.

Raises:

ValueError – A required key has an empty value.

Return type:

None

remove_asset(asset)

Remove an asset.

Parameters:

asset (Item) – Asset Item to remove.

Raises:

NotAnAssetError – asset is not an asset.

Return type:

list[InventoryOperation]

remove_directory(item, recursive=True)

Remove a directory or convert an Asset Directory to a File.

Parameters:

• item (Item) – The Item to remove as a directory.

• recursive (bool (default: True)) – Recursively remove items within item.

Raises:

• InvalidInventoryOperationError – item['onyo.path.absolute'] is invalid.

• InventoryDirNotEmpty – item['onyo.path.absolute'] has children on the filesystem.

• NoopError – item['onyo.path.absolute'] is already an Asset File.

Return type:

list[InventoryOperation]

rename_asset(asset)

Rename an asset to a new name under the same parent.

This renames an asset under the same parent. To move to a different parent directory, see move_asset().

The asset name is automatically generated by generate_asset_name(). It cannot be manually set.

Parameters:

asset (Item) – Item to rename.

Raises:

• NoopError – Rename would result in the same name.

• ValueError – asset is not an asset, the destination already exists, or the destination is already pending to be created.

Return type:

list[InventoryOperation]

rename_directory(src, dst)

Rename a directory to a new name under the same parent.

This renames a non-asset directory under the same parent. To move to a different parent directory, see move_directory(). To rename an asset (including an Asset Directory), see modify_asset() and rename_asset().

Parameters:

• src (Item) – The Item to rename.

• dst (str | Path) – The new name or an absolute Path to the new destination.

Raises:

• InvalidInventoryOperationError – src and dst do not share the same parent.

• NotADirError – src is not a non-asset directory.

• NoopError – Rename would result in the same name.

• ValueError – src is not an inventory directory, dst already exists, or dst would be an invalid location.

Return type:

list[InventoryOperation]

reset()

Discard pending operations.

Return type:

None

property root

Path to the root inventory directory.

class onyo.lib.inventory.InventoryOperation(operator, operands, repo)

Bases: object

Representation of an individual pending Inventory Operation.

Groups together the intended InventoryOperator, its targets, and repo.

__init__(operator, operands, repo)

diff()

Generate the anticipated diff of executing the operation.

Return type:

Generator[str, None, None]

execute()

Execute the Inventory Operation.

Return type:

tuple[list[Path], list[Path]]

operands: tuple

operator: InventoryOperator

repo: OnyoRepo

class onyo.lib.inventory.InventoryOperator(executor, differ, recorder)

Bases: object

Representation of a type of Inventory Operation.

Groups together the Callables to execute, diff, and record an operation.

See OPERATIONS_MAPPING.

__init__(executor, differ, recorder)

differ: Callable

executor: Callable

recorder: Callable

onyo.lib.inventory.OPERATIONS_MAPPING: dict = {'modify_assets': InventoryOperator(executor=<function exec_modify_asset>, differ=<function differ_modify_asset>, recorder=<function record_modify_asset>), 'move_assets': InventoryOperator(executor=<function exec_move_asset>, differ=<function differ_move_asset>, recorder=<function record_move_asset>), 'move_directories': InventoryOperator(executor=<function exec_move_directory>, differ=<function differ_move_directory>, recorder=<function record_move_directory>), 'new_assets': InventoryOperator(executor=<function exec_new_asset>, differ=<function differ_new_asset>, recorder=<function record_new_asset>), 'new_directories': InventoryOperator(executor=<function exec_new_directory>, differ=<function differ_new_directory>, recorder=<function record_new_directory>), 'remove_assets': InventoryOperator(executor=<function exec_remove_asset>, differ=<function differ_remove_asset>, recorder=<function record_remove_asset>), 'remove_directories': InventoryOperator(executor=<function exec_remove_directory>, differ=<function differ_remove_directory>, recorder=<function record_remove_directory>), 'remove_generic_file': InventoryOperator(executor=functools.partial(<function generic_executor>, <function <lambda>>), differ=<function differ_remove_asset>, recorder=<function <lambda>>), 'rename_assets': InventoryOperator(executor=<function exec_rename_asset>, differ=<function differ_rename_asset>, recorder=<function record_rename_asset>), 'rename_directories': InventoryOperator(executor=<function exec_rename_directory>, differ=<function differ_rename_directory>, recorder=<function record_rename_directory>)}

Mapping of Inventory Operation types with the appropriate operators.