cmeta.repos module

cMeta repositories manager

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.repos.Repos(cfg: Dict[str, Any], home_path: Path, index_path: Path, repos_config_path: Path, logger: Logger = None, index_extension: str = '.pkl', fail_on_error: bool = False, match_version_func=None)

Bases: object

cMeta repositories manager.

__init__(cfg: Dict[str, Any], home_path: Path, index_path: Path, repos_config_path: Path, logger: Logger = None, index_extension: str = '.pkl', fail_on_error: bool = False, match_version_func=None)

Initialize Repos manager.

Parameters:

• cfg (Dict[str, Any]) – Configuration dictionary.

• home_path (Path) – Path to repositories directory.

• index_path (Path) – Path to index directory.

• repos_config_path (Path) – Path to repositories config file.

• logger (logging.Logger | None) – Logger instance (optional).

• index_extension (str) – Index file extension.

• fail_on_error (bool) – If True, raise exception on error.

• match_version_func – Callback used to evaluate version matching rules.

Returns:

Operation result.

Return type:

dict

Raises:

Exception – Propagated runtime errors, if any.

init(con: bool = False, verbose: bool = False)

Initialize repositories and index if running for the first time.

Creates repos directory, local repository, and triggers reindexing if needed.

Parameters:

• con (bool) – Console mode flag (for compatibility).

• verbose (bool) – Enable verbose output (for compatibility).

Returns:

Dictionary with ‘return’: 0 on success, or ‘return’ > 0 and ‘error’ on failure.

Return type:

dict

Raises:

Exception – Propagated runtime errors, if any.

add_to_index(cmeta, cmeta_ref_parts, path, original_alias=None, original_uid=None)

Insert or update an artifact record in the category index.

Parameters:

• cmeta – Artifact metadata dictionary.

• cmeta_ref_parts – Parsed cMeta reference components.

• path – Filesystem path.

• original_alias – Previous artifact alias before update.

• original_uid – Previous artifact UID before update.

Returns:

Operation result.

Return type:

dict

Raises:

Exception – Propagated runtime errors, if any.

remove_from_index(index_file, artifact_uid, artifact_alias_lowercase)

Remove an artifact from the repository index.

Parameters:

• index_file – Path to index file.

• artifact_uid – UID of artifact to remove.

• artifact_alias_lowercase – Lowercase alias of artifact to remove from alias index.

Returns:

Dictionary with ‘return’: 0 on success, or ‘return’ > 0 and ‘error’ on failure.

Return type:

dict

Raises:

Exception – Propagated runtime errors, if any.

find_in_index(category_alias, category_uid, artifact_alias=None, artifact_uid=None, repos=[], only_uids=False, add_index_file=False, skip_uids=False)

Find artifacts in the repository index.

Parameters:

• category_alias – Lowercase category alias.

• category_uid – Category UID.

• artifact_alias – Artifact alias to search for.

• artifact_uid – Artifact UID to search for.

• repos – List of repository names to search in.

• only_uids – If True, return only UIDs without full metadata.

• add_index_file – If True, include index_file path in result.

• skip_uids – If True, skip UID validation.

Returns:

Dictionary with ‘return’: 0 and ‘lst’ containing found artifacts,

or ‘return’ > 0 and ‘error’ on failure.

Return type:

dict

Raises:

Exception – Propagated runtime errors, if any.

find_in_file_system(category_meta, category_alias, category_uid, artifact_alias=None, artifact_uid=None, repo_uids=[])

Find artifacts by scanning directories instead of using index. Used for categories with no_index flag.

Parameters:

• category_meta – Category metadata dictionary used for file-system search.

• category_alias – Category alias (lowercase)

• category_uid – Category UID

• artifact_alias – Optional artifact alias (supports wildcards)

• artifact_uid – Optional artifact UID

• repo_uids – List of repository UIDs to limit file-system search.

Returns:

{‘return’: 0, ‘artifacts’: […]} or error

Return type:

dict

Raises:

Exception – Propagated runtime errors, if any.

find(cmeta_ref: str, add_index_file: bool = False, tags: str = None, skip_uids: bool = False, skip_non_indexed: bool = False, match: bool = None, match_empty_version: bool = False, all_tags: str = None)

Find artifacts by cMeta reference.

Parameters:

• cmeta_ref (str) – cMeta reference string or parsed dictionary.

• add_index_file (bool) – If True, include index_file path in result.

• tags (str) – Optional tags to filter results.

• skip_uids (bool) – If True, skip UID validation.

• skip_non_indexed (bool) – Value for skip non indexed.

• match (bool) – Optional match dictionary to filter results (key that ends with - is supported)

• match_empty_version (bool) – Value for match empty version.

• all_tags (str) – match all tags in cmeta

Returns:

Dictionary with ‘return’: 0 and ‘artifacts’ list on success,

or ‘return’ > 0 and ‘error’ on failure.

Return type:

dict

Raises:

Exception – Propagated runtime errors, if any.

reindex(con=False, verbose=False)

Clean index and reindex all repositories.

Removes existing index files and rebuilds them by scanning all repositories.

Parameters:

• con – If True, print console messages during reindexing.

• verbose – If True, print detailed progress information.

Returns:

Dictionary with ‘return’: 0 on success, or ‘return’ > 0 and ‘error’ on failure.

Return type:

dict

Raises:

Exception – Propagated runtime errors, if any.

index(clean=False, con=False, verbose=False, add_repo_paths=[], delete_repo_paths=[])

Index repos

Parameters:

• clean – If True, clear and rebuild index artifacts from scratch.

• con – If True, print output to console.

• verbose – If True, enable verbose output.

• add_repo_paths – Repository paths to add before indexing.

• delete_repo_paths – Repository paths to remove before indexing.

Returns:

Operation result.

Return type:

dict

Raises:

Exception – Propagated runtime errors, if any.