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.
