onyo.lib.onyo module

class onyo.lib.onyo.OnyoRepo(path, init=False, find_root=False)[source]

Bases: object

Representation of an Onyo repository.

Identify and work with asset paths and directories. Get and set onyo config information.

git: Reference to the onyo.lib.git.GitRepo of this Onyo repository.

dot_onyo: The Path of the .onyo/ subdirectory (Onyo_DIR) that contains templates, the onyo-config file, and other onyo-relevant files.

__init__(path, init=False, find_root=False)[source]

Instantiate an OnyoRepo object with path as the root directory.

Parameters:

path (Path) – An absolute path to the root of the Onyo Repository.
init (bool (default: False)) – Initialize path as a git repo and create/populate the subdir .onyo/. Cannot be used with find_root=True.
find_root (bool (default: False)) – Search for the root of the repository beginning at path, and then up through parents. Cannot be used with init==True.

Raises:

ValueError – find_root=True and init==True both specified.
OnyoInvalidRepoError – path is not a valid path to an Onyo repository.

property asset_paths: list[Path]

Get the absolute Paths of all assets in this repository.

This property is cached and is reset automatically on commit().

If changes are made by other means, use clear_cache() to reset the cache.

property auto_message: bool: The configured value of onyo.commit.auto-message.

clear_cache()[source]

Clear the cache of this instance of OnyoRepo (and the sub-onyo.lib.git.GitRepo).

When the repository is modified using only the public API functions, the cache is consistent. This method is only necessary if the repository is modified otherwise.

Return type:: None

commit(paths, message)[source]

Commit changes to the repository.

This is resets the cache and is otherwise just a proxy for onyo.lib.git.GitRepo.commit().

Parameters:

paths (Union[Iterable[Path], Path]) – List of Paths to commit.
message (str) – The git commit message.

Return type:

None

static generate_commit_subject(format_string, max_length=80, **kwargs)[source]

Generate a commit message subject.

Path names are shortened on a best effort basis to reduce the subject length to max_length.

Parameters:

format_string (str) – A format string defining the commit message subject to generate.
max_length (int (default: 80)) – The suggested max length for the generated commit message subject.
**kwargs – Values to insert into the format_string. Values that are Paths will be shortened as needed.

Return type:

str

get_asset_content(path)[source]

Get a dictionary representing path’s content.

The content also includes the asset’s pseudo-keys.

Parameters:: path (Path) – Path of asset to load. This may be either a YAML file or an Asset Directory (onyo.lib.consts.ASSET_DIR_FILE_NAME is automatically appended).
Return type:: dict

get_asset_name_keys()[source]

Get a list of keys used to generate asset names.

Key names are extracted from the format string specified in the config onyo.assets.name-format.

Return type:: list[str]

get_config(key)[source]

Get the effective value of a configuration key.

This first checks git’s normal git-config locations and then onyo.lib.consts.ONYO_CONFIG as a fallback.

The results are cached, which are cleared automatically by commit() and set_config().

If changes are made by other means, use clear_cache() to reset the cache.

Parameters:

key (str) –

Name of the configuration key to query. Follows Git’s convention of “SECTION.NAME.KEY” to address a key in a git config file:

[SECTION "NAME"]
    KEY = VALUE

Return type:

str | None

get_editor()[source]

Return the editor to use.

This progresses through:

ONYO_CORE_EDITOR environment variable
onyo.core.editor
git’s core.editor
EDITOR environment variable
nano (fallback).

Return type:: str

get_history(path=None, n=None)[source]

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_paths(include=None, exclude=None, depth=0, types=None, intermediates=True)[source]

Get the Paths of all items matching paths and filters.

Parameters:

include (Optional[Iterable[Path]] (default: None)) – Paths under which to look for items. Default is to inventory root.
exclude (Union[Iterable[Path], Path, None] (default: None)) – Paths to exclude (i.e. items underneath will not be returned).
depth (int (default: 0)) – Number of levels to descend into the directories specified by include. A depth of 0 descends recursively without limit.
types (Optional[List[Literal['assets', 'directories']]] (default: None)) – List of types of inventory items to consider. Equivalent to onyo.is.asset=True and onyo.is.directory=True. Default is ['assets'].
intermediates (bool (default: True)) – Return intermediate directory items. If False, the only directories explicitly contained in the returned list are leaves.

