mlcflow 1.2.4__tar.gz → 1.2.6__tar.gz

{mlcflow-1.2.4 → mlcflow-1.2.6}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: mlcflow
-Version: 1.2.4
+Version: 1.2.6
 Summary: An automation interface tailored for CPU/GPU benchmarking
 Author-email: MLCommons <systems@mlcommons.org>
 License: 

mlcflow-1.2.6/mlc/error_codes.py

@@ -0,0 +1,209 @@
+import re
+from enum import Enum, auto
+
+
+class ErrorCode(Enum):
+    """Enum class for error codes in MLCFlow"""
+    # General errors (2000-2007)
+    AUTOMATION_SCRIPT_NOT_FOUND = (
+        2000, "The specified automation script was not found")
+    PATH_DOES_NOT_EXIST = (2001, "Provided path does not exists")
+    FILE_NOT_FOUND = (2002, "Required file was not found")
+    PERMISSION_DENIED = (2003, "Insufficient permission to execute the script")
+    IO_Error = (2004, "File I/O operation failed")
+    AUTOMATION_CUSTOM_ERROR = (2005, "Custom error triggered by the script")
+    UNSUPPORTED_OS = (
+        2006, "The Operating System is not supported by the script")
+    MISSING_ENV_VARIABLE = (2007, "Required environment variables are missing")
+
+    def __init__(self, code, description):
+        self.code = code
+        self.description = description
+
+
+ERROR_CODES = {error.code for error in ErrorCode}
+ERROR_CODE_PATTERNS = [
+    re.compile(r'(?:error|exit|return)\s+code\s*[:=]?\s*(\d+)', re.IGNORECASE),
+    re.compile(r'\[errno\s+(\d+)\]', re.IGNORECASE),
+    re.compile(r'signal\s+(\d+)', re.IGNORECASE),
+]
+
+
+class WarningCode(Enum):
+    """Enum class for warning codes in MLCFlow"""
+    # General warnings (1000-1007)
+    IO_WARNING = (1000, "File I/O operation warning")
+    AUTOMATION_SCRIPT_NOT_TESTED = (
+        1001,
+        "the script is not tested on the current operatinig system or is in a development state")
+    AUTOMATION_SCRIPT_SKIPPED = (
+        1002, "The script has been skipped during execution")
+    AUTOMATION_CUSTOM_ERROR = (1003, "Custom warning triggered by the script")
+    NON_INTERACTIVE_ENV = (1004, "Non interactive environment detected")
+    ELEVATED_PERMISSION_NEEDED = (1005, "Elevated permission needed")
+    EMPTY_TARGET = (1006, "The specified target is empty")
+
+    def __init__(self, code, description):
+        self.code = code
+        self.description = description
+
+
+def get_error_info(error_code):
+    """Get the error message for a given error code"""
+    try:
+        return {"error_code": ErrorCode(
+            error_code).code, "error_message": ErrorCode(error_code).description}
+    except ValueError:
+        return f"Unknown error code: {error_code}"
+
+
+def get_warning_info(warning_code):
+    """Get the warning message for a given warning code"""
+    try:
+        return {"warning_code": WarningCode(
+            warning_code).code, "warning_message": WarningCode(warning_code).description}
+    except ValueError:
+        return f"Unknown warning code: {warning_code}"
+
+
+def is_warning_code(code):
+    """Check if a given code is a warning code"""
+    try:
+        # Check if code is in warning range (2000-2399)
+        if 2000 <= code <= 2399:
+            WarningCode(code)
+            return True
+        return False
+    except ValueError:
+        return False
+
+
+def is_error_code(code):
+    """Check if a given code is an error code"""
+    try:
+        # Check if code is in error range (1000-1399)
+        if 1000 <= code <= 1399:
+            ErrorCode(code)
+            return True
+        return False
+    except ValueError:
+        return False
+
+
+def get_code_type(code):
+    """Get the type of a code (error or warning)"""
+    if is_error_code(code):
+        return "error"
+    elif is_warning_code(code):
+        return "warning"
+    else:
+        return "unknown"
+
+
+def _normalize_code(code):
+    """Convert a code value to int when possible."""
+    if code is None:
+        return None
+    if isinstance(code, int):
+        return code
+    try:
+        return int(str(code).strip())
+    except (TypeError, ValueError):
+        return None
+
+
+def detect_error_code(return_code=None, error_message=""):
+    """Detect the most useful error code from a return value or error text."""
+    normalized_return_code = _normalize_code(return_code)
+    message = error_message or ""
+
+    for pattern in ERROR_CODE_PATTERNS:
+        match = pattern.search(message)
+        if match:
+            detected = _normalize_code(match.group(1))
+            # Prefer the code extracted from the error text when the outer
+            # result only carries a generic status such as 1.
+            if normalized_return_code in (None, 0, 1):
+                return detected
+
+    return normalized_return_code
+
+
+def get_error_guidance(return_code=None, error_message=""):
+    """Return actionable guidance for known error codes and failure patterns."""
+    error_code = detect_error_code(return_code, error_message)
+    guidance = {
+        "error_code": error_code,
+        "error_message": None,
+        "suggestions": [],
+    }
+
+    if error_code in ERROR_CODES:
+        error_info = get_error_info(error_code)
+        if isinstance(error_info, dict):
+            guidance["error_message"] = error_info["error_message"]
+
+    message = (error_message or "").lower()
+
+    if ("no space left on device" in message or
+            "disk full" in message or
+            "not enough space" in message):
+        guidance["error_message"] = guidance["error_message"] or \
+            "Likely disk space exhaustion while running the script"
+        guidance["suggestions"] = [
+            "Free disk space in the work/cache directories and retry the command.",
+            "Remove old artifacts or caches if they are no longer needed.",
+        ]
+    # 139 = 128 + SIGSEGV(11), while some tools report the raw signal number
+    # 11 or its negative form -11.
+    elif ("segmentation fault" in message or error_code in [139, -11, 11]):
+        guidance["error_message"] = guidance["error_message"] or \
+            "A native program crashed with a segmentation fault"
+        guidance["suggestions"] = [
+            "Rerun with verbose logs to identify which native command crashed.",
+            "Check native dependencies, compiler/runtime compatibility, and input files.",
+        ]
+    # Common downloader/network failure codes used by curl and similar tools:
+    # 6/7 resolve/connect failures, 28 timeout, 35 TLS/connect issue,
+    # 56 connection reset/read failure, 60 certificate validation failure.
+    elif ("network" in message or
+          "connection" in message or
+          "timed out" in message or
+          "temporary failure in name resolution" in message or
+          "could not resolve host" in message or
+          error_code in [6, 7, 28, 35, 56, 60]):
+        guidance["error_message"] = guidance["error_message"] or \
+            "Likely network or download failure while running the script"
+        guidance["suggestions"] = [
+            "Check internet connectivity, proxy/firewall settings, and remote endpoint availability.",
+            "Retry the command after verifying the network connection.",
+        ]
+    elif error_code == 126:
+        guidance["error_message"] = guidance["error_message"] or \
+            "Command found but it could not be executed"
+        guidance["suggestions"] = [
+            "Check file permissions and whether the target command is executable.",
+        ]
+    elif error_code == 127:
+        guidance["error_message"] = guidance["error_message"] or \
+            "Command not found during script execution"
+        guidance["suggestions"] = [
+            "Verify that the required tool is installed and available on PATH.",
+        ]
+    elif error_code == 137:
+        guidance["error_message"] = guidance["error_message"] or \
+            "Process was terminated, often due to out-of-memory or a kill signal"
+        guidance["suggestions"] = [
+            "Check system memory limits and retry with fewer parallel jobs if possible.",
+        ]
+    elif error_code == 130:
+        guidance["error_message"] = guidance["error_message"] or \
+            "The command was interrupted by the user or the environment"
+        guidance["suggestions"] = [
+            "Retry the command if the interruption was unexpected.",
+        ]
+
+    if not guidance["error_message"] and not guidance["suggestions"]:
+        return None
+
+    return guidance

