onyo.lib.items module

class onyo.lib.items.Item(item=None, repo=None, **kwargs)

Bases: ItemSpec

An item that an onyo.lib.inventory.Inventory can potentially track.

In contrast to an ItemSpec, an Item is associated with a repository. Thus, it gains the ability to lookup/generate pseudokey values and the automatic resolution of user-defined key aliases.

On initialization, sanity checks are performed on the provided pseudokey-related values (e.g. all 'onyo.path' are consistent, generate the asset name from keys, etc). However, once instantiated, Item allows changes to be made and makes no assurances about the consistency of the information stored in it. For example, modifying onyo.is.directory or a key used in the asset name will not automatically update the value of onyo.path.file.

It is the responsibility of those modifying values to clear caches and ensure consistency.

It is safest to use the operations available in onyo.lib.inventory.Inventory to modify Items.

__init__(item=None, repo=None, **kwargs)

Initialize an Item.

update_from_path(path)

Update the internal dictionary with key/values from a YAML file.

YAML comments are preserved on a best-effort basis. There is no straightforward way to merge YAML comments, and thus ones from path may overwrite internal ones.

Parameters:

path (Path) – Path of YAML file to update from.

Return type:

None

yaml(exclude=None)

Get the stringified YAML including content and comments.

Parameters:

exclude (list | None (default: None)) – Keys to exclude from the output. By default, all onyo.lib.consts.RESERVED_KEYS (e.g. pseudokeys) are excluded.

Return type:

str

class onyo.lib.items.ItemSpec(spec=None, alias_map=None, **kwargs)

Bases: UserDict

Nested dictionaries of static instructions to create an Item.

Compared to a dictionary, the primary features are:

• load YAML (e.g. ItemSpec(Path('file.yaml').read_text())

• dump YAML (e.g. spec.yaml())

• equality including YAML comments (e.g. ItemSpec() == ItemSpec())

• dot notation (e.g. spec['nested.dict.key'])

• alias resolution

In contrast to Item, an ItemSpec is entirely static. It is not associated with a repository, and thus has no sanity checks nor pseudokey lookup capabilities. Alias resolution is possible, but the mapping must be provided manually.

Multidimensional dictionaries are traversed using a dot as the delimiter. In other words, it provides a view of the flattened dictionary:

> d = {'key': 'value', 'nested': {'key': 'another value'}}
> spec = ItemSpec(d)
> spec['nested.key']
'another value'
> list(spec.keys())
['key', 'nested.key']

Iteration only considers the flattened view. Keys that contain a dictionary are not yielded when using .keys(), .values(), and .items().

The underlying dictionary is available via the .data attribute when the standard Python behavior is needed.

__init__(spec=None, alias_map=None, **kwargs)

Initialize an ItemSpec.

Parameters:

• spec (Union[Mapping[TypeVar(_KT), TypeVar(_VT)], str, None] (default: None)) – Dictionary or YAML string to load.

• alias_map (Optional[Mapping[str, str]] (default: None)) – Dictionary mapping aliases to key names.

equal_content(other)

Whether another ItemSpec/Item and self have the same content and comments.

Pseudokeys are ignored entirely.

Parameters:

other (ItemSpec | Item) – Item to compare with self.

Return type:

bool

get(key, default=None)

Return the value of key if it’s in the dictionary, otherwise default.

Return type:

Any

yaml(exclude=None)

Get the stringified YAML including content and comments.

Parameters:

exclude (list | None (default: None)) – Keys to exclude from the output. By default, none are excluded.

Return type:

str

onyo.lib.items.resolve_alias(key, alias_map=None)

Return the target key of a key alias.

Parameters:

• key (TypeVar(_KT)) – Key name to resolve.

• alias_map (Optional[Mapping[str, str]] (default: None)) – Dictionary mapping aliases to key names.

Return type:

TypeVar(_KT)