Skip to content

Local UI to run and train LLMs and diffusion models. Supports GGUF, MLX, Qwen3.8, DeepSeek-V4.1, MiniMax-H3, Gemma 4, FLUX and more.

Studio: scope the GGUF converter pin to the conversion (#11417)

Daniel Hanf341e8243bcc
diff --git a/studio/backend/core/export/export.py b/studio/backend/core/export/export.py
index 977ccc61d22..107a8f84e8a 100644
--- a/studio/backend/core/export/export.py
+++ b/studio/backend/core/export/export.py
@@ -82,6 +82,80 @@ _PYTORCH_MISSING_MESSAGE = (
_LLAMA_CPP_SCRIPTS_WARNING_EMITTED = False
+def _llama_cpp_scripts_pin():
+ """Pin convert_hf_to_gguf.py to setup.sh's llama.cpp ref for one conversion.
+
+ Scoped and marked internal because UNSLOTH_LLAMA_CPP_SCRIPTS_DIR is read as the
+ user's own choice: it outranks UNSLOTH_LLAMA_CPP_CONVERTER_TAG, and it exempts the
+ converter from the UNSLOTH_CONVERTER_SCAN_STRICT refusal. A pin the user set is left
+ exactly as it is; that one carries their exemption.
+ """
+ global _LLAMA_CPP_SCRIPTS_WARNING_EMITTED
+ if _IS_MLX:
+ # The MLX save path pins for itself, under a plain threading.Lock held across the
+ # conversion: entering it here too nests, and the second entry never returns.
+ yield
+ return
+ try:
+ from unsloth_zoo.llama_cpp import (
+ LLAMA_CPP_DEFAULT_DIR,
+ _resolve_local_convert_script, # noqa: F401
+ )
+ except Exception:
+ # Not just ImportError: a half-built unsloth_zoo raises RuntimeError or AttributeError.
+ if not _LLAMA_CPP_SCRIPTS_WARNING_EMITTED:
+ logger.warning(
+ "Unsloth: installed unsloth_zoo does not honor "
+ "UNSLOTH_LLAMA_CPP_SCRIPTS_DIR; convert_hf_to_gguf.py will "
+ "still be downloaded from llama.cpp master and may drift "
+ "past the pinned llama-quantize binary. Upgrade unsloth_zoo "
+ "to activate the local script pin."
+ )
+ _LLAMA_CPP_SCRIPTS_WARNING_EMITTED = True
+ yield
+ return
+
+ if os.environ.get("UNSLOTH_LLAMA_CPP_CONVERTER_TAG", "").strip():
+ # The pin outranks the tag, so pinning here is what made setting a tag do nothing.
+ yield
+ return
+
+ try:
+ from unsloth_zoo.llama_cpp import _converter_dir_is_incomplete
+ incomplete = _converter_dir_is_incomplete(LLAMA_CPP_DEFAULT_DIR)
+ except Exception:
+ # An older unsloth_zoo has no such check, and it only ever skips the pin.
+ incomplete = False
+ if incomplete:
+ # Pinning an entrypoint with no conversion/ beside it is what stops the staged
+ # resolver from fetching a co-versioned set that runs.
+ yield
+ return
+
+ try:
+ from unsloth_zoo.llama_cpp import internal_scripts_dir_pin
+ except ImportError:
+ internal_scripts_dir_pin = None
+
+ if internal_scripts_dir_pin is not None:
+ with internal_scripts_dir_pin(LLAMA_CPP_DEFAULT_DIR):
+ yield
+ return
+
+ # Older unsloth_zoo, no internal pin: scope the variable by hand so it cannot leak.
+ # Strict mode still takes the exemption there; upgrading unsloth_zoo is the fix.
+ existing = os.environ.get("UNSLOTH_LLAMA_CPP_SCRIPTS_DIR")
+ if existing is not None:
+ yield
+ return
+ os.environ["UNSLOTH_LLAMA_CPP_SCRIPTS_DIR"] = LLAMA_CPP_DEFAULT_DIR
+ try:
+ yield
+ finally:
+ os.environ.pop("UNSLOTH_LLAMA_CPP_SCRIPTS_DIR", None)
+
+
def _multi_gpu_device_map_kwargs() -> dict:
"""``device_map`` kwargs for sharding a checkpoint across every visible GPU.
@@ -1321,28 +1395,6 @@ class ExportBackend:
quant_methods = ["q4_k_m"]
quant_method = quant_methods if len(quant_methods) > 1 else quant_methods[0]
- # Pin convert_hf_to_gguf.py to setup.sh's llama.cpp ref so it cannot drift past the pinned llama-
- # quantize gguf API.
- global _LLAMA_CPP_SCRIPTS_WARNING_EMITTED
- try:
- from unsloth_zoo.llama_cpp import (
- LLAMA_CPP_DEFAULT_DIR,
- _resolve_local_convert_script, # noqa: F401
- )
- os.environ.setdefault("UNSLOTH_LLAMA_CPP_SCRIPTS_DIR", LLAMA_CPP_DEFAULT_DIR)
- except Exception:
- # Not just ImportError: a half-built unsloth_zoo raises RuntimeError or AttributeError, and this pin
- # is only an optimisation.
- if not _LLAMA_CPP_SCRIPTS_WARNING_EMITTED:
- logger.warning(
- "Unsloth: installed unsloth_zoo does not honor "
- "UNSLOTH_LLAMA_CPP_SCRIPTS_DIR; convert_hf_to_gguf.py will "
- "still be downloaded from llama.cpp master and may drift "
- "past the pinned llama-quantize binary. Upgrade unsloth_zoo "
- "to activate the local script pin."
- )
- _LLAMA_CPP_SCRIPTS_WARNING_EMITTED = True
-
if save_directory:
save_directory = str(resolve_export_write_dir(save_directory))
# Keep unsloth relative-path internals anchored to the repo cwd.
@@ -1361,14 +1413,17 @@ class ExportBackend:
# Resolve before anything can raise; the cleanup below needs it too.
imatrix_path = _materialized_imatrix_path(_model_tmp, imatrix_file)
try:
- result = self.current_model.save_pretrained_gguf(
- _model_tmp,
- self.current_tokenizer,
- quantization_method = quant_method,
- **imatrix_kw,
- **local_token_kw,
- **shard_kw,
- )
+ # Pinned to setup.sh's llama.cpp ref so the converter cannot drift past the pinned
+ # llama-quantize gguf API; scoped to the conversion.
+ with _llama_cpp_scripts_pin():
+ result = self.current_model.save_pretrained_gguf(
+ _model_tmp,
+ self.current_tokenizer,
+ quantization_method = quant_method,
+ **imatrix_kw,
+ **local_token_kw,
+ **shard_kw,
+ )
# Scan only the owned root; exact reported paths cover external outputs.
reported = result if isinstance(result, dict) else {}
@@ -1545,15 +1600,17 @@ class ExportBackend:
except Exception as exception:
logger.warning(f"Could not publish the model card: {exception}")
else:
- self.current_model.push_to_hub_gguf(
- repo_id,
- self.current_tokenizer,
- quantization_method = quant_method,
- token = hf_token,
- private = private,
- **imatrix_kw,
- **shard_kw,
- )
+ # Converts as well as pushes, so it needs the same scoped pin.
+ with _llama_cpp_scripts_pin():
+ self.current_model.push_to_hub_gguf(
+ repo_id,
+ self.current_tokenizer,
+ quantization_method = quant_method,
+ token = hf_token,
+ private = private,
+ **imatrix_kw,
+ **shard_kw,
+ )
logger.info(f"GGUF model pushed successfully to {repo_id}")
return (
diff --git a/studio/backend/tests/test_export_converter_pin.py b/studio/backend/tests/test_export_converter_pin.py
new file mode 100644
index 00000000000..6b3e2ea8cfd
--- /dev/null
+++ b/studio/backend/tests/test_export_converter_pin.py
@@ -0,0 +1,249 @@
+# SPDX-License-Identifier: AGPL-3.0-only
+# Copyright 2026-present the Unsloth AI Inc. team. All rights reserved. See /studio/LICENSE.AGPL-3.0
+
+"""The GGUF converter pin is Unsloth's own routing, so it is scoped to one conversion.
+
+Setting UNSLOTH_LLAMA_CPP_SCRIPTS_DIR and leaving it there cost two controls that live
+in unsloth_zoo: the variable outranks UNSLOTH_LLAMA_CPP_CONVERTER_TAG, so the escape
+hatch the unsupported-architecture message names did nothing for a Studio export, and
+trust is read off the variable, so a converter Studio had just downloaded looked
+user-pinned and UNSLOTH_CONVERTER_SCAN_STRICT stopped failing exports."""
+
+from __future__ import annotations
+
+import contextlib
+import os
+import sys
+import threading
+from pathlib import Path
+
+_BACKEND_DIR = Path(__file__).resolve().parent.parent
+if str(_BACKEND_DIR) not in sys.path:
+ sys.path.insert(0, str(_BACKEND_DIR))
+_TESTS_DIR = Path(__file__).resolve().parent
+if str(_TESTS_DIR) not in sys.path:
+ sys.path.insert(0, str(_TESTS_DIR))
+
+# Reuse the absolute-paths stub harness: loads core/export/export.py without torch/unsloth.
+from test_export_absolute_paths import ( # noqa: E402
+ _install_export_backend_stubs,
+ _load_module,
+)
+
+_SCRIPTS_DIR = "UNSLOTH_LLAMA_CPP_SCRIPTS_DIR"
+_CONVERTER_TAG = "UNSLOTH_LLAMA_CPP_CONVERTER_TAG"
+
+
+def _export_mod(monkeypatch, *, mlx = False):
+ _install_export_backend_stubs(monkeypatch)
+ monkeypatch.delenv(_SCRIPTS_DIR, raising = False)
+ monkeypatch.delenv(_CONVERTER_TAG, raising = False)
+ mod = _load_module(
+ "test_core_export_backend_converter_pin", "core/export/export.py", monkeypatch
+ )
+ # The stub unsloth is MLX, so say which host each case is about: Studio pins on a
+ # GPU host, and leaves the pinning to unsloth_zoo's MLX save path on a Mac.
+ monkeypatch.setattr(mod, "_IS_MLX", mlx)
+ return mod
+
+
+def _zoo(
+ monkeypatch,
+ *,
+ internal_pin = True,
+ incomplete = False,
+):
+ """The installed unsloth_zoo, with the pieces the pin looks for."""
+ llama_cpp = sys.modules["unsloth_zoo.llama_cpp"]
+ calls = {"internal": [], "incomplete": []}
+
+ # Not reentrant, exactly like the real one: it holds a plain threading.Lock for the
+ # whole conversion, so a second entry on the same thread hangs rather than raising.
+ # Raising here turns that hang into a test failure.
+ held = threading.Lock()
+
+ @contextlib.contextmanager
+ def _internal_scripts_dir_pin(folder):
+ if not held.acquire(blocking = False):
+ raise RuntimeError("internal_scripts_dir_pin re-entered: the real one deadlocks here")
+ calls["internal"].append(folder)
+ existing = os.environ.get(_SCRIPTS_DIR)
+ if existing is None:
+ os.environ[_SCRIPTS_DIR] = folder
+ try:
+ yield
+ finally:
+ if existing is None:
+ os.environ.pop(_SCRIPTS_DIR, None)
+ else:
+ os.environ[_SCRIPTS_DIR] = existing
+ held.release()
+
+ if internal_pin:
+ monkeypatch.setattr(
+ llama_cpp, "internal_scripts_dir_pin", _internal_scripts_dir_pin, raising = False
+ )
+ else:
+ monkeypatch.delattr(llama_cpp, "internal_scripts_dir_pin", raising = False)
+
+ def _converter_dir_is_incomplete(folder):
+ calls["incomplete"].append(folder)
+ return incomplete
+
+ monkeypatch.setattr(
+ llama_cpp, "_converter_dir_is_incomplete", _converter_dir_is_incomplete, raising = False
+ )
+ return llama_cpp, calls
+
+
+def test_pin_is_scoped_to_the_conversion(monkeypatch):
+ mod = _export_mod(monkeypatch)
+ llama_cpp, calls = _zoo(monkeypatch)
+
+ with mod._llama_cpp_scripts_pin():
+ assert os.environ[_SCRIPTS_DIR] == llama_cpp.LLAMA_CPP_DEFAULT_DIR
+ # The leak is the bug: every later export, and the MLX path's own internal pin,
+ # read a variable nobody set deliberately.
+ assert _SCRIPTS_DIR not in os.environ
+ assert calls["internal"] == [llama_cpp.LLAMA_CPP_DEFAULT_DIR]
+
+
+def test_pin_goes_through_the_internal_helper(monkeypatch):
+ """Not a raw os.environ write: unsloth_zoo grants the strict-scan exemption to a
+ pin the USER set, and marking this one internal is what keeps
+ UNSLOTH_CONVERTER_SCAN_STRICT=1 able to refuse a converter Studio downloaded."""
+ mod = _export_mod(monkeypatch)
+ llama_cpp, calls = _zoo(monkeypatch)
+
+ with mod._llama_cpp_scripts_pin():
+ pass
+ assert calls["internal"] == [llama_cpp.LLAMA_CPP_DEFAULT_DIR]
+
+
+def test_a_converter_tag_is_left_in_force(monkeypatch):
+ """The pin outranks the tag, so pinning at all made `UNSLOTH_LLAMA_CPP_CONVERTER_TAG=b9999`
+ a knob that changes nothing."""
+ mod = _export_mod(monkeypatch)
+ _llama_cpp, calls = _zoo(monkeypatch)
+ monkeypatch.setenv(_CONVERTER_TAG, "b9999")
+
+ with mod._llama_cpp_scripts_pin():
+ assert _SCRIPTS_DIR not in os.environ
+ assert calls["internal"] == []
+
+
+def test_a_pin_the_user_set_is_untouched(monkeypatch):
+ mod = _export_mod(monkeypatch)
+ _llama_cpp, _calls = _zoo(monkeypatch)
+ monkeypatch.setenv(_SCRIPTS_DIR, "/home/me/llama.cpp")
+
+ with mod._llama_cpp_scripts_pin():
+ assert os.environ[_SCRIPTS_DIR] == "/home/me/llama.cpp"
+ assert os.environ[_SCRIPTS_DIR] == "/home/me/llama.cpp"
+
+
+def test_an_incomplete_install_is_not_pinned(monkeypatch):
+ """An entrypoint with no conversion/ beside it cannot run, and pinning it is what
+ stops the staged resolver from fetching a co-versioned set that can."""
+ mod = _export_mod(monkeypatch)
+ _llama_cpp, calls = _zoo(monkeypatch, incomplete = True)
+
+ with mod._llama_cpp_scripts_pin():
+ assert _SCRIPTS_DIR not in os.environ
+ assert calls["internal"] == []
+
+
+def test_older_zoo_still_gets_a_scoped_pin(monkeypatch):
+ """No internal-pin helper to call, so the variable is scoped by hand. The strict-scan
+ exemption cannot be avoided on those builds, but the leak can."""
+ mod = _export_mod(monkeypatch)
+ llama_cpp, _calls = _zoo(monkeypatch, internal_pin = False)
+
+ with mod._llama_cpp_scripts_pin():
+ assert os.environ[_SCRIPTS_DIR] == llama_cpp.LLAMA_CPP_DEFAULT_DIR
+ assert _SCRIPTS_DIR not in os.environ
+
+
+def test_the_pin_unwinds_when_the_conversion_raises(monkeypatch):
+ mod = _export_mod(monkeypatch)
+ _llama_cpp, _calls = _zoo(monkeypatch)
+
+ with contextlib.suppress(RuntimeError):
+ with mod._llama_cpp_scripts_pin():
+ raise RuntimeError("conversion failed")
+ assert _SCRIPTS_DIR not in os.environ
+
+
+def test_mlx_leaves_the_pinning_to_unsloth_zoo(monkeypatch):
+ """The MLX save path installs llama.cpp and pins it itself, so there is nothing to
+ add here."""
+ mod = _export_mod(monkeypatch, mlx = True)
+ _llama_cpp, calls = _zoo(monkeypatch)
+
+ with mod._llama_cpp_scripts_pin():
+ assert _SCRIPTS_DIR not in os.environ
+ assert calls["internal"] == []
+
+
+def test_mlx_export_does_not_nest_the_pin(monkeypatch):
+ """unsloth_zoo's pin holds a plain threading.Lock for the whole conversion, so
+ entering it here and again inside save_pretrained_gguf hangs a Mac GGUF export
+ for good. The stub raises where the real one would block."""
+ mod = _export_mod(monkeypatch, mlx = True)
+ llama_cpp, _calls = _zoo(monkeypatch)
+
+ with mod._llama_cpp_scripts_pin():
+ # What unsloth_zoo/mlx/utils.py:save_pretrained_gguf does inside the call above.
+ with llama_cpp.internal_scripts_dir_pin(llama_cpp.LLAMA_CPP_DEFAULT_DIR):
+ pass
+ assert _SCRIPTS_DIR not in os.environ
+
+
+def test_a_gguf_export_leaves_no_pin_behind(tmp_path, monkeypatch):
+ """End to end through export_gguf: the pin is in force while the model converts and
+ gone once the export returns. The export worker outlives the export, so a variable
+ left here is read by every later export in that process."""
+ mod = _export_mod(monkeypatch)
+ llama_cpp, calls = _zoo(monkeypatch)
+ save_dir = tmp_path / "export"
+ monkeypatch.setattr(mod, "resolve_export_write_dir", lambda _value: save_dir)
+ seen = {}
+
+ class _Model:
+ def save_pretrained_gguf(self, model_save_path, tokenizer, **kwargs):
+ seen["pinned_during_conversion"] = os.environ.get(_SCRIPTS_DIR)
+ output_dir = Path(f"{model_save_path}_gguf")
+ output_dir.mkdir(parents = True, exist_ok = True)
+ (output_dir / "converted.gguf").write_bytes(b"gguf")
+
+ backend = mod.ExportBackend.__new__(mod.ExportBackend)
+ backend.current_model = _Model()
+ backend.current_tokenizer = object()
+ backend.current_checkpoint = None
+
+ success, message, _output_path = backend.export_gguf(str(save_dir), "Q4_K_M")
+
+ assert success is True, message
+ assert os.environ.get(_SCRIPTS_DIR) is None
+ assert seen["pinned_during_conversion"] == llama_cpp.LLAMA_CPP_DEFAULT_DIR
+ assert calls["internal"] == [llama_cpp.LLAMA_CPP_DEFAULT_DIR]
+
+
+def test_zoo_without_the_pin_warns_once_and_runs(monkeypatch):
+ mod = _export_mod(monkeypatch)
+ llama_cpp = sys.modules["unsloth_zoo.llama_cpp"]
+ monkeypatch.delattr(llama_cpp, "_resolve_local_convert_script", raising = False)
+ warnings = []
+ monkeypatch.setattr(
+ mod.logger, "warning", lambda message, *args, **kwargs: warnings.append(message)
+ )
+ monkeypatch.setattr(mod, "_LLAMA_CPP_SCRIPTS_WARNING_EMITTED", False)
+
+ ran = 0
+ for _ in range(2):
+ with mod._llama_cpp_scripts_pin():
+ ran += 1
+ assert _SCRIPTS_DIR not in os.environ
+ assert ran == 2
+ assert len(warnings) == 1
+ assert _SCRIPTS_DIR in warnings[0]
diff --git a/tests/studio/test_studio_gguf_export_script_pin.py b/tests/studio/test_studio_gguf_export_script_pin.py
index 2a308cd9a08..72d76486e8f 100644
--- a/tests/studio/test_studio_gguf_export_script_pin.py
+++ b/tests/studio/test_studio_gguf_export_script_pin.py
@@ -1,10 +1,25 @@
-"""Unsloth GGUF export pins convert_hf_to_gguf.py via UNSLOTH_LLAMA_CPP_SCRIPTS_DIR, with a once-per-process warning fallback when unsloth_zoo lacks the local-script resolver."""
+"""Unsloth GGUF export pins convert_hf_to_gguf.py for the conversion and takes the pin
+back afterwards, with a once-per-process warning fallback when unsloth_zoo lacks the
+local-script resolver.
+
+The pin used to be an ``os.environ.setdefault`` that was never unwound. unsloth_zoo reads
+UNSLOTH_LLAMA_CPP_SCRIPTS_DIR as the user's own choice: it outranks
+UNSLOTH_LLAMA_CPP_CONVERTER_TAG, and it exempts the converter from the
+UNSLOTH_CONVERTER_SCAN_STRICT refusal. Neither is true of a directory Studio pinned for
+its own routing, so the pin now goes through unsloth_zoo's internal_scripts_dir_pin and is
+scoped to the conversion.
+
+The behaviour cases below execute the real helper, lifted out of export.py with ast, rather
+than a copy written here: a hand-written copy of the block passes whatever the block does.
+"""
from __future__ import annotations
import ast
+import contextlib
import os
import sys
+import threading
import types
from pathlib import Path
@@ -14,6 +29,9 @@ SOURCE_PATH = (
)
SRC = SOURCE_PATH.read_text(encoding = "utf-8")
TREE = ast.parse(SRC)
+SCRIPTS_DIR = "UNSLOTH_LLAMA_CPP_SCRIPTS_DIR"
+CONVERTER_TAG = "UNSLOTH_LLAMA_CPP_CONVERTER_TAG"
+PIN_HELPER = "_llama_cpp_scripts_pin"
def _module_level_assignments(tree: ast.Module):
@@ -24,6 +42,13 @@ def _module_level_assignments(tree: ast.Module):
yield target.id, node.value
+def _pin_helper_node(tree: ast.AST):
+ for node in ast.walk(tree):
+ if isinstance(node, ast.FunctionDef) and node.name == PIN_HELPER:
+ return node
+ return None
+
+
def _find_pin_try(tree: ast.AST):
for node in ast.walk(tree):
if not isinstance(node, ast.Try):
@@ -64,6 +89,74 @@ def _covers_half_built_zoo(handler: ast.ExceptHandler) -> bool:
return bool(caught & set(_CATCHES_EVERYTHING)) or {"RuntimeError", "AttributeError"} <= caught
+def _load_pin_helper(*, is_mlx = False, logger = None):
+ """The real helper, executed on its own so these cases run the shipped code."""
+ node = _pin_helper_node(TREE)
+ assert node is not None, f"expected a {PIN_HELPER} helper in export.py"
+ namespace = {
+ "os": os,
+ "contextlib": contextlib,
+ "logger": logger
+ if logger is not None
+ else types.SimpleNamespace(warning = lambda *args, **kwargs: None),
+ "_LLAMA_CPP_SCRIPTS_WARNING_EMITTED": False,
+ "_IS_MLX": is_mlx,
+ }
+ exec(
+ compile(ast.Module(body = [node], type_ignores = []), str(SOURCE_PATH), "exec"),
+ namespace,
+ )
+ return namespace[PIN_HELPER], namespace
+
+
+def _install_fake_zoo(
+ monkeypatch,
+ *,
+ default_dir = "/fake/llama.cpp",
+ resolver = True,
+ internal_pin = True,
+ incomplete = False,
+):
+ """A stand-in unsloth_zoo.llama_cpp whose pin is as non-reentrant as the real one."""
+ calls = {"internal": []}
+ fake = types.ModuleType("unsloth_zoo.llama_cpp")
+ if default_dir is not None:
+ fake.LLAMA_CPP_DEFAULT_DIR = default_dir
+ if resolver:
+ fake._resolve_local_convert_script = lambda *args, **kwargs: None
+ fake._converter_dir_is_incomplete = lambda folder: incomplete
+ held = threading.Lock()
+
+ @contextlib.contextmanager
+ def _internal_scripts_dir_pin(folder):
+ if not held.acquire(blocking = False):
+ raise RuntimeError("internal_scripts_dir_pin re-entered: the real one deadlocks here")
+ calls["internal"].append(folder)
+ existing = os.environ.get(SCRIPTS_DIR)
+ if existing is None:
+ os.environ[SCRIPTS_DIR] = folder
+ try:
+ yield
+ finally:
+ if existing is None:
+ os.environ.pop(SCRIPTS_DIR, None)
+ else:
+ os.environ[SCRIPTS_DIR] = existing
+ held.release()
+
+ if internal_pin:
+ fake.internal_scripts_dir_pin = _internal_scripts_dir_pin
+ package = types.ModuleType("unsloth_zoo")
+ monkeypatch.setitem(sys.modules, "unsloth_zoo", package)
+ monkeypatch.setitem(sys.modules, "unsloth_zoo.llama_cpp", fake)
+ monkeypatch.delenv(SCRIPTS_DIR, raising = False)
+ monkeypatch.delenv(CONVERTER_TAG, raising = False)
+ return fake, calls
+
+
+# ---------------------------------------------------------------- source contract
+
+
def test_warning_flag_defined_at_module_scope():
flags = {
name: value
@@ -86,26 +179,70 @@ def test_constant_and_resolver_imported_in_same_try():
assert "_resolve_local_convert_script" in imported
-def test_setdefault_inside_try_block():
- try_node = _find_pin_try(TREE)
- assert try_node is not None
- setdefault_calls = []
- for stmt in try_node.body:
- for node in ast.walk(stmt):
- if (
- isinstance(node, ast.Call)
- and isinstance(node.func, ast.Attribute)
- and node.func.attr == "setdefault"
- and isinstance(node.func.value, ast.Attribute)
- and node.func.value.attr == "environ"
- and node.args
- and isinstance(node.args[0], ast.Constant)
- and node.args[0].value == "UNSLOTH_LLAMA_CPP_SCRIPTS_DIR"
- ):
- setdefault_calls.append(node)
- assert setdefault_calls
- second = setdefault_calls[0].args[1]
- assert isinstance(second, ast.Name) and second.id == "LLAMA_CPP_DEFAULT_DIR"
+def test_the_pin_is_never_left_in_the_environment():
+ """No setdefault, and every direct write is answered by a pop in a finally. The
+ setdefault this replaced is what made the converter tag inert and turned
+ UNSLOTH_CONVERTER_SCAN_STRICT into a warning for every Studio export."""
+ setdefaults = []
+ for node in ast.walk(TREE):
+ if (
+ isinstance(node, ast.Call)
+ and isinstance(node.func, ast.Attribute)
+ and node.func.attr == "setdefault"
+ and isinstance(node.func.value, ast.Attribute)
+ and node.func.value.attr == "environ"
+ and node.args
+ and isinstance(node.args[0], ast.Constant)
+ and node.args[0].value == SCRIPTS_DIR
+ ):
+ setdefaults.append(node)
+ assert not setdefaults, "the scripts pin must not be left in the environment"
+
+ helper = _pin_helper_node(TREE)
+ assert helper is not None
+ writes = [
+ node
+ for node in ast.walk(helper)
+ if isinstance(node, ast.Subscript)
+ and isinstance(node.ctx, ast.Store)
+ and isinstance(node.value, ast.Attribute)
+ and node.value.attr == "environ"
+ ]
+ pops = [
+ node
+ for node in ast.walk(helper)
+ if isinstance(node, ast.Call)
+ and isinstance(node.func, ast.Attribute)
+ and node.func.attr == "pop"
+ and isinstance(node.func.value, ast.Attribute)
+ and node.func.value.attr == "environ"
+ ]
+ assert len(writes) <= len(pops), "a direct write to os.environ needs an unwind"
+
+
+def test_pin_prefers_the_internal_helper():
+ """unsloth_zoo exempts a user pin from the strict converter scan, so Studio's own
+ routing has to be marked as internal or the exemption is taken by a converter nobody
+ reviewed."""
+ helper = _pin_helper_node(TREE)
+ assert helper is not None
+ imported = [
+ alias.name
+ for node in ast.walk(helper)
+ if isinstance(node, ast.ImportFrom) and node.module == "unsloth_zoo.llama_cpp"
+ for alias in node.names
+ ]
+ assert "internal_scripts_dir_pin" in imported
+ used = [
+ item
+ for node in ast.walk(helper)
+ if isinstance(node, ast.With)
+ for item in node.items
+ if isinstance(item.context_expr, ast.Call)
+ and isinstance(item.context_expr.func, ast.Name)
+ and item.context_expr.func.id == "internal_scripts_dir_pin"
+ ]
+ assert used, "internal_scripts_dir_pin must be entered, not just imported"
def test_warning_handler_gated_on_module_flag():
@@ -141,92 +278,114 @@ def test_warning_handler_gated_on_module_flag():
assert flag_writes
assert warning_calls
msg = ast.dump(warning_calls[0])
- assert "UNSLOTH_LLAMA_CPP_SCRIPTS_DIR" in msg
+ assert SCRIPTS_DIR in msg
assert "unsloth_zoo" in msg
-def test_default_dir_is_string_for_setdefault_compat():
+def test_default_dir_is_string():
from unsloth_zoo.llama_cpp import LLAMA_CPP_DEFAULT_DIR
assert isinstance(LLAMA_CPP_DEFAULT_DIR, str)
-def test_setdefault_preserves_explicit_user_override(monkeypatch):
- monkeypatch.setenv("UNSLOTH_LLAMA_CPP_SCRIPTS_DIR", "/explicit/override")
- from unsloth_zoo.llama_cpp import LLAMA_CPP_DEFAULT_DIR
+# ---------------------------------------------------------------- behaviour
- os.environ.setdefault("UNSLOTH_LLAMA_CPP_SCRIPTS_DIR", LLAMA_CPP_DEFAULT_DIR)
- assert os.environ["UNSLOTH_LLAMA_CPP_SCRIPTS_DIR"] == "/explicit/override"
+def test_pin_is_in_force_only_while_converting(monkeypatch):
+ fake, calls = _install_fake_zoo(monkeypatch)
+ pin, _ns = _load_pin_helper()
-def test_setdefault_assigns_default_when_unset(monkeypatch):
- monkeypatch.delenv("UNSLOTH_LLAMA_CPP_SCRIPTS_DIR", raising = False)
- from unsloth_zoo.llama_cpp import LLAMA_CPP_DEFAULT_DIR
+ with pin():
+ assert os.environ[SCRIPTS_DIR] == fake.LLAMA_CPP_DEFAULT_DIR
+ assert SCRIPTS_DIR not in os.environ
+ assert calls["internal"] == [fake.LLAMA_CPP_DEFAULT_DIR]
- os.environ.setdefault("UNSLOTH_LLAMA_CPP_SCRIPTS_DIR", LLAMA_CPP_DEFAULT_DIR)
- assert os.environ["UNSLOTH_LLAMA_CPP_SCRIPTS_DIR"] == LLAMA_CPP_DEFAULT_DIR
+def test_pin_preserves_an_explicit_user_override(monkeypatch):
+ _fake, _calls = _install_fake_zoo(monkeypatch)
+ monkeypatch.setenv(SCRIPTS_DIR, "/explicit/override")
+ pin, _ns = _load_pin_helper()
-def _simulate_pin_block(emit_records, set_value):
- fake = types.ModuleType("unsloth_zoo.llama_cpp")
- if set_value is not None:
- fake.LLAMA_CPP_DEFAULT_DIR = set_value
- sys.modules["unsloth_zoo.llama_cpp"] = fake
+ with pin():
+ assert os.environ[SCRIPTS_DIR] == "/explicit/override"
+ assert os.environ[SCRIPTS_DIR] == "/explicit/override"
- state = {"emitted": False}
- def run_once():
- try:
- from unsloth_zoo.llama_cpp import (
- LLAMA_CPP_DEFAULT_DIR,
- _resolve_local_convert_script, # noqa: F401
- )
- os.environ.setdefault("UNSLOTH_LLAMA_CPP_SCRIPTS_DIR", LLAMA_CPP_DEFAULT_DIR)
- except ImportError:
- if not state["emitted"]:
- emit_records.append("warned")
- state["emitted"] = True
+def test_converter_tag_is_not_overridden(monkeypatch):
+ """UNSLOTH_LLAMA_CPP_SCRIPTS_DIR outranks the tag, so pinning while a tag is set is
+ what made the tag do nothing."""
+ _fake, calls = _install_fake_zoo(monkeypatch)
+ monkeypatch.setenv(CONVERTER_TAG, "b9999")
+ pin, _ns = _load_pin_helper()
+
+ with pin():
+ assert SCRIPTS_DIR not in os.environ
+ assert calls["internal"] == []
+
+
+def test_incomplete_install_is_not_pinned(monkeypatch):
+ _fake, calls = _install_fake_zoo(monkeypatch, incomplete = True)
+ pin, _ns = _load_pin_helper()
+
+ with pin():
+ assert SCRIPTS_DIR not in os.environ
+ assert calls["internal"] == []
- return run_once
+
+def test_mlx_does_not_nest_the_pin(monkeypatch):
+ """unsloth_zoo's MLX save path pins the converter itself and its pin holds a plain
+ threading.Lock across the conversion, so a second entry hangs the export."""
+ fake, calls = _install_fake_zoo(monkeypatch)
+ pin, _ns = _load_pin_helper(is_mlx = True)
+
+ with pin():
+ with fake.internal_scripts_dir_pin(fake.LLAMA_CPP_DEFAULT_DIR):
+ pass
+ assert calls["internal"] == [fake.LLAMA_CPP_DEFAULT_DIR]
+ assert SCRIPTS_DIR not in os.environ
+
+
+def test_older_zoo_without_the_internal_helper_still_unwinds(monkeypatch):
+ fake, _calls = _install_fake_zoo(monkeypatch, internal_pin = False)
+ pin, _ns = _load_pin_helper()
+
+ with pin():
+ assert os.environ[SCRIPTS_DIR] == fake.LLAMA_CPP_DEFAULT_DIR
+ assert SCRIPTS_DIR not in os.environ
def test_warning_fires_at_most_once_across_calls(monkeypatch):
- monkeypatch.delenv("UNSLOTH_LLAMA_CPP_SCRIPTS_DIR", raising = False)
+ """A zoo with no local-script resolver: warn once, keep exporting."""
+ _fake, _calls = _install_fake_zoo(monkeypatch, resolver = False)
emits = []
- runner = _simulate_pin_block(emits, set_value = "/fake/default")
- runner()
- runner()
- runner()
- assert emits == ["warned"]
+ logger = types.SimpleNamespace(warning = lambda message, *a, **k: emits.append(message))
+ pin, _ns = _load_pin_helper(logger = logger)
+
+ for _ in range(3):
+ with pin():
+ pass
+ assert len(emits) == 1
+ assert SCRIPTS_DIR in emits[0]
+ assert SCRIPTS_DIR not in os.environ
def test_missing_default_dir_degrades_to_warning(monkeypatch):
- monkeypatch.delenv("UNSLOTH_LLAMA_CPP_SCRIPTS_DIR", raising = False)
+ _fake, _calls = _install_fake_zoo(monkeypatch, default_dir = None)
emits = []
- runner = _simulate_pin_block(emits, set_value = None)
- runner()
- assert emits == ["warned"]
- assert "UNSLOTH_LLAMA_CPP_SCRIPTS_DIR" not in os.environ
+ logger = types.SimpleNamespace(warning = lambda message, *a, **k: emits.append(message))
+ pin, _ns = _load_pin_helper(logger = logger)
+ with pin():
+ assert SCRIPTS_DIR not in os.environ
+ assert len(emits) == 1
+ assert SCRIPTS_DIR not in os.environ
-def test_no_warning_when_both_symbols_present(monkeypatch):
- monkeypatch.delenv("UNSLOTH_LLAMA_CPP_SCRIPTS_DIR", raising = False)
- fake = types.ModuleType("unsloth_zoo.llama_cpp")
- fake.LLAMA_CPP_DEFAULT_DIR = "/fake/dir"
- fake._resolve_local_convert_script = lambda: None
- monkeypatch.setitem(sys.modules, "unsloth_zoo.llama_cpp", fake)
+def test_no_warning_when_both_symbols_present(monkeypatch):
+ fake, _calls = _install_fake_zoo(monkeypatch)
emits = []
- state = {"emitted": False}
- try:
- from unsloth_zoo.llama_cpp import (
- LLAMA_CPP_DEFAULT_DIR,
- _resolve_local_convert_script, # noqa: F401
- )
- os.environ.setdefault("UNSLOTH_LLAMA_CPP_SCRIPTS_DIR", LLAMA_CPP_DEFAULT_DIR)
- except ImportError:
- if not state["emitted"]:
- emits.append("warned")
- state["emitted"] = True
+ logger = types.SimpleNamespace(warning = lambda message, *a, **k: emits.append(message))
+ pin, _ns = _load_pin_helper(logger = logger)
+ with pin():
+ assert os.environ.get(SCRIPTS_DIR) == fake.LLAMA_CPP_DEFAULT_DIR
assert emits == []
- assert os.environ.get("UNSLOTH_LLAMA_CPP_SCRIPTS_DIR") == "/fake/dir"