cmeta.category_api_v1 module

CMeta base category class

See the cMeta COPYRIGHT and LICENSE files in the project root for details.

Classes

class cmeta.category_api_v1.Category(*args, **kwargs)[source]

Bases: InitCategory

Standard Base Category with artifact management functions

__init__(*args, **kwargs)[source]

Initialize the standard base category implementation.

Parameters:

*args – CLI positional arguments passed to the entry point.
**kwargs – Keyword arguments forwarded to the base initializer.

Returns:

Operation result.

Return type:

dict

Raises:

Exception – Propagated runtime errors, if any.

test(params: dict)[source]

Test category.

Parameters:

params (dict) – Parameters dictionary.

Returns:

A cMeta dictionary with the following keys:

return (int): 0 if success, >0 if error.

Return type:

dict

Raises:

Exception – Propagated runtime errors, if any.

info_(ctx: dict, arg1: str = None, clip: bool = True, url: bool = False, name: bool = False)[source]

Get artifact info.

Parameters:

ctx (dict) – cMeta context.
arg1 (str | None) – Artifact alias or UID.
clip (bool) – If True, copy cRef to clipboard.
url (bool) – If True, copy URL with detected cRef to the clipboard.
name (bool) – If True, copy artifact name to the clipboard

Returns:

A cMeta dictionary with the following keys:

return (int): 0 if success, >0 if error.
error (str): Error message if return > 0.
artifacts (list): List of matched artifacts.

Return type:

dict

Raises:

Exception – Propagated runtime errors, if any.

find_(ctx: dict, arg1: str = None, tags: str = None, sort: bool = None, add_index_file: bool = False, skip_uids: bool = False, match: dict = None, match_empty_version: bool = False, match_empty_values: bool = False, all_tags: str = None, load_files=[], follow_migrated: bool = True)[source]

Find artifacts.

Parameters:

ctx (dict) – cMeta context.
arg1 (str | None) – Artifact alias or UID.
tags (str | list | None) – Comma-separated string or iterable of tags to match.
sort (bool) – Sort by path (True by default).
add_index_file (bool) – Add index file information.
skip_uids (bool) – Skip UIDs when using wildcards.
match (dict) – Value for match.
match_empty_version (bool) – Value for match empty version.
match_empty_values (bool) – Match artifacts whose queried values or keys are empty.
all_tags (str) – Value for all tags.
load_files (list) – Metadata file basenames to load from each matched artifact.
follow_migrated (bool) – An alias given alone that is a migration stub (left by migrate) stands for the artifact it points to, with a notice; False returns the stub itself. A UID always finds exactly what it names.

Returns:

A cMeta dictionary with the following keys:

return (int): 0 if success, >0 if error.
error (str): Error message if return > 0.
artifacts (list): List of matched artifacts.

Return type:

dict

Raises:

Exception – Propagated runtime errors, if any.

tags_(ctx: dict, arg1: str = None, tags: str = None, sort: bool = False)[source]

Find unique tags in artifacts.

Parameters:

ctx (dict) – cMeta context.
arg1 (str | None) – Artifact alias or UID.
tags (str | list | None) – Comma-separated string or iterable of tags to match.
sort (bool) – Value for sort.

Returns:

A cMeta dictionary with the following keys:

return (int): 0 if success, >0 if error.
error (str): Error message if return > 0.
artifacts (list): List of matched artifacts.

Return type:

dict

Raises:

Exception – Propagated runtime errors, if any.

update_(ctx: dict, arg1: str = None, tags: str = None, sort: bool = True, skip_uids: bool = False, meta: dict = {}, new_tags: str = None, replace_lists: bool = False, replace: bool = False, ignore_errors: bool = False, create: bool = False, create_params: dict = {}, update_category: bool = False, match: dict = None, match_empty_version: bool = False, all_tags: str = None)[source]

Update artifact(s).

Parameters:

ctx (dict) – cMeta context.
arg1 (str | None) – cMeta artifact(s) with wildcards.
tags (str | list | None) – Prune artifacts by tags.
sort (bool) – Sort artifacts by alias and UID when updating in batch.
skip_uids (bool) – Skip UIDs when using wildcards.
meta (dict) – Meta dictionary to merge recursively with existing artifact.
new_tags (str | list | None) – Add more tags.
replace_lists (bool) – Replace lists during merging.
replace (bool) – Replace existing meta dictionary entirely.
ignore_errors (bool) – Ignore errors when updating multiple artifacts.
create (bool) – If artifact doesn’t exist attempt to create.
create_params (dict) – Pass params to create function.
update_category (bool) – Allow category update in meta.
match (dict | None) – Match artifact metadata before updating.
match_empty_version (bool) – Match artifacts with an empty version value.
all_tags (str | None) – Require all supplied tags when selecting artifacts.

