Skip to content

Quickly sandbox your AI agent.

Python

feat(cli): serve GitHub releases as PEP 503 simple index

Tyler Payne7e01b08061d6
diff --git a/.github/workflows/docs.yml b/.github/workflows/docs.yml
index c9ee3cd..73c86f5 100644
--- a/.github/workflows/docs.yml
+++ b/.github/workflows/docs.yml
@@ -7,6 +7,13 @@ on:
- 'docs/**'
- 'package.json'
- 'package-lock.json'
+ - 'scripts/ci/build_simple_index.py'
+ - '.github/workflows/docs.yml'
+ # The Release Wheels workflow tags + publishes per-package GitHub Releases.
+ # Re-run docs after each successful release to refresh the simple/ index.
+ workflow_run:
+ workflows: [Release Wheels]
+ types: [completed]
workflow_dispatch: {}
permissions:
@@ -20,6 +27,8 @@ concurrency:
jobs:
build:
+ # workflow_run fires on every Release Wheels completion; gate on success.
+ if: ${{ github.event_name != 'workflow_run' || github.event.workflow_run.conclusion == 'success' }}
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
@@ -33,6 +42,12 @@ jobs:
- run: npm run docs:build
+ - name: Build PEP 503 simple index from GitHub Releases
+ env:
+ GH_TOKEN: ${{ github.token }}
+ GITHUB_REPOSITORY: ${{ github.repository }}
+ run: python scripts/ci/build_simple_index.py docs/.vitepress/dist
+
- uses: actions/upload-pages-artifact@v3
with:
path: docs/.vitepress/dist
diff --git a/packages/quicksand/quicksand/cli/install.py b/packages/quicksand/quicksand/cli/install.py
index cecbe72..c5053d1 100644
--- a/packages/quicksand/quicksand/cli/install.py
+++ b/packages/quicksand/quicksand/cli/install.py
@@ -1,18 +1,21 @@
-"""Install optional quicksand extras from PyPI.
+"""Install optional quicksand packages from the quicksand simple index.
-Delegates version resolution and platform-wheel selection to ``pip``: a
-package on PyPI under 100 MB ships as a fat wheel with images bundled in;
-larger ones ship as a pure ``py3-none-any`` stub that pulls the matching
-fat wheel from GitHub Releases on first install (via
-:func:`quicksand_core._auto_install.auto_install_images`).
+Delegates everything (version resolution, platform wheel selection,
+transitive dependency resolution) to ``pip``. Every wheel attached to every
+per-package GitHub release is exposed through a PEP 503 index at
+``https://microsoft.github.io/quicksand/simple/``. PyPI is configured as an
+extra index so transitive dependencies resolve normally.
+
+Arguments use standard pip requirement syntax (PEP 508): ``quicksand-qemu``,
+``quicksand-qemu==0.5.9``, ``quicksand-ubuntu>=0.4,<0.5``. Short aliases
+(``qemu`` → ``quicksand-qemu``) are accepted in place of the project name.
Programmatic API::
from quicksand import install
- install("qemu", "ubuntu") # install latest from PyPI
- install("[email protected]") # pin a version
- install("ubuntu", arch="amd64") # cross-arch image install
+ install("qemu", "ubuntu") # latest
+ install("ubuntu==0.4.0") # pin a version
"""
from __future__ import annotations
@@ -21,10 +24,10 @@ import argparse
import platform
import subprocess
import sys
-from importlib.metadata import entry_points
-from pathlib import Path
-# Short aliases → actual package names on PyPI
+from packaging.requirements import Requirement
+
+# Short aliases → actual project names on the simple index / PyPI.
ALIASES: dict[str, list[str]] = {
"qemu": ["quicksand-qemu"],
"ubuntu": ["quicksand-ubuntu"],
@@ -36,46 +39,62 @@ ALIASES: dict[str, list[str]] = {
"dev": ["quicksand-image-tools", "quicksand-overlay-scaffold", "quicksand-base-scaffold"],
}
-
-# ── Helpers ───────────────────────────────────────────────────────────
+# PEP 503 simple index served from the quicksand GitHub Pages site, listing
+# every wheel attached to every per-package GitHub release. Falling back to
+# PyPI keeps transitive dependencies (``pydantic``, ``anyio``, …) resolvable.
+QUICKSAND_INDEX_URL = "https://microsoft.github.io/quicksand/simple/"
+PYPI_INDEX_URL = "https://pypi.org/simple/"
-def _parse_extra(raw: str) -> tuple[str, str | None]:
- """Parse ``"name"`` or ``"name@version"`` into ``(name, version|None)``."""
- if "@" in raw:
- name, ver = raw.split("@", 1)
- return name, ver
- return raw, None
+# ── Helpers ───────────────────────────────────────────────────────────
-def _resolve_packages(name: str) -> list[str]:
- """Resolve a name to a list of package names.
+def _expand_requirement(raw: str) -> list[Requirement]:
+ """Parse *raw* as a PEP 508 requirement, expanding aliases on the name.
- Aliases (e.g. ``"ubuntu"``) expand to their mapped packages.
- All other names are treated as literal package names.
+ ``qemu==0.5.9`` → ``[Requirement("quicksand-qemu==0.5.9")]``.
+ ``dev`` → three Requirements (one per package in the alias).
"""
- return ALIASES.get(name, [name])
+ req = Requirement(raw)
+ mapped = ALIASES.get(req.name, [req.name])
+ if mapped == [req.name]:
+ return [req]
+ out: list[Requirement] = []
+ for pkg in mapped:
+ clone = Requirement(pkg)
+ clone.specifier = req.specifier
+ clone.extras = req.extras
+ clone.marker = req.marker
+ out.append(clone)
+ return out
+
+
+def _collect(raw_requirements: list[str] | tuple[str, ...]) -> list[Requirement]:
+ """Expand aliases and dedupe while preserving order."""
+ seen: set[str] = set()
+ out: list[Requirement] = []
+ for raw in raw_requirements:
+ for req in _expand_requirement(raw):
+ key = str(req)
+ if key not in seen:
+ seen.add(key)
+ out.append(req)
+ return out
# ── Public API ────────────────────────────────────────────────────────
-def install(*extras: str, arch: str | None = None) -> None:
- """Install quicksand extras from PyPI.
-
- Uses ``pip install`` so pip's resolver picks the version. Use
- ``"name@version"`` to pin a specific version.
+def install(*requirements: str) -> None:
+ """Install quicksand packages from the GitHub-hosted simple index.
- For image packages that ship as pure-Python stubs on PyPI (because the
- fat wheel exceeds the 100 MB limit), images are fetched from the
- matching GitHub release after pip install — pass ``arch`` to fetch
- a different architecture's images for use with ``quicksand run --arch``.
+ Uses ``pip install`` so pip's resolver picks versions. Pass standard
+ pip requirement strings (``quicksand-qemu==0.5.9``, ``ubuntu>=0.4``)
+ or the short aliases listed in :data:`ALIASES`.
Args:
- *extras: One or more extra/package names (e.g. ``"qemu"``, ``"ubuntu"``,
- ``"[email protected]"``, ``"quicksand-agent"``).
- arch: Target architecture for cross-arch image installs
- (``"amd64"`` / ``"arm64"``).
+ *requirements: PEP 508 requirements (e.g. ``"quicksand-qemu"``,
+ ``"qemu==0.5.9"``, ``"ubuntu>=0.4,<0.5"``).
Raises:
RuntimeError: If pip install fails.
@@ -85,24 +104,14 @@ def install(*extras: str, arch: str | None = None) -> None:
from quicksand import install
install("qemu", "ubuntu")
- install("[email protected]")
- install("ubuntu", arch="amd64") # cross-arch
+ install("alpine==0.4.0")
"""
- if not extras:
- raise ValueError("At least one extra name is required")
-
- packages: list[str] = []
- versions: dict[str, str | None] = {}
- for raw in extras:
- name, ver = _parse_extra(raw)
- for pkg in _resolve_packages(name):
- if pkg not in packages:
- packages.append(pkg)
- versions[pkg] = ver
-
- rc = _install_packages(packages, versions, arch=arch)
+ if not requirements:
+ raise ValueError("At least one requirement is required")
+
+ rc = _install_packages(_collect(requirements))
if rc != 0:
- raise RuntimeError(f"Failed to install packages: {packages}")
+ raise RuntimeError("pip install failed")
def register(subparsers: argparse._SubParsersAction) -> None:
@@ -110,68 +119,44 @@ def register(subparsers: argparse._SubParsersAction) -> None:
all_aliases = ", ".join(ALIASES.keys())
parser = subparsers.add_parser(
"install",
- help="Install packages from PyPI",
+ help="Install packages from the quicksand simple index",
)
parser.add_argument(
- "extras",
+ "requirements",
nargs="+",
- metavar="NAME[@VERSION]",
+ metavar="REQUIREMENT",
help=(
- f"Packages to install (use @version to pin, e.g. [email protected]). "
- f"Aliases: {all_aliases}. "
- "Other names are installed directly from PyPI."
+ "Pip requirements (e.g. quicksand-qemu, qemu==0.5.9, ubuntu>=0.4). "
+ f"Aliases: {all_aliases}."
),
)
- parser.add_argument(
- "--arch",
- default=None,
- help="Install images for a specific architecture (e.g. amd64, arm64). "
- "Fetches cross-platform images from GitHub for use with quicksand run --arch.",
- )
def cmd(args: argparse.Namespace) -> int:
- """Install packages from PyPI."""
- packages: list[str] = []
- versions: dict[str, str | None] = {}
- for raw in args.extras:
- name, ver = _parse_extra(raw)
- for pkg in _resolve_packages(name):
- if pkg not in packages:
- packages.append(pkg)
- versions[pkg] = ver
-
- return _install_packages(packages, versions, arch=args.arch)
+ """Install packages from the quicksand simple index."""
+ return _install_packages(_collect(args.requirements))
# ── Implementation ────────────────────────────────────────────────────
-def _install_packages(
- packages: list[str],
- versions: dict[str, str | None],
- arch: str | None = None,
-) -> int:
- """Run ``pip install`` then fetch any missing images from GitHub."""
- print(f"Installing: {', '.join(packages)}")
+def _install_packages(requirements: list[Requirement]) -> int:
+ """Run ``pip install`` against the quicksand simple index."""
+ print(f"Installing: {', '.join(str(r) for r in requirements)}")
print(f"Platform: {platform.system()} {platform.machine()}")
- if arch:
- print(f"Target image arch: {arch}")
print()
- rc = _run_pip_install(packages, versions)
+ rc = _run_pip_install(requirements)
if rc != 0:
print("\nError: pip install failed.")
return rc
- _ensure_images(packages, arch=arch)
-
- print(f"\nInstalled {len(packages)} package(s)")
+ print(f"\nInstalled {len(requirements)} package(s)")
return 0
-def _run_pip_install(packages: list[str], versions: dict[str, str | None]) -> int:
- """Invoke ``pip install`` and let pip resolve versions from PyPI."""
+def _run_pip_install(requirements: list[Requirement]) -> int:
+ """Invoke ``pip install`` and let pip resolve versions from our indexes."""
pip_args = [
sys.executable,
"-m",
@@ -180,50 +165,12 @@ def _run_pip_install(packages: list[str], versions: dict[str, str | None]) -> in
"--upgrade",
"--upgrade-strategy",
"only-if-needed",
+ "--index-url",
+ QUICKSAND_INDEX_URL,
+ "--extra-index-url",
+ PYPI_INDEX_URL,
]
- for pkg in packages:
- ver = versions.get(pkg)
- pip_args.append(f"{pkg}=={ver}" if ver else pkg)
+ pip_args.extend(str(r) for r in requirements)
print(f"Running: pip install {' '.join(pip_args[4:])}")
return subprocess.run(pip_args).returncode
-
-
-def _ensure_images(packages: list[str], arch: str | None = None) -> None:
- """Fetch images from GitHub for any image-provider package in *packages*.
-
- Skipped automatically for packages whose fat wheel was installable from
- PyPI (their ``manifest.json`` already exists). Forced when *arch* is set,
- to overlay images for a different architecture.
- """
- requested = set(packages)
- providers = _discover_image_providers(requested)
- if not providers:
- return
-
- from quicksand_core._auto_install import auto_install_images
-
- for pkg_name, images_dir in providers:
- manifest = images_dir / "manifest.json"
- if manifest.exists() and arch is None:
- continue # fat wheel already on disk for the host
- print(f"Fetching images for {pkg_name} (arch: {arch or 'host'})")
- auto_install_images(pkg_name, images_dir, arch=arch)
-
-
-def _discover_image_providers(requested: set[str]) -> list[tuple[str, Path]]:
- """Return ``(pkg_name, images_dir)`` for every ``quicksand.images`` entry
- point whose distribution is in *requested*."""
- found: list[tuple[str, Path]] = []
- for ep in entry_points(group="quicksand.images"):
- dist = ep.dist
- if dist is None or dist.name not in requested:
- continue
- try:
- provider = ep.load()
- except Exception:
- continue
- images_dir = getattr(provider, "images_dir", None)
- if isinstance(images_dir, Path):
- found.append((dist.name, images_dir))
- return found
diff --git a/packages/quicksand/quicksand/cli/uninstall.py b/packages/quicksand/quicksand/cli/uninstall.py
index add1c53..b02addf 100644
--- a/packages/quicksand/quicksand/cli/uninstall.py
+++ b/packages/quicksand/quicksand/cli/uninstall.py
@@ -14,18 +14,27 @@ import argparse
import subprocess
import sys
-from .install import ALIASES, _parse_extra, _resolve_packages
+from .install import ALIASES
-def uninstall(*extras: str) -> None:
+def _resolve(names: list[str] | tuple[str, ...]) -> list[str]:
+ """Expand aliases and dedupe."""
+ packages: list[str] = []
+ for raw in names:
+ for pkg in ALIASES.get(raw, [raw]):
+ if pkg not in packages:
+ packages.append(pkg)
+ return packages
+
+
+def uninstall(*names: str) -> None:
"""Uninstall quicksand extras.
Args:
- *extras: One or more extra/package names (e.g. ``"qemu"``, ``"ubuntu"``,
- ``"all"``).
+ *names: One or more extra/package names (e.g. ``"qemu"``, ``"ubuntu"``).
Raises:
- ValueError: If no extras are provided.
+ ValueError: If no names are provided.
RuntimeError: If pip uninstall fails.
Examples::
@@ -33,18 +42,11 @@ def uninstall(*extras: str) -> None:
from quicksand.cli.uninstall import uninstall
uninstall("qemu", "ubuntu")
- uninstall("all")
"""
- if not extras:
- raise ValueError("At least one extra name is required")
-
- packages: list[str] = []
- for raw in extras:
- name, _ver = _parse_extra(raw)
- for pkg in _resolve_packages(name):
- if pkg not in packages:
- packages.append(pkg)
+ if not names:
+ raise ValueError("At least one name is required")
+ packages = _resolve(names)
rc = _uninstall_packages(packages)
if rc != 0:
raise RuntimeError(f"Failed to uninstall packages: {packages}")
@@ -58,7 +60,7 @@ def register(subparsers: argparse._SubParsersAction) -> None:
help="Uninstall quicksand extras",
)
parser.add_argument(
- "extras",
+ "names",
nargs="+",
metavar="NAME",
help=(f"Packages to uninstall. Aliases: {all_aliases}."),
@@ -67,14 +69,7 @@ def register(subparsers: argparse._SubParsersAction) -> None:
def cmd(args: argparse.Namespace) -> int:
"""Uninstall quicksand extras."""
- packages: list[str] = []
- for raw in args.extras:
- name, _ver = _parse_extra(raw)
- for pkg in _resolve_packages(name):
- if pkg not in packages:
- packages.append(pkg)
-
- return _uninstall_packages(packages)
+ return _uninstall_packages(_resolve(args.names))
def _uninstall_packages(packages: list[str]) -> int:
diff --git a/scripts/ci/build_simple_index.py b/scripts/ci/build_simple_index.py
new file mode 100644
index 0000000..05f8bde
--- /dev/null
+++ b/scripts/ci/build_simple_index.py
@@ -0,0 +1,153 @@
+"""Generate a PEP 503 simple repository index from GitHub Releases.
+
+Walks every release on the repo, groups wheels by their package name (parsed
+from the per-package release tag, e.g. ``quicksand-qemu/v0.5.9``), and emits
+static HTML pages that pip can consume::
+
+ <root>/simple/index.html ← lists every package
+ <root>/simple/<package>/index.html ← lists every wheel for the package
+
+Run inside CI before the Pages artifact is uploaded so the index ships with
+the docs site:
+
+ python scripts/ci/build_simple_index.py docs/.vitepress/dist
+
+Environment:
+ GH_TOKEN: optional; raises GitHub API rate limits.
+ GITHUB_REPOSITORY: ``owner/name`` (defaults to ``microsoft/quicksand``).
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import re
+import sys
+import urllib.request
+from collections import defaultdict
+from collections.abc import Iterator
+from html import escape
+from pathlib import Path
+
+REPO = os.environ.get("GITHUB_REPOSITORY", "microsoft/quicksand")
+API_ROOT = f"https://api.github.com/repos/{REPO}"
+
+# Per-package release tags look like ``<pkg>/v<version>``. ``-base`` / ``-dev``
+# suffixes denote internal markers, not user-installable releases.
+_TAG_RE = re.compile(r"^(?P<pkg>[a-zA-Z0-9._-]+)/v(?P<version>.+?)(?:-base|-dev)?$")
+
+
+def _api(path: str) -> urllib.request.Request:
+ req = urllib.request.Request(path)
+ req.add_header("Accept", "application/vnd.github+json")
+ token = os.environ.get("GH_TOKEN") or os.environ.get("GITHUB_TOKEN")
+ if token:
+ req.add_header("Authorization", f"Bearer {token}")
+ return req
+
+
+def _paginate(path: str) -> Iterator[dict]:
+ page = 1
+ while True:
+ url = f"{path}?per_page=100&page={page}"
+ with urllib.request.urlopen(_api(url)) as resp:
+ batch = json.load(resp)
+ if not batch:
+ return
+ yield from batch
+ if len(batch) < 100:
+ return
+ page += 1
+
+
+def _normalize(name: str) -> str:
+ """PEP 503 name normalization: lowercase + runs of ``-_.`` collapsed to ``-``."""
+ return re.sub(r"[-_.]+", "-", name).lower()
+
+
+def collect_releases() -> dict[str, list[dict]]:
+ """Return ``{normalized_package_name: [wheel_asset, ...]}``.
+
+ Each asset dict has ``filename`` and ``url`` keys.
+ """
+ by_pkg: dict[str, list[dict]] = defaultdict(list)
+ for release in _paginate(f"{API_ROOT}/releases"):
+ match = _TAG_RE.match(release["tag_name"])
+ if not match:
+ continue
+ if release["tag_name"].endswith(("-base", "-dev")):
+ continue
+ pkg = _normalize(match.group("pkg"))
+ for asset in release.get("assets", []):
+ name = asset["name"]
+ if not name.endswith(".whl"):
+ continue
+ by_pkg[pkg].append(
+ {
+ "filename": name,
+ "url": asset["browser_download_url"],
+ }
+ )
+ return by_pkg
+
+
+def render_package_page(package: str, assets: list[dict]) -> str:
+ """Render the per-package PEP 503 page."""
+ # Sort by filename for stable output.
+ assets = sorted(assets, key=lambda a: a["filename"])
+ lines = [
+ "<!DOCTYPE html>",
+ '<html><head><meta name="pypi:repository-version" content="1.0">',
+ f"<title>Links for {escape(package)}</title>",
+ "</head><body>",
+ f"<h1>Links for {escape(package)}</h1>",
+ ]
+ for asset in assets:
+ href = escape(asset["url"], quote=True)
+ text = escape(asset["filename"])
+ lines.append(f'<a href="{href}">{text}</a><br>')
+ lines.append("</body></html>")
+ return "\n".join(lines)
+
+
+def render_root_page(packages: list[str]) -> str:
+ """Render ``simple/index.html`` listing every package."""
+ packages = sorted(packages)
+ lines = [
+ "<!DOCTYPE html>",
+ '<html><head><meta name="pypi:repository-version" content="1.0">',
+ "<title>Simple Index</title>",
+ "</head><body>",
+ "<h1>Simple Index</h1>",
+ ]
+ for pkg in packages:
+ lines.append(f'<a href="{escape(pkg, quote=True)}/">{escape(pkg)}</a><br>')
+ lines.append("</body></html>")
+ return "\n".join(lines)
+
+
+def main() -> int:
+ if len(sys.argv) != 2:
+ print(__doc__, file=sys.stderr)
+ return 2
+ out_root = Path(sys.argv[1]) / "simple"
+ out_root.mkdir(parents=True, exist_ok=True)
+
+ by_pkg = collect_releases()
+ if not by_pkg:
+ print("No wheel assets found across GitHub releases.", file=sys.stderr)
+ return 1
+
+ for pkg, assets in by_pkg.items():
+ pkg_dir = out_root / pkg
+ pkg_dir.mkdir(parents=True, exist_ok=True)
+ (pkg_dir / "index.html").write_text(render_package_page(pkg, assets))
+ print(f" {pkg}: {len(assets)} wheels")
+
+ (out_root / "index.html").write_text(render_root_page(list(by_pkg)))
+ print(f"\nGenerated index for {len(by_pkg)} package(s) at {out_root}")
+ return 0
+
+
+if __name__ == "__main__":
+ sys.exit(main())
diff --git a/tests/unit/test_cli_install.py b/tests/unit/test_cli_install.py
index fea9395..4091952 100644
--- a/tests/unit/test_cli_install.py
+++ b/tests/unit/test_cli_install.py
@@ -3,48 +3,61 @@
from __future__ import annotations
import sys
-from dataclasses import dataclass
-from pathlib import Path
from unittest.mock import patch
import pytest
-from quicksand.cli import install as install_mod
+from packaging.requirements import Requirement
from quicksand.cli.install import (
- _ensure_images,
+ _collect,
+ _expand_requirement,
_install_packages,
- _parse_extra,
- _resolve_packages,
_run_pip_install,
install,
)
-class TestParseExtra:
- def test_bare_name(self):
- assert _parse_extra("ubuntu") == ("ubuntu", None)
+class TestExpandRequirement:
+ def test_bare_alias(self):
+ out = _expand_requirement("ubuntu")
+ assert [str(r) for r in out] == ["quicksand-ubuntu"]
- def test_pinned_version(self):
- assert _parse_extra("[email protected]") == ("ubuntu", "0.4.0")
+ def test_alias_with_specifier(self):
+ out = _expand_requirement("qemu==0.5.9")
+ assert [str(r) for r in out] == ["quicksand-qemu==0.5.9"]
- def test_first_at_only(self):
- # Versions can't contain "@", so split once.
- assert _parse_extra("[email protected]@beta") == ("pkg", "1.0@beta")
+ def test_range_specifier(self):
+ out = _expand_requirement("ubuntu>=0.4,<0.5")
+ assert len(out) == 1
+ assert out[0].name == "quicksand-ubuntu"
+ assert "0.4" in str(out[0].specifier) and "0.5" in str(out[0].specifier)
-
-class TestResolvePackages:
- def test_alias_expands(self):
- assert _resolve_packages("ubuntu") == ["quicksand-ubuntu"]
+ def test_literal_pypi_name_unchanged(self):
+ out = _expand_requirement("quicksand-qemu==0.5.9")
+ assert [str(r) for r in out] == ["quicksand-qemu==0.5.9"]
def test_dev_alias_expands_to_multiple(self):
- assert _resolve_packages("dev") == [
+ out = _expand_requirement("dev")
+ assert {r.name for r in out} == {
"quicksand-image-tools",
"quicksand-overlay-scaffold",
"quicksand-base-scaffold",
- ]
+ }
+
+ def test_dev_alias_propagates_specifier(self):
+ out = _expand_requirement("dev>=0.3")
+ for r in out:
+ assert ">=0.3" in str(r.specifier)
+
- def test_unknown_is_passthrough(self):
- # Treated as a literal PyPI name — pip will resolve or fail.
- assert _resolve_packages("some-random-pkg") == ["some-random-pkg"]
+class TestCollect:
+ def test_dedupes_after_alias_expansion(self):
+ # ``qemu`` and ``quicksand-qemu`` resolve to the same requirement.
+ out = _collect(["qemu", "quicksand-qemu"])
+ assert [str(r) for r in out] == ["quicksand-qemu"]
+
+ def test_preserves_order(self):
+ out = _collect(["ubuntu", "qemu"])
+ assert [r.name for r in out] == ["quicksand-ubuntu", "quicksand-qemu"]
class _DummyCompleted:
@@ -60,114 +73,33 @@ class TestRunPipInstall:
captured["argv"] = argv
return _DummyCompleted(0)
+ reqs = [Requirement("quicksand-qemu"), Requirement("quicksand-cua")]
with patch("quicksand.cli.install.subprocess.run", side_effect=fake_run):
- rc = _run_pip_install(["quicksand-qemu", "quicksand-cua"], {})
+ rc = _run_pip_install(reqs)
assert rc == 0
- assert captured["argv"][:7] == [
- sys.executable,
- "-m",
- "pip",
- "install",
- "--upgrade",
- "--upgrade-strategy",
- "only-if-needed",
- ]
- # Package args appear unpinned and in order.
- assert captured["argv"][7:] == ["quicksand-qemu", "quicksand-cua"]
-
- def test_applies_version_pins(self):
+ argv = captured["argv"]
+ assert argv[:4] == [sys.executable, "-m", "pip", "install"]
+ assert "--upgrade" in argv
+ idx = argv.index("--index-url")
+ assert argv[idx + 1] == "https://microsoft.github.io/quicksand/simple/"
+ eidx = argv.index("--extra-index-url")
+ assert argv[eidx + 1] == "https://pypi.org/simple/"
+ assert argv[-2:] == ["quicksand-qemu", "quicksand-cua"]
+
+ def test_forwards_specifiers(self):
captured: dict = {}
def fake_run(argv, *_args, **_kwargs):
captured["argv"] = argv
return _DummyCompleted(0)
+ reqs = [Requirement("quicksand-qemu==0.5.9"), Requirement("quicksand-ubuntu>=0.4")]
with patch("quicksand.cli.install.subprocess.run", side_effect=fake_run):
- _run_pip_install(
- ["quicksand-qemu", "quicksand-ubuntu"],
- {"quicksand-qemu": "0.5.9", "quicksand-ubuntu": None},
- )
+ _run_pip_install(reqs)
assert "quicksand-qemu==0.5.9" in captured["argv"]
- assert "quicksand-ubuntu" in captured["argv"]
- assert "quicksand-ubuntu==None" not in captured["argv"]
-
-
-@dataclass
-class _FakeDist:
- name: str
-
-
-class _FakeEntryPoint:
- def __init__(self, dist_name: str, provider):
- self.dist = _FakeDist(dist_name)
- self._provider = provider
-
- def load(self):
- return self._provider
-
-
-class _FakeProvider:
- def __init__(self, images_dir: Path) -> None:
- self.images_dir = images_dir
-
-
-class TestEnsureImages:
- def test_skips_packages_not_in_request(self, tmp_path: Path):
- images = tmp_path / "ubuntu-images"
- images.mkdir()
- eps = [_FakeEntryPoint("quicksand-ubuntu", _FakeProvider(images))]
-
- with (
- patch("quicksand.cli.install.entry_points", return_value=eps),
- patch("quicksand_core._auto_install.auto_install_images") as auto,
- ):
- _ensure_images(packages=["quicksand-qemu"], arch=None)
-
- auto.assert_not_called()
-
- def test_skips_when_manifest_present_and_no_arch(self, tmp_path: Path):
- images = tmp_path / "ubuntu-images"
- images.mkdir()
- (images / "manifest.json").write_text("{}")
- eps = [_FakeEntryPoint("quicksand-ubuntu", _FakeProvider(images))]
-
- with (
- patch("quicksand.cli.install.entry_points", return_value=eps),
- patch("quicksand_core._auto_install.auto_install_images") as auto,
- ):
- _ensure_images(packages=["quicksand-ubuntu"], arch=None)
-
- auto.assert_not_called()
-
- def test_fetches_when_manifest_missing(self, tmp_path: Path):
- images = tmp_path / "ubuntu-images"
- images.mkdir() # empty — pure-wheel install case
- eps = [_FakeEntryPoint("quicksand-ubuntu", _FakeProvider(images))]
-
- with (
- patch("quicksand.cli.install.entry_points", return_value=eps),
- patch("quicksand_core._auto_install.auto_install_images") as auto,
- ):
- _ensure_images(packages=["quicksand-ubuntu"], arch=None)
-
- auto.assert_called_once_with("quicksand-ubuntu", images, arch=None)
-
- def test_fetches_for_cross_arch_even_with_manifest(self, tmp_path: Path):
- # --arch forces a refetch so we can overlay images for a different arch.
- images = tmp_path / "ubuntu-images"
- images.mkdir()
- (images / "manifest.json").write_text("{}")
- eps = [_FakeEntryPoint("quicksand-ubuntu", _FakeProvider(images))]
-
- with (
- patch("quicksand.cli.install.entry_points", return_value=eps),
- patch("quicksand_core._auto_install.auto_install_images") as auto,
- ):
- _ensure_images(packages=["quicksand-ubuntu"], arch="amd64")
-
- auto.assert_called_once_with("quicksand-ubuntu", images, arch="amd64")
+ assert "quicksand-ubuntu>=0.4" in captured["argv"]
class TestInstall:
@@ -177,36 +109,24 @@ class TestInstall:
"quicksand.cli.install.subprocess.run",
return_value=_DummyCompleted(1),
),
- pytest.raises(RuntimeError, match="Failed to install"),
+ pytest.raises(RuntimeError, match="pip install failed"),
):
install("qemu")
- def test_no_extras_raises(self):
+ def test_no_requirements_raises(self):
with pytest.raises(ValueError):
install()
- def test_install_packages_skips_image_fetch_on_pip_failure(self):
- with (
- patch(
- "quicksand.cli.install.subprocess.run",
- return_value=_DummyCompleted(2),
- ),
- patch.object(install_mod, "_ensure_images") as ensure,
+ def test_install_packages_returns_pip_exit_code(self):
+ with patch(
+ "quicksand.cli.install.subprocess.run",
+ return_value=_DummyCompleted(2),
):
- rc = _install_packages(["quicksand-ubuntu"], {}, arch=None)
+ assert _install_packages([Requirement("quicksand-ubuntu")]) == 2
- assert rc == 2
- ensure.assert_not_called()
-
- def test_install_packages_calls_image_fetch_on_success(self):
- with (
- patch(
- "quicksand.cli.install.subprocess.run",
- return_value=_DummyCompleted(0),
- ),
- patch.object(install_mod, "_ensure_images") as ensure,
+ def test_install_packages_succeeds(self):
+ with patch(
+ "quicksand.cli.install.subprocess.run",
+ return_value=_DummyCompleted(0),
):
- rc = _install_packages(["quicksand-ubuntu"], {"quicksand-ubuntu": None}, arch="amd64")
-
- assert rc == 0
- ensure.assert_called_once_with(["quicksand-ubuntu"], arch="amd64")
+ assert _install_packages([Requirement("quicksand-ubuntu")]) == 0