sciencehub

Use the functions and data of ScienceHub projects from Python.

A ScienceHub project is a marimo 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.

pip install sciencehub

Load a project

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

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

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:

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:

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 and set it as SCIENCEHUB_TOKEN, or pass token= to sh.load.

Settings

Apache 2.0.