{mlcflow-1.2.4 → mlcflow-1.2.6}/mlc/index.py

@@ -232,8 +232,12 @@ class Index:
 
                 if os.path.isfile(yaml_path):
                     config_path = yaml_path
+                    with open(config_path, "r") as f:
+                        data = yaml.safe_load(f) or {}
                 elif os.path.isfile(json_path):
                     config_path = json_path
+                    with open(config_path, "r") as f:
+                        data = json.load(f) or {}
                 else:
                     # No config file found, remove from index if exists
                     delete_flag = False
@@ -257,6 +261,7 @@ class Index:
                     if delete_flag:
                         changed = True
                     continue
+
                 if current_item_keys is not None:
                     current_item_keys.add(config_path)
                 mtime = self.get_item_mtime(config_path)
@@ -266,6 +271,19 @@ class Index:
                 if old_mtime == mtime and not repos_changed:
                     continue
 
+                # Validate script meta against schema during indexing if meta
+                # changed or repos changed
+                if folder_type == "script":
+                    # logger.debug(f"-----Meta changed for {automation_path}, validating against schema... -----")
+                    errors, warnings = validate_meta(data, config_path)
+                    for e in errors:
+                        logger.error(f"Meta validation error: {e}")
+                    for w in warnings:
+                        logger.debug(f"Meta validation warning: {w}")
+                    if errors:
+                        raise ValueError(
+                            f"Meta validation failed for {config_path}. Fix the above error(s) and try again.")
+
                 self.modified_times[config_path] = {
                     "mtime": mtime,
                     "date_time": datetime.fromtimestamp(mtime).strftime("%Y-%m-%d %H:%M:%S")
@@ -400,17 +418,6 @@ class Index:
             tags = data.get("tags", [])
             alias = data.get("alias", None)
 
-            # Validate script meta against schema during indexing
-            if folder_type == "script":
-                errors, warnings = validate_meta(data, config_file)
-                for e in errors:
-                    logger.error(f"Meta validation error: {e}")
-                for w in warnings:
-                    logger.debug(f"Meta validation warning: {w}")
-                if errors:
-                    raise ValueError(
-                        f"Meta validation failed for {config_file}. Fix the above error(s) and try again.")
-
             # Remove stale entry for the same meta file path if exists
             self._delete_index_entries(folder_type, "path", folder_path)
 

{mlcflow-1.2.4 → mlcflow-1.2.6}/mlc/main.py

@@ -155,6 +155,7 @@ def _report_error(e):
         script_name = e.script_name
         repo_alias = e.repo_alias
         run_args = e.run_args
+        error_guidance = e.error_guidance or {}
 
         if script_name:
             # Build rerun command with user-facing inputs only
@@ -181,6 +182,18 @@ def _report_error(e):
             logger.error(f"Failed script: {script_name}")
             logger.error(f"To rerun just the failed part: {rerun_cmd}")
 
+        if error_guidance:
+            error_code = error_guidance.get("error_code")
+            if error_code is not None:
+                logger.error(f"Detected error code: {error_code}")
+
+            error_message = error_guidance.get("error_message")
+            if error_message:
+                logger.error(f"Likely cause: {error_message}")
+
+            for suggestion in error_guidance.get("suggestions", []):
+                logger.error(f"Suggestion: {suggestion}")
+
         if e.version_info_file:
             logger.error(f"Dependency versions: {e.version_info_file}")
 
@@ -377,7 +390,7 @@ def build_parser(pre_args):
     reindex_parser.add_argument('extra', nargs=argparse.REMAINDER)
 
     # Script-only
-    for action in ['docker', 'docker-run', 'apptainer',
+    for action in ['docker', 'docker-run', 'apptainer', 'apptainer-run',
                    'experiment', 'remote-run', 'remote-experiment',
                    'remote-docker', 'doc', 'lint']:
         p = subparsers.add_parser(action, add_help=False)
@@ -419,8 +432,8 @@ def build_run_args(args):
     if args.command in ['pull', 'rm', 'add', 'find'] and args.target == "repo":
         run_args['repo'] = args.details
 
-    if args.command in ['docker', 'docker-run', 'apptainer', 'experiment',
-                        'remote-run', 'remote-experiment',
+    if args.command in ['docker', 'docker-run', 'apptainer', 'apptainer-run',
+                        'experiment', 'remote-run', 'remote-experiment',
                         'remote-docker', 'doc', 'lint'] and args.target == "run":
         # run_args['target'] = 'script' #dont modify this as script might have
         # target as in input
@@ -494,7 +507,7 @@ def main():
 
     | Target  | Actions                                                   |
     |---------|-----------------------------------------------------------|
-    | script  | run, find/search, rm, mv, cp, add, test, docker-run, show |
+    | script  | run, find/search, rm, mv, cp, add, test, docker-run, apptainer/apptainer-run, show |
     | cache   | find/search, rm, show, list, prune, mark-tmp              |
     | repo    | pull, search, rm, list, find/search                       |
 
@@ -547,7 +560,7 @@ def main():
         help_text = ""
         if pre_args.target == "run":
             if pre_args.action.startswith(
-                    "docker") or pre_args.action == "apptainer":
+                    "docker") or pre_args.action in ("apptainer", "apptainer-run"):
                 pre_args.target = "script"
             else:
                 logger.error(

{mlcflow-1.2.4 → mlcflow-1.2.6}/mlc/repo_action.py

@@ -2,6 +2,7 @@ from .action import Action
 import os
 import subprocess
 import re
+import shlex
 import yaml
 import json
 import shutil
@@ -322,8 +323,21 @@ class RepoAction(Action):
             return {"return": 0, "value": os.path.basename(
                 url).replace(".git", "")}
 
+    def _is_shallow_repo(self, repo_path):
+        """Return True if the git repository at *repo_path* is a shallow clone."""
+        try:
+            result = subprocess.run(
+                ['git', '-C', repo_path, 'rev-parse', '--is-shallow-repository'],
+                capture_output=True,
+                text=True,
+            )
+            return result.returncode == 0 and result.stdout.strip() == 'true'
+        except (subprocess.SubprocessError, FileNotFoundError, OSError):
+            return False
+
     def pull_repo(self, repo_url, branch=None, checkout=None, tag=None,
-                  pat=None, ssh=None, ignore_on_conflict=False, repo_path=None, force=False):
+                  pat=None, ssh=None, ignore_on_conflict=False, repo_path=None, force=False,
+                  shallow=False, depth=None, extra_git_args=None):
 
         # Determine the checkout path from environment or default
         repo_base_path = self.repos_path  # either the value will be from 'MLC_REPOS'
@@ -358,20 +372,41 @@ class RepoAction(Action):
                 repo_path = os.path.join(repo_base_path, repo_download_name)
 
         try:
+            # Compute depth argument: --shallow implies depth=1; explicit
+            # --depth=N takes precedence
+            clone_depth = None
+            if depth is not None:
+                try:
+                    clone_depth = int(depth)
+                except (TypeError, ValueError):
+                    return {
+                        "return": 1, "error": f"Invalid value for --depth: {depth!r}. Must be a positive integer."}
+                if clone_depth < 1:
+                    return {
+                        "return": 1, "error": f"Invalid value for --depth: {clone_depth}. Must be a positive integer."}
+            elif shallow:
+                clone_depth = 1
+
+            # Parse extra_git_args into a list
+            extra_args = []
+            if extra_git_args:
+                if isinstance(extra_git_args, list):
+                    extra_args = extra_git_args
+                else:
+                    extra_args = shlex.split(str(extra_git_args))
+
             # If the directory doesn't exist, clone it
             if not os.path.exists(repo_path):
                 logger.info(f"Cloning repository {repo_url} to {repo_path}...")
 
-                # Build clone command without branch if not provided
-                clone_command = ['git', 'clone', repo_url, repo_path]
+                # Build clone command
+                clone_command = ['git', 'clone']
                 if branch:
-                    clone_command = [
-                        'git',
-                        'clone',
-                        '--branch',
-                        branch,
-                        repo_url,
-                        repo_path]
+                    clone_command += ['--branch', branch]
+                if clone_depth is not None:
+                    clone_command += ['--depth', str(clone_depth)]
+                clone_command += extra_args
+                clone_command += [repo_url, repo_path]
 
                 subprocess.run(clone_command, check=True)
 
@@ -433,8 +468,17 @@ class RepoAction(Action):
                     logger.info(
                         "Pulling latest changes...")
                     try:
+                        pull_command = ['git', '-C', repo_path, 'pull']
+                        if clone_depth is not None:
+                            if self._is_shallow_repo(repo_path):
+                                pull_command += ['--depth', str(clone_depth)]
+                            else:
+                                logger.warning(
+                                    f"--depth/--shallow ignored for pull on non-shallow repo {repo_path}. "
+                                    "Re-clone with --shallow to create a shallow copy."
+                                )
                         subprocess.run(
-                            ['git', '-C', repo_path, 'pull'],
+                            pull_command,
                             capture_output=True,
                             text=True,
                             check=True)
@@ -492,8 +536,16 @@ class RepoAction(Action):
                 else:
                     logger.info(
                         "No local changes detected. Pulling latest changes...")
-                    subprocess.run(
-                        ['git', '-C', repo_path, 'pull'], check=True)
+                    pull_command = ['git', '-C', repo_path, 'pull']
+                    if clone_depth is not None:
+                        if self._is_shallow_repo(repo_path):
+                            pull_command += ['--depth', str(clone_depth)]
+                        else:
+                            logger.warning(
+                                f"--depth/--shallow ignored for pull on non-shallow repo {repo_path}. "
+                                "Re-clone with --shallow to create a shallow copy."
+                            )
+                    subprocess.run(pull_command, check=True)
                     logger.info("Repository successfully pulled.")
 
             if tag:
@@ -562,6 +614,9 @@ class RepoAction(Action):
     - `--tag <release_tag>`: Checks out a particular release tag.
     - `--pat <access_token>` or `--ssh`: Clones a private repository using a personal access token or SSH.
     - `--force`: For existing repositories with local tracked changes, stashes changes before pull and reapplies them after pull.
+    - `--shallow`: Perform a shallow clone with `--depth=1` (fastest for a fresh copy without history). For existing repos, only applied if the repo is already shallow; otherwise ignored with a warning.
+    - `--depth=N`: Perform a shallow clone/pull with the specified history depth (e.g. `--depth=5`). For existing repos, `--depth` is only applied when the repository is already a shallow clone; passing `--depth` to a full-history clone would corrupt it and is therefore ignored with a warning.
+    - `--extra_git_args=<args>`: Pass additional arguments to the `git clone` command (e.g. `--extra_git_args="--filter=blob:none"`). Only applies when cloning a new repository; not used for pull on existing repos. Accepts only trusted input — arguments are passed directly to git without further validation.
 
     Example Output:
 
@@ -592,7 +647,11 @@ class RepoAction(Action):
                         repo_object.path, os.W_OK):
                     repo_folder_name = os.path.basename(repo_object.path)
                     res = self.pull_repo(
-                        repo_folder_name, repo_path=repo_object.path, force=run_args.get('force'))
+                        repo_folder_name, repo_path=repo_object.path, force=run_args.get(
+                            'force'),
+                        shallow=run_args.get('shallow', False),
+                        depth=run_args.get('depth'),
+                        extra_git_args=run_args.get('extra_git_args'))
                     if res['return'] > 0:
                         return res
         else:
