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.

12.6 KB
Raw Blame
# SPDX-License-Identifier: AGPL-3.0-only
# Copyright 2026-present the Unsloth AI Inc. team. All rights reserved.

"""Install cells hash their specs, not comments or spacing, so a pin bump reaches the container."""

from __future__ import annotations

import importlib.util
import json
from pathlib import Path

import pytest

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

_INSTALL = "!pip install --upgrade unsloth transformers==4.56.2\n"


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


def _write(path: Path, *sources) -> Path:
    cells = []
    for cell_type, text in sources:
        cells.append({"cell_type": cell_type, "source": [text], "metadata": {}})
    path.write_text(
        json.dumps({"cells": cells, "metadata": {}, "nbformat": 4, "nbformat_minor": 5}),
        encoding = "utf-8",
    )
    return path


def _same(sig, tmp_path: Path, before, after) -> bool:
    a = _write(tmp_path / "a.ipynb", *before)
    b = _write(tmp_path / "b.ipynb", *after)
    return sig.middle_digest(str(a)) == sig.middle_digest(str(b))


def test_a_pin_bump_in_the_install_cell_is_visible(sig, tmp_path: Path):
    assert not _same(
        sig,
        tmp_path,
        [("code", _INSTALL), ("code", "print(1)\n")],
        [("code", _INSTALL.replace("4.56.2", "5.5.0")), ("code", "print(1)\n")],
    ), "a changed version pin must make the notebook refresh"


def test_an_added_dependency_is_visible(sig, tmp_path: Path):
    assert not _same(
        sig,
        tmp_path,
        [("code", _INSTALL), ("code", "print(1)\n")],
        [("code", _INSTALL.rstrip("\n") + " trl\n"), ("code", "print(1)\n")],
    ), "an added package must make the notebook refresh"


def test_a_removed_install_cell_is_visible(sig, tmp_path: Path):
    assert not _same(
        sig,
        tmp_path,
        [("code", _INSTALL), ("code", "!pip install extras\n"), ("code", "print(1)\n")],
        [("code", _INSTALL), ("code", "print(1)\n")],
    ), "dropping an install cell must make the notebook refresh"


def test_cosmetic_install_churn_is_still_the_same(sig, tmp_path: Path):
    churned = (
        "# regenerated by update_all_notebooks.py\n"
        "\n"
        "!pip install    --upgrade   unsloth   transformers==4.56.2\n"
        "   # keep the pin in step with the sidecar\n"
    )
    assert _same(
        sig,
        tmp_path,
        [("code", _INSTALL), ("code", "print(1)\n")],
        [("code", churned), ("code", "print(1)\n")],
    ), "comment/whitespace churn in the install cell must not force a refresh"


def test_a_url_fragment_is_not_mistaken_for_a_comment(sig, tmp_path: Path):
    # #subdirectory= selects the package, so it must survive normalisation.
    a = '!pip install "git+https://github.com/o/r#subdirectory=pkg_a"\n'
    b = '!pip install "git+https://github.com/o/r#subdirectory=pkg_b"\n'
    assert not _same(
        sig, tmp_path, [("code", a), ("code", "print(1)\n")], [("code", b), ("code", "print(1)\n")]
    ), "a #fragment inside a requirement is data, not a comment"


def test_boilerplate_markdown_is_still_ignored(sig, tmp_path: Path):
    assert _same(
        sig,
        tmp_path,
        [("markdown", "To run this, press Runtime\n"), ("code", "print(1)\n")],
        [("markdown", "To run this, press Runtime and Run all\n"), ("code", "print(1)\n")],
    ), "the announcement block must still be excluded"


def test_a_body_change_is_still_visible(sig, tmp_path: Path):
    assert not _same(
        sig,
        tmp_path,
        [("code", _INSTALL), ("code", "print(1)\n")],
        [("code", _INSTALL), ("code", "print(2)\n")],
    ), "a real code change must still make the notebook refresh"


# Leading whitespace is significant: dedenting out of `else:` changes behaviour.

_UPSTREAM_HEAD = (
    "%%capture\n"
    "import os, re\n"
    'if "COLAB_" not in "".join(os.environ.keys()):\n'
    "    !pip install unsloth\n"
    "else:\n"
    '    !pip install sentencepiece protobuf "datasets==4.3.0" hf_transfer\n'
    "    !pip install --no-deps unsloth_zoo bitsandbytes accelerate peft trl triton unsloth\n"
)


