Sign in

Use projects from Python

A project's functions and files are there for your own code: call a function the author wrote, read the data they published, and pin both to the version you cited.

Install

Shell
pip install sciencehub

Load a project

Name the project as its address does: owner/project for its main notebook, owner/project/notebook for another one. Printing it lists its functions with their signatures, its files, and the version you got.

Python
import sciencehub as sh

keeling_curve = sh.load("sciencehub-team/keeling-curve")
keeling_curve

Call a function

A function is any cell the notebook keeps as a reusable function: a cell that holds only a def and uses nothing but the setup cell. marimo marks it @app.function in the file. The project's Functions tab lists them.

Python
help(keeling_curve.growth_rate)
keeling_curve.growth_rate(2015, 2025)

help(), inspect.signature, Jupyter's ? and your editor show the signature and docstring the author wrote. The first call downloads the notebook and its files, imports the notebook, and runs the function on your computer, in the notebook's folder, so a function that opens data/co2_mm_mlo.csv finds it.

The notebook's dependencies must be installed in your Python. A missing one is named in the error; keeling_curve.install() installs what the notebook declares. Calling a function runs its author's code, as installing their package would.

Read a file

Python
path = keeling_curve.path("data/co2_mm_mlo.csv")   # downloaded once, checked, then read from disk
keeling_curve.download()                            # the notebook and every file, in one folder

Every file of a public project also has an address any program can read, under raw/:

Python
import pandas as pd

co2 = pd.read_csv("https://sciencehub.sh/sciencehub-team/keeling-curve/raw/data/co2_mm_mlo.csv", comment="#")

Read a file with any library

With pip install "sciencehub[fsspec]", pandas, polars, xarray, Dask and DuckDB read a project's files by their sciencehub:// address (sh:// for short). @release-1 after the project's name reads what that release names.

Python
import pandas as pd

co2 = pd.read_csv(
    "sciencehub://sciencehub-team/keeling-curve/data/co2_mm_mlo.csv", comment="#"
)

Run it on your computer

One command copies a version of the notebook with its files into a folder and opens it in marimo. With uv it runs in a sandbox that installs what the notebook declares. Changes stay on your computer; upload the notebook on the project's History page to make them a version.

Shell
uvx sciencehub edit sciencehub-team/keeling-curve
uvx sciencehub run sciencehub-team/keeling-curve --release 1

Pin a version

A load is always one version of the notebook, with the files that version was saved with. Pin it so your results do not move when the author saves again. A release's DOI names its files too, byte for byte.

Python
sh.load("sciencehub-team/keeling-curve", version="ver_01M…")   # one saved version
sh.load("sciencehub-team/keeling-curve", release=1)            # what DOI release 1 names

Private projects

Make a personal access token with the read scope in Settings → Tokens and set it as SCIENCEHUB_TOKEN, or pass token= to sh.load.

From any language

The package reads one address. It describes a version of a notebook as JSON: its functions with their parameters, docstrings and a JSON Schema of their inputs and result, its files with addresses pinned to the version, its dependencies, and where its source is.

Shell
curl https://sciencehub.sh/api/v1/projects/sciencehub-team/keeling-curve
curl "https://sciencehub.sh/api/v1/projects/sciencehub-team/keeling-curve?release=2"

Send a token as Authorization: Bearer shp_… for private projects. A token is read at most 120 times a minute.