Returns:

A cMeta dictionary with the following keys:

return (int): 0 if success, >0 if error.
error (str): Error message if return > 0.
artifacts (list): All matched artifacts.
updated_artifacts (list): Updated artifacts.

Return type:

dict

Raises:

Exception – Propagated runtime errors, if any.

list_(ctx: dict, arg1: str = None, tags: str = None, sort: bool = None, skip_uids: bool = False)[source]

List artifact names.

Parameters:

ctx (dict) – cMeta context.
arg1 (str | None) – Artifact alias or UID.
tags (str | list | None) – Optional tag filter.
sort (bool) – Sort by alias or UID.
skip_uids (bool) – Skip UIDs when using wildcards.

Returns:

A cMeta dictionary with the following keys:

return (int): 0 if success, >0 if error.
error (str): Error message if return > 0.
artifacts (list): List of matched artifacts.

Return type:

dict

Raises:

Exception – Propagated runtime errors, if any.

read_(ctx: dict, arg1: str = None, tags: str = None, extra: bool = False, skip_uids: bool = False, yaml: bool = False, load_files=[])[source]

Read artifact meta.

Parameters:

ctx (dict) – cMeta context.
arg1 (str | None) – Artifact alias or UID.
tags (str | list | None) – Optional tag filter.
extra (bool) – Show extra info.
skip_uids (bool) – Skip UIDs when using wildcards.
yaml (bool) – Output as YAML instead of JSON.
load_files – Value for load files.

Returns:

A cMeta dictionary with the following keys:

return (int): 0 if success, >0 if error.
error (str): Error message if return > 0.
artifact (dict): Matched artifact.
cmeta (dict): Artifact metadata.

Return type:

dict

Raises:

Exception – Propagated runtime errors, if any.

delete_(ctx: dict, arg1: str = None, tags: str = None, sort: bool = True, force: bool = False, f: bool = False, skip_uids: bool = False, ignore_errors: bool = False, print_time: bool = False, match: dict = None, match_empty_version: bool = False, all_tags: str = None)[source]

Delete and unindex artifact(s).

Parameters:

ctx (dict) – cMeta context.
arg1 (str | None) – Artifact alias or UID.
tags (str | list | None) – Optional tag filter.
sort (bool) – Sort artifacts by alias and UID.
force (bool) – Force deletion without confirmation.
f (bool) – Shorthand for force.
skip_uids (bool) – Skip UIDs when using wildcards.
ignore_errors (bool) – Ignore errors when deleting multiple artifacts.
print_time (bool) – Print time per deletion.
match (dict | None) – Match artifact metadata before deleting.
match_empty_version (bool) – Match artifacts with an empty version value.
all_tags (str | None) – Require all supplied tags when selecting artifacts.

Returns:

A cMeta dictionary with the following keys:

return (int): 0 if success, >0 if error.
error (str): Error message if return > 0.
artifacts (list): All matched artifacts.
deleted_artifacts (list): Deleted artifacts.

Return type:

dict

Raises:

Exception – Propagated runtime errors, if any.

create_(ctx: dict, arg1: str = None, tags: str = None, meta: dict = {}, yaml: bool = False, virtual: bool = False, path: str = None, index: bool = False)[source]

Create and index an artifact.

Parameters:

ctx (dict) – cMeta context.
arg1 (str | None) – Artifact alias or UID.
tags (str | list | None) – Tags to add to the artifact.
meta (dict) – Initial metadata dictionary.
yaml (bool) – Save metadata as YAML instead of JSON.
virtual (bool) – Virtual artifact created only in index (such as repo).
path (str | None) – Use this path for artifact (useful for virtual artifacts such as repo).
index (bool) – Index an artifact that already exists at path without creating it.

Returns:

A cMeta dictionary with the following keys:

return (int): 0 if success, >0 if error.
error (str): Error message if return > 0.
path (str): Path to the created artifact.
meta (dict): Artifact metadata.

