sciencehub 0.1.0__tar.gz

sciencehub-0.1.0/.gitignore

@@ -0,0 +1,5 @@
+.venv/
+dist/
+uv.lock
+__pycache__/
+.pytest_cache/

sciencehub-0.1.0/PKG-INFO

@@ -0,0 +1,120 @@
+Metadata-Version: 2.5
+Name: sciencehub
+Version: 0.1.0
+Summary: Load the functions and data of ScienceHub projects in Python.
+Project-URL: Homepage, https://sciencehub.sh
+Project-URL: Documentation, https://sciencehub.sh/docs/python
+Author: ScienceHub
+License-Expression: Apache-2.0
+Keywords: datasets,marimo,notebooks,reproducibility,science
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Science/Research
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Scientific/Engineering
+Requires-Python: >=3.10
+Requires-Dist: marimo>=0.13
+Description-Content-Type: text/markdown
+
+# sciencehub
+
+Use the functions and data of [ScienceHub](https://sciencehub.sh) projects
+from Python.
+
+A ScienceHub project is a [marimo](https://marimo.io) notebook. Every function
+its author wrote as a reusable function (`@app.function`) can be called from
+your own code, and every file kept beside the notebook can be downloaded. Each
+project page lists them under **Functions** and **Files**.
+
+```sh
+pip install sciencehub
+```
+
+## Load a project
+
+```python
+import sciencehub as sh
+
+ocean = sh.load("ada/ocean-heat")
+ocean
+```
+
+```
+ada/ocean-heat · Ocean heat content
+version 7Q2M4XKD, the current one · https://sciencehub.sh/ada/ocean-heat
+
+Functions
+  heat_content(depth_m: float = 700) -> float
+      Heat content above a depth, in joules per square metre.
+Files
+  data/argo.csv  14.2 kB
+
+Pin this version: sh.load("ada/ocean-heat", version="01K7…7Q2M4XKD")
+```
+
+`sh.load` takes the name from the project's address: `"owner/project"` for
+its main notebook, `"owner/project/notebook"` for another one, or the address
+itself.
+
+## Call a function
+
+```python
+help(ocean.heat_content)
+ocean.heat_content(depth_m=700)
+```
+
+`help()`, `inspect.signature`, Jupyter's `?` and editor completion show the
+signature and docstring the author wrote, before anything is downloaded.
+
+The first call downloads the notebook and its files into a cache, imports the
+notebook, and calls the function on your computer. The function runs with the
+notebook's folder as its working directory, so a function that opens
+`data/argo.csv` finds it, as it does on ScienceHub.
+
+The notebook's own dependencies have to be installed in your Python. If one is
+missing, the error names it; `ocean.install()` installs everything the
+notebook declares, with pip or uv.
+
+Calling a function runs its author's code, as installing their package would.
+
+## Read a file
+
+```python
+path = ocean.path("data/argo.csv")   # downloaded once, checked, then read from disk
+with ocean.open("data/argo.csv") as handle:
+    ...
+ocean.download()                     # the notebook and every file, in one folder
+```
+
+Files of public projects also have an address any program can read:
+
+```python
+import pandas as pd
+
+df = pd.read_csv("https://sciencehub.sh/ada/ocean-heat/raw/data/argo.csv")
+```
+
+## Pin a version
+
+A load is always one version, and `ocean.version` says which. Pin it so your
+results do not change when the author saves a new one:
+
+```python
+sh.load("ada/ocean-heat", version="01K7…")   # one saved version
+sh.load("ada/ocean-heat", release=2)         # what DOI release 2 names, files included
+```
+
+## Private projects
+
+Make a personal access token with the read scope at
+[sciencehub.sh/settings/tokens](https://sciencehub.sh/settings/tokens) and
+set it as `SCIENCEHUB_TOKEN`, or pass `token=` to `sh.load`.
+
+## Settings
+
+| Variable           | What it does                                         |
+| ------------------ | ---------------------------------------------------- |
+| `SCIENCEHUB_TOKEN` | A personal access token, for private projects        |
+| `SCIENCEHUB_URL`   | Another ScienceHub site than `https://sciencehub.sh` |
+| `SCIENCEHUB_CACHE` | Where versions are kept; the user cache by default   |
+
+Apache 2.0.

sciencehub-0.1.0/README.md

@@ -0,0 +1,103 @@
+# sciencehub
+
+Use the functions and data of [ScienceHub](https://sciencehub.sh) projects
+from Python.
+
+A ScienceHub project is a [marimo](https://marimo.io) notebook. Every function
+its author wrote as a reusable function (`@app.function`) can be called from
+your own code, and every file kept beside the notebook can be downloaded. Each
+project page lists them under **Functions** and **Files**.
+
+```sh
+pip install sciencehub
+```
+
+## Load a project
+
+```python
+import sciencehub as sh
+
+ocean = sh.load("ada/ocean-heat")
+ocean
+```
+
+```
+ada/ocean-heat · Ocean heat content
+version 7Q2M4XKD, the current one · https://sciencehub.sh/ada/ocean-heat
+
+Functions
+  heat_content(depth_m: float = 700) -> float
+      Heat content above a depth, in joules per square metre.
+Files
+  data/argo.csv  14.2 kB
+
+Pin this version: sh.load("ada/ocean-heat", version="01K7…7Q2M4XKD")
+```
+
+`sh.load` takes the name from the project's address: `"owner/project"` for
+its main notebook, `"owner/project/notebook"` for another one, or the address
+itself.
+
+## Call a function
+
+```python
+help(ocean.heat_content)
+ocean.heat_content(depth_m=700)
+```
+
+`help()`, `inspect.signature`, Jupyter's `?` and editor completion show the
+signature and docstring the author wrote, before anything is downloaded.
+
+The first call downloads the notebook and its files into a cache, imports the
+notebook, and calls the function on your computer. The function runs with the
+notebook's folder as its working directory, so a function that opens
+`data/argo.csv` finds it, as it does on ScienceHub.
+
+The notebook's own dependencies have to be installed in your Python. If one is
+missing, the error names it; `ocean.install()` installs everything the
+notebook declares, with pip or uv.
+
+Calling a function runs its author's code, as installing their package would.
+
+## Read a file
+
+```python
+path = ocean.path("data/argo.csv")   # downloaded once, checked, then read from disk
+with ocean.open("data/argo.csv") as handle:
+    ...
+ocean.download()                     # the notebook and every file, in one folder
+```
+
+Files of public projects also have an address any program can read:
+
+```python
+import pandas as pd
+
+df = pd.read_csv("https://sciencehub.sh/ada/ocean-heat/raw/data/argo.csv")
+```
+
+## Pin a version
+
+A load is always one version, and `ocean.version` says which. Pin it so your
+results do not change when the author saves a new one:
+
+```python
+sh.load("ada/ocean-heat", version="01K7…")   # one saved version
+sh.load("ada/ocean-heat", release=2)         # what DOI release 2 names, files included
+```
+
+## Private projects
+
+Make a personal access token with the read scope at
+[sciencehub.sh/settings/tokens](https://sciencehub.sh/settings/tokens) and
+set it as `SCIENCEHUB_TOKEN`, or pass `token=` to `sh.load`.
+
+## Settings
+
+| Variable           | What it does                                         |
+| ------------------ | ---------------------------------------------------- |
+| `SCIENCEHUB_TOKEN` | A personal access token, for private projects        |
+| `SCIENCEHUB_URL`   | Another ScienceHub site than `https://sciencehub.sh` |
+| `SCIENCEHUB_CACHE` | Where versions are kept; the user cache by default   |
+
+Apache 2.0.

sciencehub-0.1.0/pyproject.toml

@@ -0,0 +1,34 @@
+[project]
+name = "sciencehub"
+version = "0.1.0"
+description = "Load the functions and data of ScienceHub projects in Python."
+readme = "README.md"
+license = "Apache-2.0"
+requires-python = ">=3.10"
+authors = [{ name = "ScienceHub" }]
+keywords = ["science", "notebooks", "marimo", "reproducibility", "datasets"]
+classifiers = [
+	"Development Status :: 4 - Beta",
+	"Intended Audience :: Science/Research",
+	"Programming Language :: Python :: 3",
+	"Topic :: Scientific/Engineering",
+]
+# A notebook imports marimo itself, so loading its functions needs it.
+dependencies = ["marimo>=0.13"]
+
+[project.urls]
+Homepage = "https://sciencehub.sh"
+Documentation = "https://sciencehub.sh/docs/python"
+
+[build-system]
+requires = ["hatchling>=1.25"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/sciencehub"]
+
+[dependency-groups]
+dev = ["pytest>=8"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]

sciencehub-0.1.0/src/sciencehub/__init__.py

@@ -0,0 +1,28 @@
+"""Use the functions and data of ScienceHub projects from Python.
+
+    import sciencehub as sh
+
+    ocean = sh.load("ada/ocean-heat")      # the current version; print it to see what it offers
+    help(ocean.heat_content)               # the author's docstring and signature
+    ocean.heat_content(depth_m=700)        # runs on this computer
+    ocean.path("data/argo.csv")            # downloaded once, then read from disk
+    sh.load("ada/ocean-heat", release=2)   # exactly what DOI release 2 names
+
+Loading a project runs its author's code when a function is first called, as
+installing their package would.
+"""
+
+from ._http import AccessError, NotFoundError, ScienceHubError
+from ._project import File, MissingDependencyError, Project, Version, load
+
+__all__ = [
+    "AccessError",
+    "File",
+    "MissingDependencyError",
+    "NotFoundError",
+    "Project",
+    "ScienceHubError",
+    "Version",
+    "load",
+]
+__version__ = "0.1.0"

sciencehub-0.1.0/src/sciencehub/_http.py

@@ -0,0 +1,82 @@
+"""Requests to a ScienceHub site, with the standard library only."""
+
+from __future__ import annotations
+
+import json
+import os
+import urllib.error
+import urllib.request
+from typing import Any
+
+DEFAULT_URL = "https://sciencehub.sh"
+USER_AGENT = "sciencehub-python/0.1.0"
+
+
+class ScienceHubError(Exception):
+    """A request to ScienceHub did not succeed."""
+
+
+class NotFoundError(ScienceHubError, LookupError):
+    """The project, notebook, version or file does not exist, or the token cannot read it."""
+
+
+class AccessError(ScienceHubError, PermissionError):
+    """The site refused the token, or the request needs one."""
+
+
+def base_url(explicit: str | None = None) -> str:
+    return (explicit or os.environ.get("SCIENCEHUB_URL") or DEFAULT_URL).rstrip("/")
+
+
+def _token(explicit: str | None) -> str | None:
+    return explicit or os.environ.get("SCIENCEHUB_TOKEN") or None
+
+
+def _request(url: str, token: str | None) -> urllib.request.Request:
+    headers = {"User-Agent": USER_AGENT, "Accept": "application/json, */*"}
+    if token:
+        headers["Authorization"] = f"Bearer {token}"
+    return urllib.request.Request(url, headers=headers)
+
+
+def _explain(error: urllib.error.HTTPError, url: str) -> ScienceHubError:
+    message = ""
+    try:
+        body = json.loads(error.read().decode("utf-8"))
+        message = body.get("error", {}).get("message") or body.get("error_description") or ""
+    except (ValueError, AttributeError):
+        pass
+    if error.code == 404:
+        return NotFoundError(message or f"Not found: {url}")
+    if error.code in (401, 403):
+        hint = (
+            "Set SCIENCEHUB_TOKEN to a personal access token with the read scope, "
+            "made at https://sciencehub.sh/settings/tokens."
+        )
+        return AccessError(f"{message} {hint}".strip())
+    if error.code == 429:
+        return ScienceHubError(message or "Too many requests. Wait a minute and try again.")
+    return ScienceHubError(message or f"{error.code} {error.reason} from {url}")
+
+
+def get_json(url: str, token: str | None = None) -> dict[str, Any]:
+    try:
+        with urllib.request.urlopen(_request(url, _token(token)), timeout=30) as response:
+            body = json.loads(response.read().decode("utf-8"))
+    except urllib.error.HTTPError as error:
+        raise _explain(error, url) from None
+    except urllib.error.URLError as error:
+        raise ScienceHubError(f"Could not reach {url}: {error.reason}") from None
+    if not body.get("success"):
+        raise ScienceHubError(body.get("error", {}).get("message", f"No answer from {url}"))
+    return body["data"]
+
+
+def get_bytes(url: str, token: str | None = None) -> bytes:
+    try:
+        with urllib.request.urlopen(_request(url, _token(token)), timeout=300) as response:
+            return response.read()
+    except urllib.error.HTTPError as error:
+        raise _explain(error, url) from None
+    except urllib.error.URLError as error:
+        raise ScienceHubError(f"Could not reach {url}: {error.reason}") from None

sciencehub-0.1.0/src/sciencehub/_project.py

@@ -0,0 +1,456 @@
+"""A version of a ScienceHub notebook, loaded for use from Python."""
+
+from __future__ import annotations
+
+import contextlib
+import difflib
+import hashlib
+import html
+import importlib.util
+import inspect
+import json
+import os
+import re
+import shutil
+import subprocess
+import sys
+import threading
+from collections.abc import Callable
+from dataclasses import dataclass
+from pathlib import Path
+from types import ModuleType
+from typing import Any
+from urllib.parse import quote, urlsplit
+
+from . import _http
+
+_CHDIR_LOCK = threading.RLock()
+
+
+class MissingDependencyError(ImportError):
+    """The notebook imports a package that is not installed in this Python."""
+
+
+@dataclass(frozen=True)
+class File:
+    """A file kept beside the notebook, at the version that was loaded."""
+
+    path: str
+    size: int
+    sha256: str
+    url: str
+
+    def __repr__(self) -> str:
+        return f"<File {self.path} {_size(self.size)}>"
+
+
+@dataclass(frozen=True)
+class Version:
+    id: str
+    saved_at: str | None
+    current: bool
+    release: int | None
+    doi: str | None
+    url: str
+
+
+def _size(count: int) -> str:
+    value = float(count)
+    for unit in ("B", "kB", "MB", "GB"):
+        if value < 1000 or unit == "GB":
+            return f"{int(value)} {unit}" if unit == "B" else f"{value:.1f} {unit}"
+        value /= 1000
+    return f"{count} B"
+
+
+def _cache_root() -> Path:
+    explicit = os.environ.get("SCIENCEHUB_CACHE")
+    if explicit:
+        return Path(explicit)
+    if sys.platform == "darwin":
+        return Path.home() / "Library" / "Caches" / "sciencehub"
+    if sys.platform == "win32":
+        return Path(os.environ.get("LOCALAPPDATA", Path.home())) / "sciencehub" / "cache"
+    return Path(os.environ.get("XDG_CACHE_HOME", Path.home() / ".cache")) / "sciencehub"
+
+
+class _Written:
+    """Source text shown as written, so `help()` prints `g: float = G`, not `g: 'float' = G`."""
+
+    def __init__(self, source: str) -> None:
+        self.source = source
+
+    def __repr__(self) -> str:
+        return self.source
+
+
+def _signature(parameters: list[dict[str, Any]], returns: str | None) -> inspect.Signature:
+    kinds = {
+        "positional-only": inspect.Parameter.POSITIONAL_ONLY,
+        "positional-or-keyword": inspect.Parameter.POSITIONAL_OR_KEYWORD,
+        "keyword-only": inspect.Parameter.KEYWORD_ONLY,
+        "var-positional": inspect.Parameter.VAR_POSITIONAL,
+        "var-keyword": inspect.Parameter.VAR_KEYWORD,
+    }
+    built = [
+        inspect.Parameter(
+            parameter["name"],
+            kinds[parameter["kind"]],
+            default=inspect.Parameter.empty
+            if parameter.get("default") is None
+            else _Written(parameter["default"]),
+            annotation=inspect.Parameter.empty
+            if parameter.get("annotation") is None
+            else _Written(parameter["annotation"]),
+        )
+        for parameter in parameters
+    ]
+    try:
+        return inspect.Signature(
+            built,
+            return_annotation=inspect.Signature.empty if returns is None else _Written(returns),
+        )
+    except ValueError:
+        return inspect.Signature()
+
+
+def _parse_ref(ref: str) -> tuple[str, str, str | None]:
+    """`owner/project`, `owner/project/notebook`, or a page address on the site."""
+    path = urlsplit(ref.strip()).path if "://" in ref else ref.strip()
+    segments = [segment for segment in path.strip("/").split("/") if segment]
+    if len(segments) >= 4 and segments[2] == "notebooks":
+        return segments[0], segments[1], segments[3]
+    if len(segments) == 2:
+        return segments[0], segments[1], None
+    if len(segments) == 3:
+        return segments[0], segments[1], segments[2]
+    raise ValueError(
+        f'"{ref}" does not name a project. Write it as "owner/project" '
+        'or "owner/project/notebook", as in the address of its page.'
+    )
+
+
+class Project:
+    """One version of a notebook on ScienceHub: its functions and its files.
+
+    Made by :func:`sciencehub.load`. Functions are attributes:
+    ``project.heat_content(depth_m=700)`` imports the notebook on this
+    computer and calls its function. ``project.path("data/argo.csv")``
+    downloads a file once and returns where it is.
+    """
+
+    def __init__(self, data: dict[str, Any], *, token: str | None = None) -> None:
+        self._data = data
+        self._token = token
+        self._module: ModuleType | None = None
+        self.owner: str = data["project"]["owner"]
+        self.slug: str = data["project"]["slug"]
+        self.name: str = data["project"]["name"]
+        self.description: str = data["project"]["description"]
+        self.url: str = data["notebook"]["url"]
+        self.notebook: str = data["notebook"]["slug"]
+        self.notebooks: list[str] = [entry["slug"] for entry in data["notebooks"]]
+        release = data["version"].get("release")
+        self.version = Version(
+            id=data["version"]["id"],
+            saved_at=data["version"].get("saved_at"),
+            current=bool(data["version"].get("current")),
+            release=release["number"] if release else None,
+            doi=release["doi"] if release else None,
+            url=data["version"]["url"],
+        )
+        self.dependencies: list[str] = list(data["environment"].get("dependencies") or [])
+        self.files: list[File] = [
+            File(path=f["path"], size=f["size"], sha256=f["sha256"], url=f["url"])
+            for f in data["files"]
+        ]
+        self.functions: dict[str, Callable[..., Any]] = {}
+        self._classes: dict[str, dict[str, Any]] = {}
+        for entry in data["functions"]:
+            if entry["kind"] == "class":
+                self._classes[entry["name"]] = entry
+            else:
+                self.functions[entry["name"]] = self._proxy(entry)
+
+    @property
+    def ref(self) -> str:
+        """``owner/project``, with the notebook when it is not the main one."""
+        main = self._data["notebook"].get("main", True)
+        base = f"{self.owner}/{self.slug}"
+        return base if main else f"{base}/{self.notebook}"
+
+    @property
+    def directory(self) -> Path:
+        """Where this version's source and files are kept on this computer."""
+        host = urlsplit(self.url).netloc.replace(":", "_")
+        return _cache_root() / host / self.owner / self.slug / self.notebook / self.version.id
+
+    # Functions -----------------------------------------------------------
+
+    def _proxy(self, entry: dict[str, Any]) -> Callable[..., Any]:
+        name = entry["name"]
+        project = self
+
+        if entry.get("async"):
+
+            async def call(*args: Any, **kwargs: Any) -> Any:
+                function = project._function(name)
+                with project._inside():
+                    return await function(*args, **kwargs)
+        else:
+
+            def call(*args: Any, **kwargs: Any) -> Any:
+                function = project._function(name)
+                with project._inside():
+                    return function(*args, **kwargs)
+
+        call.__name__ = name
+        call.__qualname__ = name
+        call.__module__ = self.ref
+        call.__doc__ = entry.get("doc") or None
+        call.__signature__ = _signature(entry["parameters"], entry.get("returns"))  # type: ignore[attr-defined]
+        call.project = self  # type: ignore[attr-defined]
+        call.url = f"{self.url}/functions#{name}"  # type: ignore[attr-defined]
+        return call
+
+    def _function(self, name: str) -> Callable[..., Any]:
+        function = getattr(self.module(), name, None)
+        if function is None:
+            raise AttributeError(f"{self.ref} at version {self.version.id} has no function {name}.")
+        return function
+
+    @contextlib.contextmanager
+    def _inside(self):
+        """Run with the notebook's folder as the working directory, as it runs on ScienceHub."""
+        with _CHDIR_LOCK:
+            previous = os.getcwd()
+            os.chdir(self.directory)
+            try:
+                yield
+            finally:
+                os.chdir(previous)
+
+    def __getattr__(self, name: str) -> Any:
+        if name.startswith("_"):
+            raise AttributeError(name)
+        functions = self.__dict__.get("functions", {})
+        if name in functions:
+            return functions[name]
+        if name in self.__dict__.get("_classes", {}):
+            return getattr(self.module(), name)
+        known = [*functions, *self.__dict__.get("_classes", {})]
+        close = difflib.get_close_matches(name, known, n=1)
+        hint = f" Did you mean {close[0]}?" if close else ""
+        offered = ", ".join(known) if known else "none"
+        raise AttributeError(
+            f"{self.ref} has no function {name}.{hint} Its functions: {offered}."
+        )
+
+    def __dir__(self) -> list[str]:
+        return sorted({*super().__dir__(), *self.functions, *self._classes})
+
+    # Files ---------------------------------------------------------------
+
+    def _file(self, path: str) -> File:
+        for entry in self.files:
+            if entry.path == path:
+                return entry
+        close = difflib.get_close_matches(path, [entry.path for entry in self.files], n=1)
+        hint = f' Did you mean "{close[0]}"?' if close else ""
+        raise FileNotFoundError(f'{self.ref} has no file "{path}" at this version.{hint}')
+
+    def _fetch(self, entry: File) -> Path:
+        target = self.directory / entry.path
+        if target.exists() and _sha256(target) == entry.sha256:
+            return target
+        body = _http.get_bytes(entry.url, self._token)
+        if hashlib.sha256(body).hexdigest() != entry.sha256:
+            raise _http.ScienceHubError(
+                f"{entry.path} arrived with other bytes than this version names. Try again."
+            )
+        target.parent.mkdir(parents=True, exist_ok=True)
+        partial = target.with_name(f".{target.name}.part")
+        partial.write_bytes(body)
+        partial.replace(target)
+        return target
+
+    def path(self, path: str) -> Path:
+        """Download one file of this version, once, and return where it is on this computer."""
+        return self._fetch(self._file(path))
+
+    def open(self, path: str, mode: str = "rb", **kwargs: Any):
+        """Open one file of this version, downloading it first if needed."""
+        return open(self.path(path), mode, **kwargs)  # noqa: SIM115
+
+    def download(self) -> Path:
+        """Download the notebook and every file of this version; return the folder they are in."""
+        self._source()
+        for entry in self.files:
+            self._fetch(entry)
+        return self.directory
+
+    # The notebook ----------------------------------------------------------
+
+    def _source(self) -> Path:
+        target = self.directory / self._data["notebook"]["file"]
+        if not target.exists():
+            body = _http.get_bytes(self._data["version"]["source_url"], self._token)
+            target.parent.mkdir(parents=True, exist_ok=True)
+            partial = target.with_name(f".{target.name}.part")
+            partial.write_bytes(body)
+            partial.replace(target)
+            (self.directory / ".sciencehub.json").write_text(json.dumps(self._data))
+        return target
+
+    def module(self) -> ModuleType:
+        """The notebook imported as a module, with its files beside it. Imported once."""
+        if self._module is not None:
+            return self._module
+        source = self.download() / self._data["notebook"]["file"]
+        name = "sciencehub_" + re.sub(r"\W", "_", f"{self.ref}_{self.version.id}")
+        spec = importlib.util.spec_from_file_location(name, source)
+        if spec is None or spec.loader is None:
+            raise ImportError(f"Could not import {source}.")
+        module = importlib.util.module_from_spec(spec)
+        sys.modules[name] = module
+        sys.path.insert(0, str(self.directory))
+        try:
+            with self._inside():
+                spec.loader.exec_module(module)
+        except ModuleNotFoundError as error:
+            del sys.modules[name]
+            raise MissingDependencyError(self._missing(error.name)) from error
+        except BaseException:
+            del sys.modules[name]
+            raise
+        finally:
+            with contextlib.suppress(ValueError):
+                sys.path.remove(str(self.directory))
+        self._module = module
+        return module
+
+    def _missing(self, package: str | None) -> str:
+        needed = [d for d in self.dependencies if not re.match(r"^marimo\b", d)]
+        what = f"the package {package}" if package else "a package"
+        install = f"pip install {' '.join(_quoted(needed))}" if needed else f"pip install {package}"
+        return (
+            f"{self.ref} needs {what}, which is not installed in this Python. "
+            f"Install what the notebook declares with project.install(), or run: {install}"
+        )
+
+    def install(self) -> None:
+        """Install the packages the notebook declares into this Python, with pip or uv."""
+        packages = [d for d in self.dependencies if not re.match(r"^marimo\b", d)]
+        if not packages:
+            return
+        if shutil.which("uv") and not _has_pip():
+            command = ["uv", "pip", "install", "--python", sys.executable, *packages]
+        else:
+            command = [sys.executable, "-m", "pip", "install", *packages]
+        subprocess.run(command, check=True)
+
+    # Showing it ------------------------------------------------------------
+
+    def _version_line(self) -> str:
+        parts = [f"version {self.version.id[-8:]}"]
+        if self.version.release:
+            parts.append(f"release {self.version.release}, https://doi.org/{self.version.doi}")
+        elif self.version.current:
+            parts.append("the current one")
+        return ", ".join(parts)
+
+    def __repr__(self) -> str:
+        lines = [f"{self.ref} · {self.name}", f"{self._version_line()} · {self.url}"]
+        if self.description:
+            lines.append(self.description)
+        if self.functions or self._classes:
+            lines.append("")
+            lines.append("Functions")
+            for entry in self._data["functions"]:
+                prefix = "class " if entry["kind"] == "class" else ""
+                lines.append(f"  {prefix}{entry['name']}{entry['signature']}")
+                if entry.get("doc"):
+                    lines.append(f"      {entry['doc'].splitlines()[0]}")
+        if self.files:
+            lines.append("")
+            lines.append("Files")
+            width = max(len(entry.path) for entry in self.files)
+            for entry in self.files:
+                lines.append(f"  {entry.path.ljust(width)}  {_size(entry.size)}")
+        if self.version.current and not self.version.release:
+            lines.append("")
+            lines.append(f'Pin this version: sh.load("{self.ref}", version="{self.version.id}")')
+        return "\n".join(lines)
+
+    def _repr_html_(self) -> str:
+        e = html.escape
+        rows = "".join(
+            f"<tr><td><code>{e(('class ' if f['kind'] == 'class' else '') + f['name'] + f['signature'])}</code></td>"
+            f"<td>{e((f.get('doc') or '').splitlines()[0] if f.get('doc') else '')}</td></tr>"
+            for f in self._data["functions"]
+        )
+        files = "".join(
+            f"<tr><td><code>{e(entry.path)}</code></td><td>{_size(entry.size)}</td></tr>"
+            for entry in self.files
+        )
+        return (
+            f'<div><p><a href="{e(self.url)}"><strong>{e(self.ref)}</strong></a> · {e(self.name)}<br>'
+            f"<small>{e(self._version_line())}</small></p>"
+            + (f"<p>{e(self.description)}</p>" if self.description else "")
+            + (f"<table><thead><tr><th>Function</th><th></th></tr></thead><tbody>{rows}</tbody></table>" if rows else "")
+            + (f"<table><thead><tr><th>File</th><th>Size</th></tr></thead><tbody>{files}</tbody></table>" if files else "")
+            + "</div>"
+        )
+
+
+def _quoted(packages: list[str]) -> list[str]:
+    return [f'"{p}"' if re.search(r"[<>=!~\[\] ]", p) else p for p in packages]
+
+
+def _has_pip() -> bool:
+    return importlib.util.find_spec("pip") is not None
+
+
+def _sha256(path: Path) -> str:
+    digest = hashlib.sha256()
+    with open(path, "rb") as handle:
+        for chunk in iter(lambda: handle.read(1 << 20), b""):
+            digest.update(chunk)
+    return digest.hexdigest()
+
+
+def load(
+    ref: str,
+    *,
+    version: str | None = None,
+    release: int | None = None,
+    token: str | None = None,
+    url: str | None = None,
+) -> Project:
+    """Load a version of a ScienceHub notebook.
+
+    ``ref`` names it the way its page does: ``"owner/project"`` for the main
+    notebook, ``"owner/project/notebook"`` for another, or the page's address.
+    Without ``version`` or ``release`` it is the current version; the result
+    says which, so it can be pinned. ``release=2`` loads exactly what release
+    2's DOI names.
+
+    Private projects need a personal access token with the read scope, given
+    as ``token`` or in ``SCIENCEHUB_TOKEN``. ``url`` (or ``SCIENCEHUB_URL``)
+    chooses another ScienceHub site.
+    """
+    if version is not None and release is not None:
+        raise ValueError("Give version or release, not both.")
+    base = _http.base_url(url)
+    if "://" in ref:
+        parts = urlsplit(ref)
+        base = f"{parts.scheme}://{parts.netloc}"
+    owner, slug, notebook = _parse_ref(ref)
+    address = f"{base}/api/v1/projects/{quote(owner)}/{quote(slug)}"
+    if notebook:
+        address += f"/notebooks/{quote(notebook)}"
+    if release is not None:
+        address += f"?release={int(release)}"
+    elif version is not None:
+        address += f"?version={quote(version)}"
+    return Project(_http.get_json(address, token), token=token)

sciencehub-0.1.0/tests/conftest.py

@@ -0,0 +1,230 @@
+"""A site that answers the way sciencehub.sh does, on a local port."""
+
+from __future__ import annotations
+
+import hashlib
+import json
+import threading
+from http.server import BaseHTTPRequestHandler, ThreadingHTTPServer
+
+import pytest
+
+NOTEBOOK = '''# /// script
+# dependencies = ["marimo", "pandas>=2"]
+# ///
+import marimo
+
+__generated_with = "0.25.1"
+app = marimo.App()
+
+with app.setup:
+    import csv
+    G = 9.81
+
+
+@app.function
+def fall_time(height_m: float, g: float = G) -> float:
+    """Seconds for an object to fall height_m metres from rest."""
+    return (2 * height_m / g) ** 0.5
+
+
+@app.function
+def mean_drift(path: str = "data/argo.csv") -> float:
+    """Mean drift of the floats in a CSV file beside the notebook."""
+    with open(path) as handle:
+        rows = list(csv.DictReader(handle))
+    return sum(float(row["drift"]) for row in rows) / len(rows)
+
+
+@app.function
+async def doubled(x: int) -> int:
+    return 2 * x
+
+
+@app.class_definition
+class Body:
+    """A falling body."""
+
+    mass: float = 1.0
+
+
+@app.cell
+def _():
+    raise RuntimeError("cells do not run on import")
+    return
+
+
+if __name__ == "__main__":
+    app.run()
+'''
+
+BROKEN = '''import marimo
+
+app = marimo.App()
+
+with app.setup:
+    import a_package_nobody_has
+
+
+@app.function
+def use() -> int:
+    return 1
+'''
+
+CSV = b"float,drift\nA,1.5\nB,2.5\n"
+
+
+def description(base: str, slug: str, source_functions: list[dict], files: list[dict]) -> dict:
+    page = f"{base}/ada/{slug}"
+    return {
+        "project": {
+            "owner": "ada",
+            "slug": slug,
+            "name": "Drift",
+            "description": "Argo float drift.",
+            "visibility": "public",
+            "url": page,
+        },
+        "notebook": {
+            "slug": "drift",
+            "title": "Drift",
+            "file": "drift.py",
+            "main": True,
+            "url": page,
+            "concept_doi": None,
+        },
+        "notebooks": [{"slug": "drift", "title": "Drift", "main": True}],
+        "version": {
+            "id": "01K7VERSION",
+            "saved_at": "2026-10-13T10:00:00.000Z",
+            "current": True,
+            "release": None,
+            "url": f"{page}/history/01K7VERSION",
+            "source_url": f"{page}/history/01K7VERSION/source",
+        },
+        "environment": {"python": None, "dependencies": ["marimo", "pandas>=2"], "marimo": "0.25.1"},
+        "functions": source_functions,
+        "files": files,
+        "files_recorded": True,
+    }
+
+
+FUNCTIONS = [
+    {
+        "kind": "function",
+        "name": "fall_time",
+        "async": False,
+        "signature": "(height_m: float, g: float = G) -> float",
+        "parameters": [
+            {"name": "height_m", "kind": "positional-or-keyword", "annotation": "float", "default": None},
+            {"name": "g", "kind": "positional-or-keyword", "annotation": "float", "default": "G"},
+        ],
+        "returns": "float",
+        "doc": "Seconds for an object to fall height_m metres from rest.",
+        "decorators": [],
+    },
+    {
+        "kind": "function",
+        "name": "mean_drift",
+        "async": False,
+        "signature": '(path: str = "data/argo.csv") -> float',
+        "parameters": [
+            {
+                "name": "path",
+                "kind": "positional-or-keyword",
+                "annotation": "str",
+                "default": '"data/argo.csv"',
+            }
+        ],
+        "returns": "float",
+        "doc": "Mean drift of the floats in a CSV file beside the notebook.",
+        "decorators": [],
+    },
+    {
+        "kind": "function",
+        "name": "doubled",
+        "async": True,
+        "signature": "(x: int) -> int",
+        "parameters": [{"name": "x", "kind": "positional-or-keyword", "annotation": "int", "default": None}],
+        "returns": "int",
+        "doc": None,
+        "decorators": [],
+    },
+    {
+        "kind": "class",
+        "name": "Body",
+        "async": False,
+        "signature": "",
+        "parameters": [],
+        "returns": None,
+        "doc": "A falling body.",
+        "decorators": [],
+    },
+]
+
+
+class Site:
+    def __init__(self) -> None:
+        self.routes: dict[str, tuple[int, str, bytes]] = {}
+        self.requests: list[tuple[str, str | None]] = []
+        self.server = ThreadingHTTPServer(("127.0.0.1", 0), self._handler())
+        self.base = f"http://127.0.0.1:{self.server.server_address[1]}"
+        threading.Thread(target=self.server.serve_forever, daemon=True).start()
+
+    def _handler(self):
+        site = self
+
+        class Handler(BaseHTTPRequestHandler):
+            def do_GET(self) -> None:  # noqa: N802
+                site.requests.append((self.path, self.headers.get("Authorization")))
+                status, kind, body = site.routes.get(
+                    self.path,
+                    (404, "application/json", b'{"success": false, "error": {"code": "NOT_FOUND", "message": "No such project."}}'),
+                )
+                self.send_response(status)
+                self.send_header("Content-Type", kind)
+                self.send_header("Content-Length", str(len(body)))
+                self.end_headers()
+                self.wfile.write(body)
+
+            def log_message(self, *args) -> None:
+                pass
+
+        return Handler
+
+    def project(self, slug: str, source: str, functions: list[dict], files: dict[str, bytes]) -> None:
+        listed = [
+            {
+                "path": path,
+                "size": len(body),
+                "sha256": hashlib.sha256(body).hexdigest(),
+                "url": f"{self.base}/ada/{slug}/history/01K7VERSION/raw/{path}",
+            }
+            for path, body in files.items()
+        ]
+        data = description(self.base, slug, functions, listed)
+        self.routes[f"/api/v1/projects/ada/{slug}"] = (
+            200,
+            "application/json",
+            json.dumps({"success": True, "data": data}).encode(),
+        )
+        self.routes[f"/ada/{slug}/history/01K7VERSION/source"] = (200, "text/plain", source.encode())
+        for path, body in files.items():
+            self.routes[f"/ada/{slug}/history/01K7VERSION/raw/{path}"] = (200, "text/csv", body)
+
+
+@pytest.fixture
+def site(tmp_path, monkeypatch):
+    monkeypatch.setenv("SCIENCEHUB_CACHE", str(tmp_path / "cache"))
+    monkeypatch.delenv("SCIENCEHUB_TOKEN", raising=False)
+    served = Site()
+    monkeypatch.setenv("SCIENCEHUB_URL", served.base)
+    served.project("drift", NOTEBOOK, FUNCTIONS, {"data/argo.csv": CSV})
+    served.project(
+        "broken",
+        BROKEN,
+        [{**FUNCTIONS[0], "name": "use", "parameters": [], "signature": "() -> int", "doc": None}],
+        {},
+    )
+    yield served
+    served.server.shutdown()

sciencehub-0.1.0/tests/test_load.py

@@ -0,0 +1,100 @@
+import asyncio
+import inspect
+import os
+import pydoc
+
+import pytest
+
+import sciencehub as sh
+
+
+def test_describes_the_project_without_downloading_or_importing_it(site):
+    project = sh.load("ada/drift")
+    assert project.ref == "ada/drift"
+    assert sorted(project.functions) == ["doubled", "fall_time", "mean_drift"]
+    assert [entry.path for entry in project.files] == ["data/argo.csv"]
+    assert project.version.id == "01K7VERSION"
+    text = repr(project)
+    assert "fall_time(height_m: float, g: float = G) -> float" in text
+    assert "Seconds for an object to fall" in text
+    assert "class Body" in text
+    assert 'sh.load("ada/drift", version="01K7VERSION")' in text
+    assert "<table>" in project._repr_html_()
+    assert [path for path, _ in site.requests] == ["/api/v1/projects/ada/drift"]
+
+
+def test_gives_help_the_signature_and_docstring_the_author_wrote(site):
+    fall_time = sh.load("ada/drift").fall_time
+    assert str(inspect.signature(fall_time)) == "(height_m: float, g: float = G) -> float"
+    assert fall_time.__doc__ == "Seconds for an object to fall height_m metres from rest."
+    page = pydoc.render_doc(fall_time, renderer=pydoc.plaintext)
+    assert "fall_time(height_m: float, g: float = G) -> float" in page
+    assert "Seconds for an object to fall" in page
+    assert "fall_time" in dir(sh.load("ada/drift"))
+
+
+def test_calls_a_function_on_this_computer(site):
+    project = sh.load("ada/drift")
+    assert project.fall_time(4.905) == pytest.approx(1.0)
+    assert project.fall_time(height_m=19.62, g=9.81) == pytest.approx(2.0)
+
+
+def test_runs_a_function_where_its_files_are(site, tmp_path):
+    before = os.getcwd()
+    assert sh.load("ada/drift").mean_drift() == pytest.approx(2.0)
+    assert os.getcwd() == before
+
+
+def test_awaits_an_async_function(site):
+    doubled = sh.load("ada/drift").doubled
+    assert inspect.iscoroutinefunction(doubled)
+    assert asyncio.run(doubled(21)) == 42
+
+
+def test_gives_the_class_itself(site):
+    body = sh.load("ada/drift").Body
+    assert body.__doc__ == "A falling body."
+    assert body().mass == 1.0
+
+
+def test_downloads_a_file_once_and_checks_its_bytes(site):
+    project = sh.load("ada/drift")
+    path = project.path("data/argo.csv")
+    assert path.read_bytes().startswith(b"float,drift")
+    asked = len(site.requests)
+    assert project.path("data/argo.csv") == path
+    assert len(site.requests) == asked
+    with pytest.raises(FileNotFoundError, match='Did you mean "data/argo.csv"'):
+        project.path("data/argo.cvs")
+
+
+def test_refuses_bytes_that_are_not_the_ones_the_version_names(site):
+    project = sh.load("ada/drift")
+    site.routes["/ada/drift/history/01K7VERSION/raw/data/argo.csv"] = (200, "text/csv", b"tampered")
+    with pytest.raises(sh.ScienceHubError, match="other bytes"):
+        project.path("data/argo.csv")
+
+
+def test_names_a_missing_package_and_how_to_install_it(site):
+    project = sh.load("ada/broken")
+    with pytest.raises(sh.MissingDependencyError, match="a_package_nobody_has.*project.install"):
+        project.use()
+
+
+def test_suggests_a_name_for_a_typo(site):
+    with pytest.raises(AttributeError, match="Did you mean fall_time"):
+        sh.load("ada/drift").fall_tme  # noqa: B018
+
+
+def test_explains_a_missing_project_and_a_bad_reference(site):
+    with pytest.raises(sh.NotFoundError, match="No such project"):
+        sh.load("ada/nothing")
+    with pytest.raises(ValueError, match="owner/project"):
+        sh.load("drift")
+
+
+def test_reads_a_page_address_and_sends_the_token(site, monkeypatch):
+    monkeypatch.setenv("SCIENCEHUB_TOKEN", "shp_test")
+    project = sh.load(f"{site.base}/ada/drift")
+    assert project.slug == "drift"
+    assert site.requests[-1] == ("/api/v1/projects/ada/drift", "Bearer shp_test")