mlcflow 1.2.5__tar.gz → 1.2.7__tar.gz

{mlcflow-1.2.5 → mlcflow-1.2.7}/PKG-INFO

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

{mlcflow-1.2.5 → mlcflow-1.2.7}/mlc/main.py

@@ -576,7 +576,7 @@ def main():
             else:
                 pre_args.target, pre_args.action = pre_args.action, None
             actions = get_action(pre_args.target, default_parent)
-            help_text += actions.__doc__
+            help_text += actions.__doc__ or ""
             # iterate through every method
             for method_name, method in inspect.getmembers(
                     actions.__class__, inspect.isfunction):
@@ -588,7 +588,7 @@ def main():
             action_name = pre_args.action.replace("-", "_")
             try:
                 method = getattr(actions, action_name)
-                help_text += actions.__doc__
+                help_text += actions.__doc__ or ""
                 if method.__doc__:
                     help_text += method.__doc__
             except AttributeError:

{mlcflow-1.2.5 → mlcflow-1.2.7}/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
@@ -39,11 +40,152 @@ class RepoAction(Action):
 
     """
 
+    GIT_MISSING_BRANCH_PHRASE = "did not match any file(s) known to git"
+    GIT_FAST_FORWARD_FAILURE_PHRASE = "not possible to fast-forward"
+
     def __init__(self, parent=None):
         # super().__init__(parent)
         self.parent = parent
         self.__dict__.update(vars(parent))
 
+    def _build_pull_command(self, repo_path, branch=None, clone_depth=None,
+                            fast_forward_only=False):
+        pull_command = ['git', '-C', repo_path, 'pull']
+        if fast_forward_only:
+            pull_command.append('--ff-only')
+        if clone_depth is not None:
+            if self._is_shallow_repo(repo_path):
+                pull_command.extend(['--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."
+                )
+        # Preserve the historical existing-repo behavior of a plain
+        # `git pull` by default. The branch argument is only forwarded to
+        # `git pull` when the internal strict path explicitly opts into
+        # fast-forward-only updates.
+        if branch and fast_forward_only:
+            pull_command.extend(['origin', branch])
+        return pull_command
+
+    def _checkout_pull_branch(self, repo_path, branch):
+        """Ensure *branch* is checked out locally before a strict pull.
+
+        First tries to checkout an existing local branch. If that fails, fetches
+        the branch from origin and creates a new tracking branch. Raises
+        RuntimeError with contextual guidance when the branch cannot be prepared.
+
+        Args:
+            repo_path: Local repository path.
+            branch: Branch name to prepare before pulling.
+
+        Raises:
+            RuntimeError: If the branch cannot be fetched or checked out.
+        """
+        try:
+            subprocess.run(
+                ['git', '-C', repo_path, 'checkout', branch],
+                capture_output=True,
+                text=True,
+                check=True)
+        except subprocess.CalledProcessError as checkout_error:
+            checkout_error_text = self._subprocess_error_message(
+                checkout_error)
+            lowered_checkout_error = checkout_error_text.lower()
+            # Git uses the same exit code for many checkout failures, so we
+            # only fall back to fetch+track when stderr includes both
+            # "pathspec" and Git's usual missing-ref phrase
+            # "did not match any file(s) known to git".
+            missing_local_branch = (
+                "pathspec" in lowered_checkout_error
+                and self.GIT_MISSING_BRANCH_PHRASE in lowered_checkout_error
+            )
+            if not missing_local_branch:
+                raise RuntimeError(
+                    f"Cannot switch to branch '{branch}' in {repo_path}: "
+                    f"{checkout_error_text}"
+                ) from checkout_error
+            try:
+                subprocess.run(
+                    ['git', '-C', repo_path, 'fetch', 'origin', branch],
+                    capture_output=True,
+                    text=True,
+                    check=True)
+            except subprocess.CalledProcessError as fetch_error:
+                raise RuntimeError(
+                    f"Failed to fetch branch '{branch}' in {repo_path}: "
+                    f"{self._subprocess_error_message(fetch_error)}. "
+                    "Ensure the branch exists on origin and that the repository is reachable."
+                ) from fetch_error
+
+            try:
+                subprocess.run(
+                    ['git', '-C', repo_path, 'checkout', '-b',
+                        branch, '--track', f'origin/{branch}'],
+                    capture_output=True,
+                    text=True,
+                    check=True)
+            except subprocess.CalledProcessError as tracking_error:
+                raise RuntimeError(
+                    f"Initial checkout of '{branch}' failed in {repo_path}. "
+                    "After fetching from origin, creating a tracking branch also failed. "
+                    f"Initial error: {checkout_error_text}. "
+                    f"Tracking branch error: {self._subprocess_error_message(tracking_error)}. "
+                    "Check that the branch name is correct and that your local checkout can track origin."
+                ) from tracking_error
+
+    @staticmethod
+    def _format_stash_restore_guidance(repo_path):
+        return (
+            f"Local changes remain in stash. Please run `git -C {repo_path} stash apply` "
+            "after resolving pull issues."
+        )
+
+    def _format_pull_error(self, repo_path, error_message, stash_created=False,
+                           force=False, failure_phase="git pull"):
+        """Format a pull failure message.
+
+        Args:
+            repo_path: Repository path being updated.
+            error_message: Original stderr/stdout-derived git failure text.
+            stash_created: Whether local changes were stashed for a force pull.
+            force: Whether the failure happened on a force-pull path.
+            failure_phase: Phase label such as ``git pull`` or
+                ``branch checkout``.
+
+        Returns:
+            A user-facing error string with optional recovery guidance.
+        """
+        prefix = "Force pull failed" if force else "Pull failed"
+        if failure_phase:
+            prefix = f"{prefix} during {failure_phase}"
+
+        resolution = ""
+        lowered_error = error_message.lower()
+        # Git reports ff-only failures via stderr text instead of a distinct
+        # exit code, so use this case-insensitive substring from the standard
+        # "Not possible to fast-forward, aborting." message to add guidance.
+        if self.GIT_FAST_FORWARD_FAILURE_PHRASE in lowered_error:
+            resolution = (
+                " Check whether the local and remote branches have diverged "
+                "and reconcile them manually before retrying."
+            )
+
+        if stash_created:
+            return (
+                f"{prefix} for {repo_path}. "
+                f"{self._format_stash_restore_guidance(repo_path)} "
+                f"Details: {error_message}{resolution}"
+            )
+
+        return f"{prefix} for {repo_path}: {error_message}{resolution}"
+
+    @staticmethod
+    def _subprocess_error_message(error):
+        """Return the most helpful message from a subprocess-related error."""
+        return (error.stderr or error.stdout or str(error)).strip()
+
     def add(self, run_args):
         """
     ####################################################################################################################
