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.

9.0 KB
Raw Blame
# SPDX-License-Identifier: AGPL-3.0-only
# Copyright 2026-Present the Unsloth team. See /studio/LICENSE.AGPL-3.0

"""Cleaned notebooks are recorded before publish, or one lost state write strands the whole set."""

from __future__ import annotations

import hashlib
import importlib.util
import json
import os
from pathlib import Path

import pytest

REPO_ROOT = Path(__file__).resolve().parents[2]
STRIP_PATH = REPO_ROOT / "docker" / "unsloth_nb_strip_colab.py"

INTRO = (
    'To run this, press "*Runtime*" and press "*Run all*" on a **free** '
    "Tesla T4 Google Colab instance!\n"
)
# json.dumps escapes quotes in INTRO; this fragment appears verbatim and only there.
MARK = "Tesla T4 Google Colab instance"


@pytest.fixture(scope = "module")
def strip():
    assert STRIP_PATH.is_file(), f"missing {STRIP_PATH}"
    spec = importlib.util.spec_from_file_location("unsloth_nb_strip_durability", STRIP_PATH)
    mod = importlib.util.module_from_spec(spec)
    spec.loader.exec_module(mod)
    return mod


def _sha256(path: Path) -> str:
    return hashlib.sha256(path.read_bytes()).hexdigest()


def _notebook(path: Path, tag: str) -> None:
    path.parent.mkdir(parents = True, exist_ok = True)
    path.write_text(
        json.dumps(
            {
                "cells": [
                    {"cell_type": "markdown", "source": [INTRO], "metadata": {}},
                    {
                        "cell_type": "code",
                        "source": [f"print({tag!r})\n"],
                        "metadata": {},
                        "outputs": [],
                        "execution_count": None,
                    },
                ],
                "metadata": {"widgets": {"stale": True}},
                "nbformat": 4,
                "nbformat_minor": 5,
            }
        ),
        encoding = "utf-8",
    )


@pytest.fixture
def tree(tmp_path: Path):
    dest = tmp_path / "dest"
    names = [f"nb/n{i}.ipynb" for i in range(4)]
    lines = []
    for i, rel in enumerate(names):
        _notebook(dest / rel, f"cell-{i}")
        lines.append(f"{_sha256(dest / rel)}  {rel}")
    state = dest / ".unsloth_sync_state"
    state.write_text("\n".join(lines) + "\n", encoding = "utf-8")
    return dest, state, names


def _state(state: Path) -> dict:
    out = {}
    for line in state.read_text(encoding = "utf-8").splitlines():
        parts = line.split("  ", 1)
        if len(parts) == 2:
            out[parts[1]] = parts[0]
    return out


def _orphans(dest: Path, state: Path, names) -> list:
    """Notebooks on disk whose bytes no longer match what the state file records.
    Every one of these is permanently frozen from the refresh's point of view."""
    recorded = _state(state)
    return [rel for rel in names if recorded.get(rel) != _sha256(dest / rel)]


def test_the_migration_records_what_it_published(strip, tree):
    dest, state, names = tree
    assert strip.migrate(str(state), str(dest)) == 0
    assert _orphans(dest, state, names) == []
    for rel in names:
        assert MARK not in (dest / rel).read_text(encoding = "utf-8")


def test_a_failing_state_write_publishes_nothing(strip, tree, monkeypatch):
    """The whole point of the ordering: if the record cannot be written, the notebook
    must not be cleaned either, so the disk still matches and the next start retries."""
    dest, state, names = tree
    monkeypatch.setattr(strip, "_write_state", lambda *a, **k: False)

    assert strip.migrate(str(state), str(dest)) == 0

    assert _orphans(dest, state, names) == []
    for rel in names:
        assert MARK in (dest / rel).read_text(encoding = "utf-8"), rel
    assert not list((dest / "nb").glob("*.tmp")), "a staged copy was left behind"


def test_a_state_write_that_fails_partway_strands_nothing(strip, tree, monkeypatch):
    """The realistic shape: the disk fills, or the container is stopped, midway."""
    dest, state, names = tree
    real = strip._write_state
    calls = {"n": 0}

    def _fail_after_two(path, lines):
        calls["n"] += 1
        if calls["n"] > 2:
            return False
        return real(path, lines)

    monkeypatch.setattr(strip, "_write_state", _fail_after_two)

    assert strip.migrate(str(state), str(dest)) == 0

    assert _orphans(dest, state, names) == []
    cleaned = [rel for rel in names if MARK not in (dest / rel).read_text(encoding = "utf-8")]
    assert len(cleaned) == 2, cleaned
    assert not list((dest / "nb").glob("*.tmp"))


