copy (cp) | Copy artifact(s).signature
def copy__(
self,
params: dict, # cMeta params.
):
"""
Copy artifact(s).
@base.move_(**params, copy=True)
Args:
params (dict): cMeta params.
Returns:
dict: A cMeta dictionary (see move_ for details).
Raises:
Exception: Propagated runtime errors, if any.
"""
|
create (add) | Create and index an artifact.signature
def create_(
self,
ctx: dict, # cMeta context.
arg1: str = None, # Artifact alias or UID.
tags: str = None, # Tags to add to the artifact.
meta: dict = {}, # Initial metadata dictionary.
yaml: bool = False, # Save metadata as YAML instead of JSON.
virtual: bool = False, # 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 = False, # If true and path exists but not index, just add to index
# Useful when AI agents create cMeta entries while bypassing cMeta
):
"""
Create and index an artifact.
Args:
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:
dict: 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.
Raises:
Exception: Propagated runtime errors, if any.
"""
|
delete (rm|remove|del) | Delete and unindex artifact(s).signature
def delete_(
self,
ctx: dict, # cMeta context.
arg1: str = None, # Artifact alias or UID.
tags: str = None, # Optional tag filter.
sort: bool = True, # Sort artifacts by alias and UID.
force: bool = False, # Force deletion without confirmation.
f: bool = False, # Shorthand for force.
skip_uids: bool = False, # Skip UIDs when using wildcards.
ignore_errors: bool = False, # Ignore errors when deleting multiple artifacts.
print_time: bool = False, # Print time per deletion.
match: dict = None, # Value for match.
match_empty_version: bool = False, # Value for match empty version.
all_tags: str = None, # Value for all tags.
):
"""
Delete and unindex artifact(s).
Args:
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:
dict: 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.
Raises:
Exception: Propagated runtime errors, if any.
"""
|
find (search) | Find artifacts.signature
def find_(
self,
ctx: dict, # cMeta context.
arg1: str = None, # Artifact alias or UID.
tags: str = None, # Comma-separated string or iterable of tags to match.
sort: bool = None, # Sort by path (True by default).
add_index_file: bool = False, # Add index file information.
skip_uids: bool = False, # Skip UIDs when using wildcards.
match: dict = None, # Value for match.
match_empty_version: bool = False, # Value for match empty version.
match_empty_values: bool = False, # Match when queried values or keys are empty.
all_tags: str = None, # Value for all tags.
load_files = [], # Load files (omit extension to load either yaml or json)
follow_migrated: bool = True, # Follow an old alias left by "migrate" to its artifact.
):
"""
Find artifacts.
Args:
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:
dict: 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.
Raises:
Exception: Propagated runtime errors, if any. \
"""
|
get | Get artifact meta. Read if exists, create and read if doesn't exist.signature
def get_(
self,
ctx: dict, # cMeta context.
arg1: str = None, # Artifact alias or UID.
tags: str = None, # Tags to add to the artifact (used during creation).
skip_uids: bool = False, # Skip UIDs when using wildcards.
yaml: bool = False, # Save/output metadata as YAML instead of JSON.
meta: dict = {}, # Initial metadata dictionary (used during creation).
virtual: bool = False, # Virtual artifact created only in index (used during creation).
path: str = None, # Use this path for artifact (used during creation).
show_path: bool = False, # Print path instead of meta
load_files = [], # Value for load files.
):
"""
Get artifact meta. Read if exists, create and read if doesn't exist.
Args:
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:
dict: 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.
Raises:
Exception: Propagated runtime errors, if any.
"""
|
index | Index artifact(s).signature
def index(
self,
params: dict, # cMeta params.
):
"""
Index artifact(s).
@base.create_(**params, index=True)
Args:
params (dict): cMeta params.
Returns:
dict: A cMeta dictionary (see move_ for details).
Raises:
Exception: Propagated runtime errors, if any.
"""
|
info | Get artifact info.signature
def info_(
self,
ctx: dict, # cMeta context.
arg1: str = None, # Artifact alias or UID.
clip: bool = True, # If True, copy cRef to clipboard.
url: bool = False, # If True, copy URL with detected cRef to the clipboard.
name: bool = False, # If True, copy artifact name to the clipboard
):
"""
Get artifact info.
Args:
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:
dict: 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.
Raises:
Exception: Propagated runtime errors, if any.
"""
|
list (ls) | List artifact names.signature
def list_(
self,
ctx: dict, # cMeta context.
arg1: str = None, # Artifact alias or UID.
tags: str = None, # Optional tag filter.
sort: bool = None, # Sort by alias or UID.
skip_uids: bool = False, # Skip UIDs when using wildcards.
):
"""
List artifact names.
Args:
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:
dict: 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.
Raises:
Exception: Propagated runtime errors, if any.
"""
|
migrate | Rename an artifact (or move it to another repository under a new alias) and leave asignature
def migrate_(
self,
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 = None, # Prune the source artifact by tags.
):
"""
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.
Args:
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:
dict: 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.
Raises:
Exception: Propagated runtime errors, if any.
"""
|
move (ren|rename|mv) | Rename and/or move artifact(s).signature
def move_(
self,
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 = None, # Prune source artifacts by tags.
sort: bool = True, # Sort artifacts by alias and UID when updating in batch.
skip_uids: bool = False, # Skip UIDs when using wildcards.
ignore_errors: bool = False, # Ignore errors when updating multiple artifacts.
copy: bool = False, # If True, copy artifact instead of moving.
):
"""
Rename and/or move artifact(s).
Args:
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:
dict: 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.
Raises:
Exception: Propagated runtime errors, if any.
"""
|
read (load) | Read artifact meta.signature
def read_(
self,
ctx: dict, # cMeta context.
arg1: str = None, # Artifact alias or UID.
tags: str = None, # Optional tag filter.
extra: bool = False, # Show extra info.
skip_uids: bool = False, # Skip UIDs when using wildcards.
yaml: bool = False, # Output as YAML instead of JSON.
load_files = [], # Value for load files.
):
"""
Read artifact meta.
Args:
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:
dict: 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.
Raises:
Exception: Propagated runtime errors, if any.
"""
|
reindex | Refresh the index record(s) of artifact(s) from their folders, changing no file.signature
def reindex_(
self,
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 = None, # Prune the artifacts by tags, as in find (a tag with a leading "-" excludes).
sort: bool = True, # Sort the artifacts by alias and UID.
skip_uids: bool = False, # Skip UIDs when using wildcards.
ignore_errors: bool = False, # Go on past an artifact that cannot be reindexed and report it at the end.
):
"""
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).
Args:
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:
dict: 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`).
Raises:
Exception: Propagated runtime errors, if any.
"""
|
set | Set artifact meta. Update and read if exists, create and read if doesn't exist.signature
def set_(
self,
ctx: dict, # cMeta context.
arg1: str = None, # Artifact alias or UID.
tags: str = None, # Tags to add to the artifact (used during creation).
skip_uids: bool = False, # Skip UIDs when using wildcards.
yaml: bool = False, # Save/output metadata as YAML instead of JSON.
meta: dict = {}, # Initial metadata dictionary (used during creation).
virtual: bool = False, # Virtual artifact created only in index (used during creation).
path: str = None, # Use this path for artifact (used during creation).
show_path: bool = False, # Print path instead of meta
):
"""
Set artifact meta. Update and read if exists, create and read if doesn't exist.
Args:
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:
dict: 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.
Raises:
Exception: Propagated runtime errors, if any.
"""
|
tags | Find unique tags in artifacts.signature
def tags_(
self,
ctx: dict, # cMeta context.
arg1: str = None, # Artifact alias or UID.
tags: str = None, # Comma-separated string or iterable of tags to match.
sort: bool = False, # Value for sort.
):
"""
Find unique tags in artifacts.
Args:
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:
dict: 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.
Raises:
Exception: Propagated runtime errors, if any.
"""
|
test | Test category.signature
def test(
self,
params: dict, # Parameters dictionary.
):
"""
Test category.
Args:
params (dict): Parameters dictionary.
Returns:
dict: A cMeta dictionary with the following keys:
- **return** (int): 0 if success, >0 if error.
Raises:
Exception: Propagated runtime errors, if any.
"""
|
update | Update artifact(s).signature
def update_(
self,
ctx: dict, # Execution context dictionary with category, command, and control data.
arg1: str = None, # First positional argument from command input.
tags: str = None, # Value for tags.
sort: bool = True, # Value for sort.
skip_uids: bool = False, # If True, skip UID validation in wildcard lookups.
meta: dict = {}, # Metadata dictionary to persist.
new_tags: str = None, # Value for new tags.
replace_lists: bool = False, # Value for replace lists.
replace: bool = False, # Value for replace.
ignore_errors: bool = False, # Value for ignore errors.
create: bool = False, # Value for create.
create_params: dict = {}, # Value for create params.
update_category: bool = False, # Value for update category.
match: dict = None, # Value for match.
match_empty_version: bool = False, # Value for match empty version.
all_tags: str = None, # Value for all tags.
):
"""
Update artifact(s).
Args:
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:
dict: 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.
Raises:
Exception: Propagated runtime errors, if any.
"""
|