@@ -604,6 +663,9 @@ class RepoAction(Action):
             ssh = run_args.get('ssh')
             force = run_args.get('force')
             ignore_on_conflict = run_args.get('ignore_on_conflict')
+            shallow = run_args.get('shallow', False)
+            depth = run_args.get('depth')
+            extra_git_args = run_args.get('extra_git_args')
 
             if sum(bool(var) for var in [branch, checkout, tag]) > 1:
                 return {
@@ -617,7 +679,10 @@ class RepoAction(Action):
                 pat,
                 ssh,
                 ignore_on_conflict=ignore_on_conflict,
-                force=force)
+                force=force,
+                shallow=shallow,
+                depth=depth,
+                extra_git_args=extra_git_args)
             if res['return'] > 0:
                 return res
 

{mlcflow-1.2.4 → mlcflow-1.2.6}/mlc/script_action.py

@@ -7,6 +7,7 @@ import json
 import inspect
 from .index import Index
 from . import utils
+from .error_codes import get_error_guidance
 from .logger import logger
 
 
@@ -25,8 +26,9 @@ class ScriptAction(Action):
     6.  Copy(cp)
     7.  Run
     8.  Docker
-    9.  Test
-    10. Experiment
+    9.  Apptainer
+    10. Test
+    11. Experiment
 
     Scripts in MLCFlow can be identified using different methods:
 