def test_moving_an_install_line_out_of_the_colab_branch_is_visible(sig, tmp_path: Path):
    inside = _UPSTREAM_HEAD + '    !pip install --no-deps --upgrade "torchao>=0.16.0"\n'
    outside = _UPSTREAM_HEAD + '!pip install --no-deps --upgrade "torchao>=0.16.0"\n'
    assert not _same(
        sig,
        tmp_path,
        [("code", inside), ("code", "print(1)\n")],
        [("code", outside), ("code", "print(1)\n")],
    ), "dedenting an install line out of the Colab-only branch must force a refresh"


def test_indenting_an_install_line_into_the_colab_branch_is_visible(sig, tmp_path: Path):
    outside = _UPSTREAM_HEAD + '!pip install --no-deps --upgrade "torchao>=0.16.0"\n'
    inside = _UPSTREAM_HEAD + '    !pip install --no-deps --upgrade "torchao>=0.16.0"\n'
    assert not _same(
        sig,
        tmp_path,
        [("code", outside), ("code", "print(1)\n")],
        [("code", inside), ("code", "print(1)\n")],
    ), "indenting an install line into the Colab-only branch must force a refresh"


def test_indentation_churn_inside_the_cell_is_still_cosmetic(sig, tmp_path: Path):
    churned = (
        "%%capture\n"
        "# regenerated by update_all_notebooks.py\n"
        "import os,   re\n"
        "\n"
        'if "COLAB_" not in "".join(os.environ.keys()):\n'
        "\t!pip install    unsloth\n"
        "    # keep the pin in step with the sidecar\n"
        "else:\n"
        '\t!pip install sentencepiece protobuf "datasets==4.3.0"  hf_transfer\n'
        "\t!pip install  --no-deps unsloth_zoo bitsandbytes accelerate peft trl triton unsloth\n"
    )
    assert _same(
        sig,
        tmp_path,
        [("code", _UPSTREAM_HEAD), ("code", "print(1)\n")],
        [("code", churned), ("code", "print(1)\n")],
    ), "comment/blank/inner-spacing/tab churn at the same depth must stay SAME"


# Classify per line: NeMo-Gym notebooks mention `uv pip install` in prose inside code.

_NEMO_STYLE = (
    "# Inside the .venv guard this cell used to carry, `uv pip install` was run here.\n"
    "import subprocess\n"
    "with open(cfg, 'w') as _f:\n"
    "    _f.write(\n"
    '        "instruction_following:\\n"\n'
    '        "  resources_servers:\\n"\n'
    '        "      entrypoint: app.py\\n"\n'
    "    )\n"
)


def test_a_comment_mentioning_an_install_does_not_make_it_an_install_cell(sig):
    cell = {"cell_type": "code", "source": [_NEMO_STYLE]}
    assert not sig._is_install_code(
        cell
    ), "a 200-line Python cell was flattened because a comment named uv pip install"


def test_yaml_nesting_inside_a_string_literal_is_not_cosmetic(sig, tmp_path: Path):
    renested = _NEMO_STYLE.replace('"      entrypoint', '"    entrypoint')
    assert renested != _NEMO_STYLE
    assert not _same(
        sig,
        tmp_path,
        [("code", _NEMO_STYLE), ("code", "print(1)\n")],
        [("code", renested), ("code", "print(1)\n")],
    ), "re-nesting a generated YAML key changes what the notebook writes"


def test_a_string_literal_beside_a_real_install_is_still_compared(sig, tmp_path: Path):
    """The reviewer's case: the cell really does install, so it is an install cell,
    but the code around the install must not be flattened with it."""
    before = _INSTALL + 'script = "echo # pip install foo"\n'
    after = _INSTALL + 'script = "echo # pip install bar"\n'
    assert not _same(
        sig,
        tmp_path,
        [("code", before), ("code", "print(1)\n")],
        [("code", after), ("code", "print(1)\n")],
    ), "a `#` inside a string is data, not a comment"


_COMPOUND = "!pip install foo && python -c 'print(\"a # b\")' && pip install bar==2.0\n"


def test_a_quoted_hash_on_a_compound_install_line_is_data(sig, tmp_path: Path):
    assert sig._is_install_line(_COMPOUND.strip(), False)
    assert not _same(
        sig,
        tmp_path,
        [("code", _COMPOUND), ("code", "print(1)\n")],
        [("code", _COMPOUND.replace("# b", "# c")), ("code", "print(1)\n")],
    ), "a `#` inside a quoted stretch of an install line is data, not a comment"


def test_a_pin_after_a_quoted_hash_is_still_visible(sig, tmp_path: Path):
    """The cost of cutting at the quoted `#`: every spec behind it vanished too."""
    assert not _same(
        sig,
        tmp_path,
        [("code", _COMPOUND), ("code", "print(1)\n")],
        [("code", _COMPOUND.replace("bar==2.0", "bar==3.0")), ("code", "print(1)\n")],
    ), "a changed pin behind a quoted `#` must still make the notebook refresh"


