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.
Python agentaichatgptdeepseekfine-tuninggemmaimage-generationllamallmllmsopenaipythonqwenreinforcement-learningself-hostedstable-diffusiontext-to-speechttsuiunsloth
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.pyindex 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.pynew file mode 100644index 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.pyindex 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 annotationsimport ast+import contextlibimport osimport sys+import threadingimport typesfrom 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_writesassert warning_callsmsg = ast.dump(warning_calls[0])- assert "UNSLOTH_LLAMA_CPP_SCRIPTS_DIR" in msg+ assert SCRIPTS_DIR in msgassert "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_DIRassert 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.environdef 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.environdef 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_DIRassert emits == []- assert os.environ.get("UNSLOTH_LLAMA_CPP_SCRIPTS_DIR") == "/fake/dir"