@@ -284,6 +286,9 @@ Main Script Meta:""")
                 elif function_name == "docker":
                     result = automation_instance.docker(
                         run_args)  # Pass args to the run method
+                elif function_name == "apptainer":
+                    result = automation_instance.apptainer(
+                        run_args)  # Pass args to the apptainer method
                 elif function_name == "test":
                     result = automation_instance.test(
                         run_args)  # Pass args to the run method
@@ -319,6 +324,8 @@ Main Script Meta:""")
 
             if result['return'] > 0:
                 error = result.get('error', "")
+                error_guidance = get_error_guidance(
+                    result.get('error_code', result.get('return')), error)
                 _name_match = re.search(r'name\s*=\s*([^,)]+)', error)
                 _script_name = _name_match.group(1).strip() if _name_match else run_args.get(
                     'tags', run_args.get('details'))
@@ -338,7 +345,10 @@ Main Script Meta:""")
                 raise ScriptExecutionError(
                     f"Script {function_name} execution failed in {module_path}. \nError : {error}",
                     script_name=_script_name, repo_alias=_repo_alias, module_path=module_path,
-                    run_args=run_args, version_info_file=_version_info_file)
+                    run_args=run_args, version_info_file=_version_info_file,
+                    error_code=error_guidance.get(
+                        'error_code') if error_guidance else None,
+                    error_guidance=error_guidance)
 
             if str(run_args.get("mlc_output")).lower() in [
                     "on", "true", "yes", "1"]:
@@ -408,6 +418,33 @@ Main Script Meta:""")
 
     docker.__doc__ = docker_run.__doc__
 