@@ -322,8 +464,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, fast_forward_only=False):
 
         # Determine the checkout path from environment or default
         repo_base_path = self.repos_path  # either the value will be from 'MLC_REPOS'
@@ -358,20 +513,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,21 +609,33 @@ class RepoAction(Action):
                     logger.info(
                         "Pulling latest changes...")
                     try:
+                        if fast_forward_only and branch:
+                            self._checkout_pull_branch(repo_path, branch)
                         subprocess.run(
-                            ['git', '-C', repo_path, 'pull'],
+                            self._build_pull_command(
+                                repo_path, branch, clone_depth, fast_forward_only),
                             capture_output=True,
                             text=True,
                             check=True)
+                    except RuntimeError as e:
+                        return {
+                            "return": 1,
+                            "error": self._format_pull_error(
+                                repo_path,
+                                str(e),
+                                stash_created=stash_created,
+                                force=True,
+                                failure_phase="branch checkout")
+                        }
                     except subprocess.CalledProcessError as e:
-                        pull_error = (e.stderr or e.stdout or str(e)).strip()
-                        if stash_created:
-                            return {
-                                "return": 1,
-                                "error": f"Force pull failed during git pull for {repo_path}. Local changes remain in stash. Please run `git -C {repo_path} stash apply` after resolving pull issues. Details: {pull_error}"
-                            }
+                        pull_error = self._subprocess_error_message(e)
                         return {
                             "return": 1,
-                            "error": f"Force pull failed during git pull for {repo_path}: {pull_error}"
+                            "error": self._format_pull_error(
+                                repo_path,
+                                pull_error,
+                                stash_created=stash_created,
+                                force=True)
                         }
                     logger.info("Repository successfully pulled.")
 
@@ -492,8 +680,28 @@ class RepoAction(Action):
                 else:
                     logger.info(
                         "No local changes detected. Pulling latest changes...")