def test_the_rest_is_cleaned_on_the_next_start(strip, tree, monkeypatch):
    dest, state, names = tree
    real = strip._write_state
    calls = {"n": 0}

    def _fail_after_two(path, lines):
        calls["n"] += 1
        return real(path, lines) if calls["n"] <= 2 else False

    monkeypatch.setattr(strip, "_write_state", _fail_after_two)
    strip.migrate(str(state), str(dest))
    monkeypatch.setattr(strip, "_write_state", real)

    assert strip.migrate(str(state), str(dest)) == 0

    assert _orphans(dest, state, names) == []
    for rel in names:
        assert MARK not in (dest / rel).read_text(encoding = "utf-8"), rel


def test_a_notebook_that_fails_to_publish_gives_its_record_back(strip, tree, monkeypatch):
    """The inverted window. It is one notebook rather than all of them, and it is
    undone by rewriting that entry, which is why this ordering is the safe one."""
    dest, state, names = tree
    before = dict(_state(state))
    monkeypatch.setattr(strip, "_publish", lambda tmp, path, prev: strip._unlink(tmp) or False)

    assert strip.migrate(str(state), str(dest)) == 0

    assert _state(state) == before, "a record was left pointing at bytes never published"
    assert _orphans(dest, state, names) == []
    assert not list((dest / "nb").glob("*.tmp"))


def test_the_state_write_is_fsynced_before_the_rename(strip, tmp_path, monkeypatch):
    """A rename made visible before its content is durable strands the notebooks the
    same way a failed write does."""
    order = []
    real_fsync = os.fsync
    real_replace = os.replace

    monkeypatch.setattr(os, "fsync", lambda fd: order.append("fsync") or real_fsync(fd))
    monkeypatch.setattr(os, "replace", lambda a, b: order.append("replace") or real_replace(a, b))

    target = tmp_path / "state"
    assert strip._write_state(str(target), ["a  b"]) is True
    assert order == ["fsync", "replace"], order
    assert target.read_text(encoding = "utf-8") == "a  b\n"


def test_malformed_and_unmanaged_lines_survive_verbatim(strip, tmp_path):
    dest = tmp_path / "dest"
    _notebook(dest / "nb/x.ipynb", "x")
    state = dest / ".unsloth_sync_state"
    state.write_text(
        "not-a-record\n"
        f"{_sha256(dest / 'nb/x.ipynb')}  nb/x.ipynb\n"
        "deadbeef  nb/gone.ipynb\n",
        encoding = "utf-8",
    )

    assert strip.migrate(str(state), str(dest)) == 0

    lines = state.read_text(encoding = "utf-8").splitlines()
    assert lines[0] == "not-a-record"
    assert lines[2] == "deadbeef  nb/gone.ipynb"
    assert lines[1] == f"{_sha256(dest / 'nb/x.ipynb')}  nb/x.ipynb"


def test_a_publish_cut_off_after_its_record_is_recovered(strip, tree, monkeypatch):
    """A cut between writing the record and the notebook leaves one recoverable mismatch, not a lost set."""
    dest, state, names = tree

    def _killed(tmp, path, before):
        strip._unlink(tmp)
        raise KeyboardInterrupt

    monkeypatch.setattr(strip, "_publish", _killed)
    with pytest.raises(KeyboardInterrupt):
        strip.migrate(str(state), str(dest))
    monkeypatch.undo()

    stranded = _orphans(dest, state, names)
    assert stranded, "precondition: a record ran ahead of its notebook"
    for rel in stranded:
        assert MARK in (dest / rel).read_text(encoding = "utf-8"), rel

    assert strip.migrate(str(state), str(dest)) == 0

    assert _orphans(dest, state, names) == []
    for rel in names:
        assert MARK not in (dest / rel).read_text(encoding = "utf-8"), rel


def test_a_real_user_edit_is_still_left_alone(strip, tree):
    """The blast radius. Recovery must not become a licence to rewrite a notebook
    whose hash stopped matching for the ordinary reason."""
    dest, state, names = tree
    rel = names[0]
    path = dest / rel
    nb = json.loads(path.read_text(encoding = "utf-8"))
    nb["cells"].append(
        {
            "cell_type": "code",
            "source": ["print('mine')\n"],
            "metadata": {},
            "outputs": [],
            "execution_count": None,
        }
    )
    path.write_text(json.dumps(nb), encoding = "utf-8")
    mine = path.read_text(encoding = "utf-8")
    recorded = _state(state)[rel]

    assert strip.migrate(str(state), str(dest)) == 0

    assert path.read_text(encoding = "utf-8") == mine, "the user's notebook was rewritten"
    assert _state(state)[rel] == recorded


def test_the_recovery_keys_on_reproducing_the_record(strip, tree):
    """Non-vacuity: cleaning the file has to land on the recorded hash exactly, which
    only the interrupted publish can do, so nothing else is touched."""
    dest, state, names = tree
    path = dest / names[0]

    assert strip._resume(str(path), "0" * 64) is False
    assert MARK in path.read_text(encoding = "utf-8")