+    def apptainer(self, run_args):
+        return self.apptainer_run(run_args)
+
+    def apptainer_run(self, run_args):
+        """
+    ####################################################################################################################
+    Target: Script
+    Action: Apptainer
+    ####################################################################################################################
+
+    The `apptainer` action runs scripts inside an Apptainer containerized environment.
+
+    An MLCFlow script can be executed inside Apptainer using either of the following syntaxes:
+
+    1. Apptainer Run: mlc apptainer run --tags=<script tags> <run flags>
+    2. Apptainer Script: mlc apptainer script --tags=<script tags> <run flags>
+
+    Example Command:
+
+    mlc apptainer script --tags=detect,os -j
+    mlca detect,os -j
+
+        """
+        return self.call_script_module_function("apptainer", run_args)
+
+    apptainer.__doc__ = apptainer_run.__doc__
+
     def remote_run(self, run_args):
         """
     ####################################################################################################################
@@ -680,10 +717,13 @@ Main Script Meta:""")
 
 class ScriptExecutionError(Exception):
     def __init__(self, message, script_name=None, repo_alias=None,
-                 module_path=None, run_args=None, version_info_file=None):
+                 module_path=None, run_args=None, version_info_file=None,
+                 error_code=None, error_guidance=None):
         super().__init__(message)
         self.script_name = script_name
         self.repo_alias = repo_alias
         self.module_path = module_path
         self.run_args = run_args or {}
         self.version_info_file = version_info_file
+        self.error_code = error_code
+        self.error_guidance = error_guidance

{mlcflow-1.2.4 → mlcflow-1.2.6}/mlcflow.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: mlcflow
-Version: 1.2.4
+Version: 1.2.6
 Summary: An automation interface tailored for CPU/GPU benchmarking
 Author-email: MLCommons <systems@mlcommons.org>
 License: 