-                    subprocess.run(
-                        ['git', '-C', repo_path, 'pull'], check=True)
+                    try:
+                        if fast_forward_only and branch:
+                            self._checkout_pull_branch(repo_path, branch)
+                        subprocess.run(
+                            self._build_pull_command(
+                                repo_path, branch, clone_depth, fast_forward_only),
+                            capture_output=True,
+                            text=True,
+                            check=True)
+                    except RuntimeError as e:
+                        return {
+                            "return": 1,
+                            "error": self._format_pull_error(
+                                repo_path, str(e), failure_phase="branch checkout")
+                        }
+                    except subprocess.CalledProcessError as e:
+                        pull_error = self._subprocess_error_message(e)
+                        return {
+                            "return": 1,
+                            "error": self._format_pull_error(
+                                repo_path, pull_error)
+                        }
                     logger.info("Repository successfully pulled.")
 
             if tag:
@@ -533,6 +741,8 @@ class RepoAction(Action):
 
             return {"return": 0}
 
+        except RuntimeError as e:
+            return {'return': 1, 'error': str(e)}
         except subprocess.CalledProcessError as e:
             return {'return': 1, 'error': f"Git command failed: {e}"}
         except Exception as e:
@@ -558,10 +768,13 @@ class RepoAction(Action):
 
 
     - `--checkout <commit_sha>`: Checks out a specific commit after cloning (applicable when the repository exists locally).
-    - `--branch <branch_name>`: Checks out a specific branch **while cloning** a new repository.
+    - `--branch <branch_name>`: Checks out a specific branch while cloning a new repository. When strict fast-forward-only pulls are requested for an existing checkout, it also selects the local branch to switch to before pulling `origin/<branch>`.
     - `--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 +805,12 @@ 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'),
+                        fast_forward_only=run_args.get('fast_forward_only', False))
                     if res['return'] > 0:
                         return res
         else:
@@ -604,6 +822,10 @@ 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')
+            fast_forward_only = run_args.get('fast_forward_only', False)
 
             if sum(bool(var) for var in [branch, checkout, tag]) > 1:
                 return {
@@ -617,7 +839,11 @@ 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,
+                fast_forward_only=fast_forward_only)
             if res['return'] > 0:
                 return res
 

{mlcflow-1.2.5 → mlcflow-1.2.7}/mlc/script_action.py

@@ -244,7 +244,8 @@ Main Script Meta:""")
                 "automation": "repo",
                 "action": "pull",
                 "repo": "mlcommons@mlperf-automations",
-                "branch": "dev"
+                "branch": "dev",
+                "fast_forward_only": True
             })
 
             if result['return'] == 0:

{mlcflow-1.2.5 → mlcflow-1.2.7}/mlcflow.egg-info/PKG-INFO

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

{mlcflow-1.2.5 → mlcflow-1.2.7}/mlcflow.egg-info/SOURCES.txt

@@ -26,4 +26,5 @@ mlcflow.egg-info/requires.txt
 mlcflow.egg-info/top_level.txt
 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.5 → mlcflow-1.2.7}/pyproject.toml

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

mlcflow-1.2.7/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.7/tests/test_script_action_apptainer.py

@@ -0,0 +1,54 @@
+import tempfile
+import unittest
+from unittest.mock import patch
+
+from mlc.script_action import ScriptAction
+
+
+class _Parent:
+    def __init__(self, repos_path=None):
+        self.repos_path = repos_path
+
+
+class ScriptActionApptainerTest(unittest.TestCase):
+    def test_apptainer_delegates_to_script_module(self):
+        action = ScriptAction(_Parent(tempfile.gettempdir()))
+        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)
+
+    def test_auto_pull_uses_fast_forward_only_for_mlperf_automations(self):
+        with tempfile.TemporaryDirectory() as repos_path:
+            action = ScriptAction(_Parent(repos_path))
+
+            with patch.object(
+                    ScriptAction,
+                    "find_target_folder",
+                    return_value=None), \
+                    patch.object(
+                        ScriptAction,
+                        "access",
+                        return_value={"return": 1, "error": "pull failed"}) as access:
+                result = action.call_script_module_function("run", {})
+
+            self.assertEqual(result["return"], 1)
+            access.assert_called_once_with({
+                "automation": "repo",
+                "action": "pull",
+                "repo": "mlcommons@mlperf-automations",
+                "branch": "dev",
+                "fast_forward_only": True
+            })
+
+
+if __name__ == "__main__":
+    unittest.main()

mlcflow-1.2.5/tests/test_script_action_apptainer.py

@@ -1,29 +0,0 @@
-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()