cmeta.utils.names module

Reusable functions to handle cMeta objects

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

cMeta UID = 16 hex characters cMeta alias = any adopted filename in Linux, Windows and MacOS (since we keep them as directories i repositories)

cMeta name = alias | UID | alias,UID

repo_name = repo_alias | repo_uid | repo_alias,repo_uid repo == repo_name

artifact_name = artifact_alias | artifact_uid | artifact_alias,artifact_uid artifact_name_dict = {‘artifact_alias’, ‘artifact_uid’}

artifact_obj = (artifact_repo_name:)artifact_name artifact_obj_dict = {artifact_repo_alias, artifact_repo_uid, artifact_alias, artifact_uid} artifact == artifact_obj

category_name = category_alias | category_uid | category_alias,category_uid category_name_dict = {category_alias, category_uid}

category_obj = (category_repo_name:)category_name category_obj_dict = {category_repo_alias, category_repo_uid, category_alias, category_uid} category == category_obj

cmeta_ref = category_obj::artifact_obj cmeta_ref_dict = {category_repo_alias, category_repo_uid, category_alias, category_uid,

artifact_repo_alias, artifact_repo_uid, artifact_alias, artifact_uid}

cRef == cmeta_ref

Find in Fast index:

records = list of artifacts following search criteria record = {‘path’,

‘cmeta_ref_parts’, ‘cmeta’}

Functions

cmeta.utils.names.generate_cmeta_uid() → str[source]

Generate a new 16-character UID (from UUID4).

Returns:: A new 16-character hexadecimal UID string.
Return type:: str

cmeta.utils.names.get_sort_key_cmeta_obj_alias_or_uid(item: dict)[source]

Get a sort key from a CMeta object for sorting by alias or UID.

Extracts the artifact identifier for sorting, prioritizing lowercase alias, then regular alias, then UID.

Parameters:: item (dict) – Dictionary containing ‘cmeta_ref_parts’ with artifact identifiers.
Returns:: The artifact’s lowercase alias, alias, or UID for sorting.
Return type:: str or None

cmeta.utils.names.is_valid_category_alias(alias: str)[source]

Validate if category alias is valid (Windows, Linux, MacOS)

Parameters:: alias (str) – The string to validate as category alias.
Returns:: Dictionary with ‘return’: 0 if valid, or ‘return’: 1 and ‘error’ if invalid.
Return type:: dict

cmeta.utils.names.is_valid_cmeta_alias(alias: str)[source]

Validate if alias is valid for Windows, Linux, and MacOS filesystems.

Checks for invalid characters and problematic patterns that would cause issues when used as directory names across different operating systems.

Parameters:: alias (str) – The string to validate as a CMeta alias.
Returns:: Dictionary with ‘return’: 0 if valid, or ‘return’: 1 and ‘error’ if invalid.
Return type:: dict

cmeta.utils.names.is_valid_cmeta_uid(text: str) → bool[source]

Validate if UID is a valid 16-character hex string (case-insensitive).

Parameters:: text (str) – The string to validate as a UID.
Returns:: True if the text is a valid 16-character hex string, False otherwise.
Return type:: bool

cmeta.utils.names.parse_cmeta_name(name: str | Dict[str, Any] | None, key: str | None = None) → Dict[str, Any][source]

Parse cMeta name (alias | uid | alias,uid), returning a dict.

Parameters:

name (Optional[str|dict]) – The name string or dict to parse. Can be None.
key (Optional[str]) – If provided, keys will be ‘{key}_alias’ and ‘{key}_uid’.

Returns:

{‘return’: 0, ‘name’: {keyed alias/uid or just alias/uid}}.: If error, returns {‘return’: 1, ‘error’: …} If input is dict, returns it unchanged as {‘return’: 0, ‘name’: name}

Return type:

Dict[str, Any]

cmeta.utils.names.parse_cmeta_obj(obj: str | Dict[str, Any] | None, key: str | None = None, fail_on_error: bool = False) → Dict[str, Any][source]

Parse cMeta object string (repo_name:cmeta_name or cmeta_name) into dict.

Parameters:

obj (Optional[str|dict]) – Object string or dict to parse.
key (Optional[str]) – Optional key prefix for dict keys.
fail_on_error (bool) – If True, raise error on failure.

Returns:

{‘return’: 0, ‘obj_parts’: {repo/name parts}}.: If error, returns {‘return’: 1, ‘error’: …} If input is dict, returns it unchanged as {‘return’: 0, ‘obj_parts’: obj}

Return type:

Dict[str, Any]

cmeta.utils.names.parse_cmeta_ref(ref: str | Dict[str, Any] | None, fail_on_error: bool = False) → Dict[str, Any][source]

Parse cMeta ref string (category_obj::artifact_obj) into dict.

Parameters:

ref (Optional[str|dict]) – Ref string or dict to parse.
fail_on_error (bool) – If True, raise error on failure.

Returns:

{‘return’: 0, ‘ref_parts’: {category/artifact parts}}.: If error, returns {‘return’: 1, ‘error’: …} If input is dict, returns it unchanged as {‘return’: 0, ‘ref_parts’: ref}

Return type:

Dict[str, Any]

cmeta.utils.names.restore_cmeta_name(name: Dict[str, Any], key: str | None = None, fail_on_error: bool = False) → Dict[str, Any][source]

Restore cMeta name string from canonicalized dict.

Parameters:

name (Dict[str, Any]) – Dict containing alias/uid or {key}_alias/{key}_uid.
key (Optional[str]) – Optional key to use for lookup.
fail_on_error (bool) – If True, raise error on failure.

Returns:

{‘return’: 0, ‘name’: restored_string}.: If error, returns {‘return’: 1, ‘error’: …}

Return type:

Dict[str, Any]

cmeta.utils.names.restore_cmeta_obj(obj_parts: Dict[str, Any], key: str | None = None, fail_on_error: bool = False) → Dict[str, Any][source]

Restore cMeta object string from canonicalized dict.

Parameters:

obj_parts (Dict[str, Any]) – Dict with repo/name parts.
key (Optional[str]) – Optional key prefix.
fail_on_error (bool) – If True, raise error on failure.

Returns:

{‘return’: 0, ‘obj’: restored_string}.: If error, returns {‘return’: 1, ‘error’: …}

Return type:

Dict[str, Any]

cmeta.utils.names.restore_cmeta_ref(ref_parts: Dict[str, Any], fail_on_error: bool = False) → Dict[str, Any][source]

Restore cMeta ref string from canonicalized dict.

Parameters:

ref_parts (Dict[str, Any]) – Dict with category/artifact parts.
fail_on_error (bool) – If True, raise error on failure.

Returns:

{‘return’: 0, ‘ref’: restored_string}.: If error, returns {‘return’: 1, ‘error’: …}

Return type:

Dict[str, Any]

cMeta installation

cmeta.utils.names module

Functions