onyo.lib.onyo module

class onyo.lib.onyo.OnyoRepo(path, init=False, find_root=False)

Bases: object

An object representing an Onyo repository.

Allows identifying and working with asset paths and directories, getting and setting onyo config information.

git

Contains the path to the root of the repository, and functions to add and commit changes, set and get config information, and delete files and folders.

Type:

GitRepo

dot_onyo

The path to the .onyo/ directory containing templates, the config file and other onyo specific information.

Type:

Path

ANCHOR_FILE_NAME = '.anchor'

ASSET_DIR_FILE_NAME = '.onyo-asset-dir'

IGNORE_FILE_NAME = '.onyoignore'

ONYO_CONFIG = PosixPath('.onyo/config')

ONYO_DIR = PosixPath('.onyo')

TEMPLATE_DIR = PosixPath('.onyo/templates')

__init__(path, init=False, find_root=False)

Instantiates an OnyoRepo object with path as the root directory.

Parameters:

• path (Path) – An absolute path to the root of the Onyo Repository for which the OnyoRepo object should be initialized.

• init (bool (default: False)) – If init=True, the path will be initialized as a git repo and a .onyo/ directory will be created. find_root=True must not be used in combination with init=True. Verifies the validity of the onyo repository.

• find_root (bool (default: False)) – When find_root=True, the function searches the root of a repository, beginning at path.

Raises:

• ValueError – If tried to find a repository root and initializing a repository at the same time.

• OnyoInvalidRepoError – If the path to initialize the repository 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 OnyoRepo.commit().

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

clear_cache()

Clear cache of this instance of GitRepo.

Caches cleared are: - OnyoRepo.asset_paths - GitRepo.git.clear_cache()

If the repository is exclusively modified via public API functions, the cache of the OnyoRepo object is consistent. If the repository is modified otherwise, use of this function may be necessary to ensure that the cache does not contain stale information.

Return type:

None

commit(paths, message)

Commit changes to the repository.

This is resets the cache and is otherwise just a proxy for GitRepo.commit.

Parameters:

• paths (Union[Iterable[Path], Path]) – List of paths to commit.

• message (str) – The git commit message.

static generate_commit_message(format_string, max_length=80, **kwargs)

Generate a commit message subject.

The function will shorten paths in the resulting string in order to try to fit into max_length.

Parameters:

• format_string (str) – A format string defining the commit message subject to generate.

• max_length (int (default: 80)) – An integer specifying the maximal length for generated commit message subjects.

• **kwargs – Values to insert into the format_string. If values are paths, they will be shortened to include as much user readable information as possible.

Returns:

A message suitable as a commit message subject.

Return type:

str

get_asset_content(path)

Get a dictionary representing path’s content.

Parameters:

path (Path) – Asset path to load. This is expected to be either a YAML file or an asset directory (OnyoRepo.ASSET_DIR_FILE_NAME automatically appended).

Returns:

Dictionary representing an asset. That is: The union of the content of the YAML file and teh asset’s pseudo-keys.

Return type:

dict

get_asset_name_keys()

Get a list of keys required for generating asset names

This is extracting names of used keys from the onyo.assets.name-format config, which is supposed to be a python format string.

Notes

The extraction is relying on every such usage starting with a ‘{’, followed by a key name, which is then either closed directly via ‘}’ or first followed by some formatting options in which case there’s ‘[’, ‘.’, ‘!’, etc. Note, that ‘w’ is used to match the key name, which includes alphanumeric characters as well as underscores, therefore matching python variable name restrictions. This is relevant, because we want to get a dict from the YAML and making the values available to name generation by passing the dict to a format call on the configured string: config_str.format(**yaml_dict) Hence, keys need to be able to be python variables.

This comes with a limitation on what formatting can be used in the config. Utilizing nested dictionaries, for example, would not be possible. Only the toplevel key would be recognized here.

Returns:

list containing the names of all keys found

Return type:

list of str

get_asset_paths(include=None, exclude=None, depth=0)

Select all assets in the repository that are relative to the given subtrees descending at most depth directories.

Parameters:

• include (Optional[Iterable[Path]] (default: None)) – Paths to look for assets under. Defaults to the root of the inventory.

• exclude (Union[Iterable[Path], Path, None] (default: None)) – Paths to exclude, meaning that assets underneath any of these are not being returned. Defaults to None.

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

Return type:

List[Path]

Returns:

list of Path

Paths to all matching assets in the repository.

get_config(name)

Get effective value of config name.

This is considering regular git-config locations and checks OnyoRepo.ONYO_CONFIG as fallback.

Return type:

str | None

get_editor()

Returns the editor, progressing through onyo, git, $EDITOR, and finally fallback to “nano”.

Return type:

str

get_template(path=None)

Select a template file and return an asset dict from it.

from the directory .onyo/templates/

Parameters:

path (Path | str | None (default: None)) – Template file. If this a relative path or a string, then this is interpreted as relative to the template directory. If no path is given, the template defined in the config file .onyo/config is returned.

Returns:

dictionary representing the content of the template. If name is not specified and there’s no onyo.new.template config set the dictionary will be empty.

Return type:

dict

Raises:

ValueError – If the requested template can’t be found or is not a file.

is_asset_dir(path)

Whether path is an asset directory.

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

Parameters:

path (Path) – Path to check.

Returns:

Whether path is an asset directory.

Return type:

bool

is_asset_path(path)

Whether path is an asset in the repository.

Parameters:

path (Path) – Path to check for pointing to an asset.

Returns:

Whether path is an asset in the repository.

Return type:

bool

is_inventory_dir(path)

Whether path is an inventory directory.

This only considers directories w/ committed anchor file.

Return type:

bool

is_inventory_path(path)

Whether path is valid for tracking 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.

Returns:

Whether path is valid for an inventory item.

Return type:

bool

is_onyo_ignored(path)

Whether path is matched by an .onyoignore file.

Such a path would be tracked by git, but not considered to be an inventory item by onyo. Ignore files do apply to the subtree they are placed into.

Parameters:

path (Path) – Path to check for matching an exclude pattern in an ignore file (OnyoRepo.IGNORE_FILE_NAME).

Returns:

Whether path is ignored.

Return type:

bool

is_onyo_path(path)

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.

Returns:

True if path is used internally by onyo.

Return type:

bool

mk_inventory_dirs(dirs)

Create inventory directories dirs.

Creates dirs including anchor files.

Raises:

• OnyoProtectedPathError – if dirs contains an invalid path (see OnyoRepo.is_inventory_path()).

• FileExistsError – if dirs contains a path pointing to an existing file (hence, the dir can’t be created).

Returns:

list of created anchor files (paths to be committed).

Return type:

list of Path

set_config(name, value, location='onyo')

Set the configuration option name to value.

Parameters:

• name (str) – The name of the configuration option to set.

• value (str) – The value to set for the configuration option.

• location (str (default: 'onyo')) – The location of the configuration for which the value should be set. Standard Git config locations: ‘system’, ‘global’, ‘local’, and ‘worktree’. The location ‘onyo’ is available in addition and refers to a committed config file at OnyoRepo.ONYO_CONFIG. Default: ‘onyo’.

Raises:

ValueError – If location is unknown.

Return type:

None

validate_anchors()

Check if all dirs (except those in .onyo/) contain an .anchor file.

Returns:

True if all directories contain an .anchor file, otherwise False.

Return type:

bool

validate_onyo_repo()

Assert whether this is a properly set up onyo repository and has a fully populated .onyo/ directory.

Raises:

OnyoInvalidRepoError – If validation failed

Return type:

None

write_asset_content(asset)

Return type:

dict