Return type:

dict

Raises:

Exception – Propagated runtime errors, if any.

move_(ctx: dict, arg1: str, arg2: str, tags: str = None, sort: bool = True, skip_uids: bool = False, ignore_errors: bool = False, copy: bool = False)[source]

Rename and/or move artifact(s).

Parameters:

ctx (dict) – cMeta context.
arg1 (str) – cMeta artifact(s) with wildcards to be renamed or moved.
arg2 (str) – New cMeta artifact name and/or new repository.
tags (str | list | None) – Prune source artifacts by tags.
sort (bool) – Sort artifacts by alias and UID when updating in batch.
skip_uids (bool) – Skip UIDs when using wildcards.
ignore_errors (bool) – Ignore errors when updating multiple artifacts.
copy (bool) – If True, copy artifact instead of moving.

Returns:

A cMeta dictionary with the following keys:

return (int): 0 if success, >0 if error.
error (str): Error message if return > 0.
artifacts (list): All matched artifacts.
updated_artifacts (list): Updated artifacts.

Return type:

dict

Raises:

Exception – Propagated runtime errors, if any.

copy__(params: dict)[source]

Copy artifact(s).

@base.move_(**params, copy=True)

Parameters:: params (dict) – cMeta params.
Returns:: A cMeta dictionary (see move_ for details).
Return type:: dict
Raises:: Exception – Propagated runtime errors, if any.

migrate_(ctx: dict, arg1: str, arg2: str, tags: str = None)[source]

Rename an artifact (or move it to another repository under a new alias) and leave a stub under its old alias that points to it.

The artifact keeps its UID, as with move, so alias,UID and UID references to it keep working. The stub gets the old alias, a new UID and two keys: migrated_to, the new alias,UID, and migrated_when, the date and time of the migration (ISO 8601, UTC). A lookup of the old alias alone - cx task run <old>, cx <category> find <old> - then follows the stub to the artifact and prints a notice once. Commands that change artifacts (update, tags, move, delete) act on the stub itself, so cx <category> rm <old> removes it when nobody uses the old alias any more.

Parameters:

ctx (dict) – cMeta context.
arg1 (str) – The artifact to migrate: alias, UID or alias,UID (one artifact, no wildcards).
arg2 (str) – Its new alias, optionally in another repository: [repo:]alias.
tags (str | list | None) – Prune the source artifact by tags.

Returns:

A cMeta dictionary with the following keys:

return (int): 0 if success, >0 if error.
error (str): Error message if return > 0.
artifact (dict): The migrated artifact (its new alias, the same UID).
stub_path (str): Path of the stub left under the old alias.
stub_meta (dict): Meta of the stub.
migrated_to (str): The new alias,UID.
migrated_when (str): When, ISO 8601 in UTC.

Return type:

dict

Raises:

Exception – Propagated runtime errors, if any.

index(params: dict)[source]

Index artifact(s).

@base.create_(**params, index=True)

Parameters:: params (dict) – cMeta params.
Returns:: A cMeta dictionary (see move_ for details).
Return type:: dict
Raises:: Exception – Propagated runtime errors, if any.

reindex_(ctx: dict, arg1: str = None, tags: str = None, sort: bool = True, skip_uids: bool = False, ignore_errors: bool = False)[source]

Refresh the index record(s) of artifact(s) from their folders, changing no file.

The meta file of each artifact is read from its folder on disk and the artifact’s record in the index of the category is rewritten from it: the alias is the folder’s name, every other alias that still pointed at the artifact’s UID is dropped, and the path, the meta and the sharding depth are what a full cx –reindex records. The meta file is read, never written (an empty update rewrites it). Use it after a meta file was edited by hand, after a folder was renamed, moved or copied in from another machine, or when a lookup looks stale - instead of the whole cx –reindex.

The artifact may be named by its alias, UID, alias,UID or repo:alias, with wildcards; nothing names every artifact of the category. A folder the index does not know yet (made or renamed by hand) is found on disk in the repositories; an artifact whose indexed folder is gone is looked for by its UID in its repository. No folder is touched, and the only record ever removed is that of an artifact whose folder, still there, holds another artifact now (replaced by hand) - said in the output. A folder that cannot be found, a meta without a valid artifact UID, or a UID found in two existing folders is an error, and the index is left as it was (–ignore_errors reindexes the other artifacts and reports these).

Parameters:

