cmeta.category_api_v1 module

CMeta base category class

cMeta author and developer: (C) 2025-2026 Grigori Fursin

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

Classes

class cmeta.category_api_v1.Category(*args, **kwargs)

Bases: InitCategory

Standard Base Category with artifact management functions

__init__(*args, **kwargs)

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)

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)

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, all_tags: str = None, load_files=[])

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.

• all_tags (str) – Value for all tags.

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)

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)

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

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)

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=[])

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)

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.

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)

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

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)

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)

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.

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=[])

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)

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.