{mlcflow-1.2.4 → mlcflow-1.2.6}/mlcflow.egg-info/SOURCES.txt

@@ -24,4 +24,7 @@ mlcflow.egg-info/dependency_links.txt
 mlcflow.egg-info/entry_points.txt
 mlcflow.egg-info/requires.txt
 mlcflow.egg-info/top_level.txt
-tests/test_cache_mark_tmp.py
+tests/test_action_invalid_meta_entries.py
+tests/test_cache_mark_tmp.py
+tests/test_mlcflow_unix_installer.py
+tests/test_script_action_apptainer.py

{mlcflow-1.2.4 → mlcflow-1.2.6}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "mlcflow"
-version = "1.2.4"
+version = "1.2.6"
 
 description = "An automation interface tailored for CPU/GPU benchmarking"
 authors = [

mlcflow-1.2.6/tests/test_action_invalid_meta_entries.py

@@ -0,0 +1,165 @@
+import json
+import os
+import tempfile
+import unittest
+
+import mlc.action as _mlc_action
+from mlc.action import Action
+from mlc.item import Item
+
+
+class ActionInvalidMetaSearchTest(unittest.TestCase):
+
+    def setUp(self):
+        self.temp_dir = tempfile.TemporaryDirectory()
+        self.addCleanup(self.temp_dir.cleanup)
+
+        self.previous_cwd = os.getcwd()
+        self.addCleanup(os.chdir, self.previous_cwd)
+        os.chdir(self.temp_dir.name)
+
+        self.previous_mlc_repos = os.environ.get("MLC_REPOS")
+        self.addCleanup(self._restore_env)
+        os.environ["MLC_REPOS"] = os.path.join(self.temp_dir.name, "repos")
+
+    def _restore_env(self):
+        if self.previous_mlc_repos is None:
+            os.environ.pop("MLC_REPOS", None)
+        else:
+            os.environ["MLC_REPOS"] = self.previous_mlc_repos
+
+    def _new_action(self):
+        a = Action()
+        a.parent = None
+        return a
+
+    def _seed_stale_index_entry(
+            self, action, folder_name, uid="fake-uid-000", tags=None):
+        """
+        Bypass the filesystem scanner by directly injecting a stale cache index
+        entry that points to a directory with no meta.json.  This replicates the
+        production scenario where the on-disk index JSON already contains the
+        entry from a previous run that crashed mid-download.
+        """
+        stale_dir = os.path.join(
+            self.temp_dir.name, "repos", "local", "cache", folder_name
+        )
+        os.makedirs(stale_dir, exist_ok=True)
+        # Leave only the incomplete-download marker — no meta.json.
+        with open(os.path.join(stale_dir, "mlc_temp_cache.json"), "w") as f:
+            json.dump({"status": "incomplete"}, f)
+
+        entry = {
+            "uid": uid,
+            "tags": tags or [],
+            "alias": folder_name,
+            "path": stale_dir,
+            "repo": "local",
+        }
+        action.get_index().indices["cache"] = [entry]
+        return stale_dir
+
+    def test_search_fetch_all_with_unknown_target_returns_empty_list(self):
+        action = self._new_action()
+
+        res = action.search({"target_name": "unknown", "fetch_all": True})
+
+        self.assertEqual(res["return"], 0)
+        self.assertEqual(res["list"], [])
+
+    def test_search_fetch_all_skips_item_with_invalid_meta(self):
+        action = self._new_action()
+        add_res = action.add({
+            "target_name": "cache",
+            "item": "bad-meta-cache",
+            "tags": "a,b",
+        })
+        self.assertEqual(add_res["return"], 0)
+
+        # Corrupt meta.json so it is not a dict.
+        with open(os.path.join(add_res["path"], "meta.json"), "w") as f:
+            json.dump([], f)
+
+        res = action.search({"target_name": "cache", "fetch_all": True})
+
+        self.assertEqual(res["return"], 0)
+        self.assertEqual(len(res["list"]), 0)
+
+    def test_search_alias_lookup_skips_item_with_invalid_meta(self):
+        action = self._new_action()
+        add_res = action.add({
+            "target_name": "cache",
+            "item": "bad-meta-alias",
+            "tags": "x,y",
+        })
+        self.assertEqual(add_res["return"], 0)
+
+        # Corrupt meta.json into a non-dict so it fails verification lookup
+        with open(os.path.join(add_res["path"], "meta.json"), "w") as f:
+            json.dump([], f)
+
+        res = action.search(
+            {"target_name": "cache", "details": "bad-meta-alias"})
+
+        self.assertEqual(res["return"], 0)
+        self.assertEqual(len(res["list"]), 0)
+
+    def test_search_alias_lookup_skips_corrupt_index_entry_without_meta(self):
+        """
+        Index entry points to a path that has no meta file at all.
+        Injected directly to bypass the filesystem scanner.
+        """
+        action = self._new_action()
+        self._seed_stale_index_entry(
+            action, "bad-whisper-cache", uid="not-a-real-uid", tags=["x", "y"]
+        )
+
+        res = action.search(
+            {"target_name": "cache", "details": "bad-whisper-cache"})
+
+        self.assertEqual(res["return"], 0)
+        self.assertEqual(len(res["list"]), 0)
+
+    def test_search_meta_validation_prevents_corrupt_items_in_alias_path(self):
+        """
+        Regression test for the Whisper inference stale-folder bug.
+        Regression test for the Whisper dataset stale-folder bug.
+        Simulates a crashed/incomplete download where the index entry persists but meta.json is missing,
+        ensuring the search guard safely skips it.
+        """
+        action = self._new_action()
+
+        self._seed_stale_index_entry(
+            action, "whisper-dataset", uid="fake-whisper-uid-123", tags=["x", "y"]
+        )
+
+        res = action.search(
+            {"target_name": "cache", "details": "whisper-dataset"})
+
+        self.assertEqual(res["return"], 0)
+        self.assertEqual(
+            len(res["list"]), 0,
+            msg="search() must skip cache items whose meta.json is absent or invalid.",
+        )
+
+    def test_search_tags_handles_missing_tags_key_in_index(self):
+        action = self._new_action()
+        add_res = action.add({
+            "target_name": "cache",
+            "item": "missing-tags-index",
+            "tags": "alpha,beta",
+        })
+        self.assertEqual(add_res["return"], 0)
+
+        cache_index = action.get_index().indices["cache"]
+        self.assertEqual(len(cache_index), 1)
+        cache_index[0].pop("tags", None)
+
+        res = action.search({"target_name": "cache", "tags": "alpha"})
+
+        self.assertEqual(res["return"], 0)
+        self.assertEqual(len(res["list"]), 0)
+
+
+if __name__ == "__main__":
+    unittest.main()

mlcflow-1.2.6/tests/test_mlcflow_unix_installer.py

@@ -0,0 +1,83 @@
+import subprocess
+import platform
+import sys
+from pathlib import Path
+
+
+REPO_ROOT = Path(__file__).resolve().parents[1]
+INSTALLER_SCRIPT = REPO_ROOT / "docs" / "install" / "mlcflow_unix_installer.sh"
+
+
+def _resolve_venv_dir(tmp_path, setup_snippet):
+    default_dir = tmp_path / "mlcflow"
+    marker = "__RESULT__"
+    command = f"""
+set -euo pipefail
+source "{INSTALLER_SCRIPT}"
+DEFAULT_VENV_DIR="{default_dir}"
+VENV_DIR="$DEFAULT_VENV_DIR"
+PY_MAJOR_MINOR="$(python3 -c 'import sys; print("{{}}.{{}}".format(*sys.version_info[:2]))')"
+PY_ARCH="$(python3 -c 'import platform; print(platform.machine())')"
+{setup_snippet}
+resolve_default_venv_dir
+echo "{marker}$VENV_DIR"
+"""
+    result = subprocess.run(
+        ["bash", "-lc", command],
+        text=True,
+        capture_output=True,
+        check=True,
+    )
+
+    for line in reversed(result.stdout.splitlines()):
+        if line.startswith(marker):
+            return line[len(marker):]
+
+    raise AssertionError(
+        f"Could not parse resolved venv path from output:\n{result.stdout}")
+
+
+def test_resolve_default_venv_dir_prefers_compatible_default(tmp_path):
+    setup_snippet = """
+python3 -m venv "$DEFAULT_VENV_DIR"
+"""
+    resolved = _resolve_venv_dir(tmp_path, setup_snippet)
+    assert resolved == str(tmp_path / "mlcflow")
+
+
+def test_resolve_default_venv_dir_uses_suffix_for_incompatible_default(
+        tmp_path):
+    setup_snippet = """
+mkdir -p "$DEFAULT_VENV_DIR"
+"""
+    resolved = _resolve_venv_dir(tmp_path, setup_snippet)
+    assert resolved.startswith(str(tmp_path / "mlcflow_"))
+    assert "_py" in resolved
+
+
+def test_resolve_default_venv_dir_removes_stale_shared_env_when_default_incompatible(
+        tmp_path):
+    """When the default venv is incompatible and the suffixed venv already exists
+    but is itself stale/broken, the stale suffixed dir must be removed so that
+    setup_venv can create a fresh one rather than silently reusing a broken env."""
+    setup_snippet = """
+mkdir -p "$DEFAULT_VENV_DIR"
+SHARED_VENV_DIR="${DEFAULT_VENV_DIR}_${PY_ARCH}_py${PY_MAJOR_MINOR}"
+mkdir -p "$SHARED_VENV_DIR"
+"""
+    resolved = _resolve_venv_dir(tmp_path, setup_snippet)
+    expected_suffix = f"{tmp_path / 'mlcflow'}_{platform.machine()}_py{sys.version_info[0]}.{sys.version_info[1]}"
+    assert resolved == expected_suffix
+    # The stale shared dir should have been removed so setup_venv creates it
+    # fresh
+    assert not Path(expected_suffix).exists()
+
+
+def test_resolve_default_venv_dir_reuses_compatible_suffixed_env(tmp_path):
+    setup_snippet = """
+SHARED_VENV_DIR="${DEFAULT_VENV_DIR}_${PY_ARCH}_py${PY_MAJOR_MINOR}"
+python3 -m venv "$SHARED_VENV_DIR"
+"""
+    resolved = _resolve_venv_dir(tmp_path, setup_snippet)
+    expected = f"{tmp_path / 'mlcflow'}_{platform.machine()}_py{sys.version_info[0]}.{sys.version_info[1]}"
+    assert resolved == expected

mlcflow-1.2.6/tests/test_script_action_apptainer.py

@@ -0,0 +1,29 @@
+import unittest
+from unittest.mock import patch
+
+from mlc.script_action import ScriptAction
+
+
+class _Parent:
+    pass
+
+
+class ScriptActionApptainerTest(unittest.TestCase):
+    def test_apptainer_delegates_to_script_module(self):
+        action = ScriptAction(_Parent())
+        run_args = {"tags": "detect,os"}
+        expected = {"return": 0}
+
+        with patch.object(
+                ScriptAction,
+                "call_script_module_function",
+                return_value=expected) as call_script_module_function:
+            result = action.apptainer(run_args)
+
+        self.assertEqual(result, expected)
+        call_script_module_function.assert_called_once_with(
+            "apptainer", run_args)
+
+
+if __name__ == "__main__":
+    unittest.main()

mlcflow-1.2.4/mlc/error_codes.py

@@ -1,77 +0,0 @@
-from enum import Enum, auto
-
-class ErrorCode(Enum):
-    """Enum class for error codes in MLCFlow"""
-    # General errors (2000-2007)
-    AUTOMATION_SCRIPT_NOT_FOUND = (2000, "The specified automation script was not found")
-    PATH_DOES_NOT_EXIST = (2001, "Provided path does not exists")
-    FILE_NOT_FOUND = (2002, "Required file was not found")
-    PERMISSION_DENIED = (2003, "Insufficient permission to execute the script")
-    IO_Error = (2004, "File I/O operation failed")
-    AUTOMATION_CUSTOM_ERROR = (2005, "Custom error triggered by the script")
-    UNSUPPORTED_OS = (2006, "The Operating System is not supported by the script")
-    MISSING_ENV_VARIABLE = (2007, "Required environment variables are missing")
-    
-    def __init__(self, code, description):
-        self.code = code
-        self.description = description
-
-class WarningCode(Enum):
-    """Enum class for warning codes in MLCFlow"""
-    # General warnings (1000-1007)
-    IO_WARNING = (1000, "File I/O operation warning")
-    AUTOMATION_SCRIPT_NOT_TESTED = (1001, "the script is not tested on the current operatinig system or is in a development state")
-    AUTOMATION_SCRIPT_SKIPPED = (1002, "The script has been skipped during execution")
-    AUTOMATION_CUSTOM_ERROR = (1003, "Custom warning triggered by the script")
-    NON_INTERACTIVE_ENV = (1004, "Non interactive environment detected")
-    ELEVATED_PERMISSION_NEEDED = (1005, "Elevated permission needed")
-    EMPTY_TARGET = (1006, "The specified target is empty")
-    
-    def __init__(self, code, description):
-        self.code = code
-        self.description = description
-
-def get_error_info(error_code):
-    """Get the error message for a given error code"""
-    try:
-        return {"error_code": ErrorCode(error_code).code, "error_message": ErrorCode(error_code).description}
-    except ValueError:
-        return f"Unknown error code: {error_code}"
-
-def get_warning_info(warning_code):
-    """Get the warning message for a given warning code"""
-    try:
-        return {"warning_code": WarningCode(warning_code).code, "warning_message": WarningCode(warning_code).description}
-    except ValueError:
-        return f"Unknown warning code: {warning_code}"
-
-def is_warning_code(code):
-    """Check if a given code is a warning code"""
-    try:
-        # Check if code is in warning range (2000-2399)
-        if 2000 <= code <= 2399:
-            WarningCode(code)
-            return True
-        return False
-    except ValueError:
-        return False
-
-def is_error_code(code):
-    """Check if a given code is an error code"""
-    try:
-        # Check if code is in error range (1000-1399)
-        if 1000 <= code <= 1399:
-            ErrorCode(code)
-            return True
-        return False
-    except ValueError:
-        return False
-
-def get_code_type(code):
-    """Get the type of a code (error or warning)"""
-    if is_error_code(code):
-        return "error"
-    elif is_warning_code(code):
-        return "warning"
-    else:
-        return "unknown"