ctx (dict) – cMeta context.
arg1 (str | None) – Artifact alias, UID, alias,UID or repo:alias (wildcards allowed); nothing names every artifact of the category.
tags (str | list | None) – Prune the artifacts by tags, as in find (a leading “-” excludes).
sort (bool) – Sort the artifacts by alias and UID.
skip_uids (bool) – Skip UIDs when using wildcards.
ignore_errors (bool) – Go on past an artifact that cannot be reindexed and report it at the end.

Returns:

A cMeta dictionary with the following keys:

return (int): 0 if success, >0 if error (16: nothing found).
error (str): Error message if return > 0.
artifacts (list): The reindexed artifacts, as their new index records.
dropped_aliases (dict): Per UID, the (lowercase) aliases dropped because they were not the folder’s name.
dropped_records (list): The records removed because their folder holds another artifact now (ref, path, now).
errors (list): With ignore_errors, one dict per artifact that could not be reindexed (ref, path, error).

Return type:

dict

Raises:

Exception – Propagated runtime errors, if any.

get_(ctx: dict, arg1: str = None, tags: str = None, skip_uids: bool = False, yaml: bool = False, meta: dict = {}, virtual: bool = False, path: str = None, show_path: bool = False, load_files=[])[source]

Get artifact meta. Read if exists, create and read if doesn’t exist.

Parameters:

ctx (dict) – cMeta context.
arg1 (str | None) – Artifact alias or UID.
tags (str | list | None) – Tags to add to the artifact (used during creation).
skip_uids (bool) – Skip UIDs when using wildcards.
yaml (bool) – Save/output metadata as YAML instead of JSON.
meta (dict) – Initial metadata dictionary (used during creation).
virtual (bool) – Virtual artifact created only in index (used during creation).
path (str | None) – Use this path for artifact (used during creation).
show_path (bool) – Print path instead of meta
load_files – Value for load files.

Returns:

A cMeta dictionary with the following keys:

return (int): 0 if success, >0 if error.
error (str): Error message if return > 0.
artifact (dict): Matched artifact.
cmeta (dict): Artifact metadata.
created (bool): True if artifact was created, False if it already existed.

Return type:

dict

Raises:

Exception – Propagated runtime errors, if any.

set_(ctx: dict, arg1: str = None, tags: str = None, skip_uids: bool = False, yaml: bool = False, meta: dict = {}, virtual: bool = False, path: str = None, show_path: bool = False)[source]

Set artifact meta. Update and read if exists, create and read if doesn’t exist.

Parameters:

ctx (dict) – cMeta context.
arg1 (str | None) – Artifact alias or UID.
tags (str | list | None) – Tags to add to the artifact (used during creation).
skip_uids (bool) – Skip UIDs when using wildcards.
yaml (bool) – Save/output metadata as YAML instead of JSON.
meta (dict) – Initial metadata dictionary (used during creation).
virtual (bool) – Virtual artifact created only in index (used during creation).
path (str | None) – Use this path for artifact (used during creation).
show_path (bool) – Print path instead of meta

Returns:

A cMeta dictionary with the following keys:

return (int): 0 if success, >0 if error.
error (str): Error message if return > 0.
artifact (dict): Matched artifact.
cmeta (dict): Artifact metadata.
created (bool): True if artifact was created, False if it already existed.

Return type:

dict

Raises:

Exception – Propagated runtime errors, if any.

Functions

cmeta.category_api_v1.apply_artifact_defaults(cmeta: dict, repo_meta: dict = None, env: dict = None, cfg: dict = None, creating: bool = True, today: str = None)[source]

Stamp who made an artifact and how: authors, copyright and generator.

When an artifact is created, keys already in its meta are kept, and missing ones are filled:

authors: CMETA_AUTHORS, else artifact_defaults.authors of the repository (the person at work comes before the repository default);
copyright: artifact_defaults.copyright of the repository, else CMETA_COPYRIGHT (the repository decides who holds the copyright);
generator: CMETA_GENERATOR (set by the task or agent that is running), else artifact_defaults.generator of the repository; “by” defaults to the authors.

When an artifact is updated and CMETA_GENERATOR is set, “last_generator” records it with the date, so a regeneration stays visible next to how the artifact was created.

Returns:: The same cmeta.
Return type:: dict

cMeta stable releases and API

cmeta.category_api_v1 module

Classes

Functions