Return type:

List[Path]

get_templates(path=None, recursive=False)[source]

Yield ItemSpec(s) (recursively) from a path.

Parameters:

path (Path | None (default: None)) – Path to a Template. If relative, then it is considered relative to the template directory (onyo.lib.consts.TEMPLATE_DIR). If no path is given, the template defined in the config onyo.new.template is used.
recursive (bool (default: False)) – Recurse into directory templates
not (If path is not specified and the config onyo.new.template is)
set
empty. (the dictionary will be)

Raises:

ValueError – If the requested template can’t be found.

Return type:

Generator[ItemSpec, None, None]

is_asset_dir(path)[source]

Whether path is an asset directory.

An asset directory is both an asset and an inventory directory.

Parameters:: path (Path) – Path to check.
Return type:: bool

is_asset_file(path)[source]

Whether path is an asset file.

Parameters:: path (Path) – Path to check.
Return type:: bool

is_asset_path(path)[source]

Whether path is an asset in the repository.

Parameters:: path (Path) – Path to check.
Return type:: bool

is_inventory_dir(path)[source]

Whether path is an inventory directory.

This only considers directories with a committed anchor file.

Parameters:: path (Path) – Path to check.
Return type:: bool

is_inventory_path(path)[source]

Whether path a valid potential name for an asset or an inventory directory.

This only checks whether path is suitable in principle. It does not check whether that path already exists or if it would be valid and available as an asset name.

Parameters:: path (Path) – Path to check.
Return type:: bool

is_item_path(path)[source]

Whether path is a valid path for an item.

This checks whether path is valid for reading an item from or creating an item at in principle. It’s not checking whether path actually exists.

Return type:: bool

is_onyo_ignored(path)[source]

Whether path is matched by a pattern in .onyoignore.

Such a path would not considered to be an inventory item by Onyo, but could still be tracked in git.

.onyoignore files apply to the subtree they are placed into.

Parameters:: path (Path) – Path to check for matching an exclude pattern in an ignore file (onyo.lib.consts.IGNORE_FILE_NAME).
Return type:: bool

is_onyo_path(path)[source]

Determine whether an absolute path is used by onyo internally.

Currently anything underneath .onyo/, anything named .onyo*, and an anchor files in an inventory directory is considered an onyo path.

Parameters:: path (Path) – The path to check.
Return type:: bool

is_template_path(path)[source]

Whether path is a valid template location.

Return type:: bool

mk_inventory_dirs(dirs)[source]

Create inventory directories.

Also creates an .anchor file for each new directory.

A list of the newly-created anchor files is returned.

Raises:

OnyoProtectedPathError – dirs contains an invalid path.
FileExistsError – dirs contains a path pointing to an existing file

Return type:

list[Path]

set_config(key, value, location='onyo')[source]

Set the value of a configuration key.

Parameters:

key (str) – The name of the configuration key to set.
value (str) – The value to set the configuration key to.
location (Literal['system', 'global', 'local', 'worktree', 'onyo'] (default: 'onyo')) – The location to set the key/value in. Valid locations are standard git-config locations ('system', 'global', 'local', and 'worktree') and 'onyo' (onyo.lib.consts.ONYO_CONFIG).

Raises:

ValueError – location is invalid.

Return type:

None

validate_anchors()[source]

Check if all inventory directories contain an .anchor file.

Returns:: True if all directories contain an .anchor file, otherwise False.
Return type:: bool

validate_onyo_repo()[source]

Assert whether this a full init-ed onyo repository.

Raises:: OnyoInvalidRepoError – Validation failed
Return type:: None

write_asset(asset)[source]

Write an asset’s contents to disk.

Pseudokeys are not included in the written YAML.

Parameters:

asset (Item) – The asset Item to write.
path – The Path to write content to. Default is the asset’s 'onyo.path.file' pseudokey.

Raises:

ValueError – The pseudokey 'onyo.path.file' is not a valid inventory path.

Return type:

Item