def test_a_real_trailing_comment_on_an_install_line_is_still_cosmetic(sig, tmp_path: Path):
    assert _same(
        sig,
        tmp_path,
        [("code", _INSTALL.rstrip("\n") + "  # install the stack\n"), ("code", "print(1)\n")],
        [("code", _INSTALL.rstrip("\n") + " # bring in the stack\n"), ("code", "print(1)\n")],
    ), "an unquoted trailing comment must stay cosmetic"


def test_whitespace_inside_a_string_is_data_too(sig, tmp_path: Path):
    assert not _same(
        sig,
        tmp_path,
        [("code", _INSTALL + 'cfg = "a  b"\n'), ("code", "print(1)\n")],
        [("code", _INSTALL + 'cfg = "a    b"\n'), ("code", "print(1)\n")],
    )


def test_a_shell_cell_needs_no_bang_prefix(sig, tmp_path: Path):
    """`%%bash` makes the cell shell, so the marker needs no `!` prefix there."""
    cell = {"cell_type": "code", "source": ["%%bash\npip install unsloth\n"]}
    assert sig._is_install_code(cell)
    churned = "%%bash\npip install  unsloth\n# comment\n"
    assert _same(
        sig,
        tmp_path,
        [("code", "%%bash\npip install unsloth\n"), ("code", "print(1)\n")],
        [("code", churned), ("code", "print(1)\n")],
    )


@pytest.mark.parametrize(
    "line",
    [
        "!pip install unsloth\n",
        "  !pip install unsloth\n",
        "%pip install unsloth\n",
        "%uv pip install unsloth\n",
        "!uv pip install unsloth\n",
        "!apt-get install -y ffmpeg\n",
    ],
)
def test_every_real_invocation_still_counts_as_an_install_cell(sig, line):
    assert sig._is_install_code({"cell_type": "code", "source": [line]}), line


@pytest.mark.parametrize(
    "line",
    [
        "# pip install unsloth\n",
        'note = "pip install unsloth"\n',
        "print('run pip install unsloth first')\n",
        "subprocess.run(['bash', '-c', 'uv pip install foo'])\n",
    ],
)
def test_a_mention_is_not_an_invocation(sig, line):
    assert not sig._is_install_code({"cell_type": "code", "source": [line]}), line


def test_pip3_is_deliberately_absent_from_the_markers(sig):
    """pip3 is absent from the install markers on purpose: unrecognised cells compare byte for byte."""
    assert not any("pip3 install" == m for m in sig._INSTALL_MARKERS)
    assert not sig._is_install_code({"cell_type": "code", "source": ["!pip3 install x\n"]})


# In %%bash cells quoted `# ...` and spacing are data, so they must not be normalised away.
_SHELL_MENTION = '%%bash\nmsg="pip install foo # bar"\necho "$msg"\n'


def test_a_quoted_mention_in_a_shell_cell_is_not_a_command(sig, tmp_path: Path):
    assert not sig._is_install_line('msg="pip install foo # bar"', True)
    assert not _same(
        sig,
        tmp_path,
        [("code", _SHELL_MENTION), ("code", "print(1)\n")],
        [("code", _SHELL_MENTION.replace("# bar", "# baz")), ("code", "print(1)\n")],
    ), "editing a quoted shell string changes what the cell runs"


def test_an_operand_in_a_shell_cell_is_not_a_command(sig):
    assert not sig._is_install_line("echo pip install foo", True)
    assert not sig._is_install_line("grep -c 'x' pip install.log", True)


@pytest.mark.parametrize(
    "line",
    [
        "pip install unsloth",
        "  pip install unsloth",
        "sudo apt-get install -y ffmpeg",
        "uv pip install unsloth",
        "cd /tmp && pip install unsloth",
        "mkdir -p x; pip install unsloth",
        "PIP_NO_CACHE_DIR=1 pip install unsloth",
        "python3 -m pip install unsloth",
        "!pip install unsloth",
        'pip install "unsloth[all]"',
    ],
)
def test_a_real_shell_invocation_still_counts(sig, line):
    assert sig._is_install_line(line, True), line


def test_the_whole_shipped_corpus_is_unaffected(sig):
    """All marker lines inside the shipped %%bash notebook cells open a command, so narrowing the
    marker changes no digest; only the review-found tail is removed."""
    for line in (
        "pip install -q unsloth",
        "apt install -y git",
        "conda install -c conda-forge x",
    ):
        assert sig._is_install_line(line, True), line