rspace-client-python

The official Python client for the RSpace ELN and Inventory APIs. It wraps the raw REST endpoints in a Pythonic interface so you can create and search documents, manage Inventory samples and containers, export your work, and read/write Gallery and Inventory files — from a script, a Jupyter notebook, or your own application.

Don't have an RSpace account? Sign up for free at community.researchspace.com, or run RSpace locally in Docker. You'll need an API key from your profile page to use this client. This client is especially easy to use from Jupyter notebooks — see the round-trip data analysis video for a walkthrough.

Quick start

pip install rspace-client

import os
from rspace_client.inv import inv
from rspace_client.eln import eln

inv_cli = inv.InventoryClient(os.getenv("RSPACE_URL"), os.getenv("RSPACE_API_KEY"))
eln_cli = eln.ELNClient(os.getenv("RSPACE_URL"), os.getenv("RSPACE_API_KEY"))

samples = inv_cli.list_samples()
print(f"There are {samples['totalHits']} samples")

print(eln_cli.get_status())

Set RSPACE_URL and RSPACE_API_KEY as environment variables first:

bash> export RSPACE_URL=https://myrspace.com
bash> export RSPACE_API_KEY=abcdefgh...

Full REST API reference is served by your own RSpace instance at https://<YOUR_RSPACE_DOMAIN>/public/apiDocs (e.g. https://community.researchspace.com/public/apiDocs).

Core features

Full worked examples for every feature above are in the Usage Guide.

Compatibility & limitations

This client doesn't cover 100% of the REST API. It's a convenience layer, and some capabilities are only exposed through the web application or the raw REST endpoints — for example, sharing a notebook into the Shared Folder currently has to be done in the UI (see Creating a Folder / Notebook). If something you need isn't covered here, check the full REST API docs at <YOUR_RSPACE_DOMAIN>/public/apiDocs before assuming it isn't possible.

Examples & notebooks

Runnable scripts in examples/ (run with python3 examples/<script>.py $RSPACE_URL $RSPACE_API_KEY from that folder):

Interactive notebooks in jupyter_notebooks/:

(proteins.csv and temp_data.csv in the same folder are sample data used by these notebooks.)

Testing

CI (.github/workflows/codeql-and-tests.yml) runs unit tests across supported Python versions, then integration tests against a real RSpace instance: it builds rspace-web from source and starts it with a freshly seeded database (no Docker image, no browser automation), logs in once to initialize the built-in test account, then runs the suite against it.

To run tests locally:

# unit tests only
poetry run pytest -m "not integration"

# integration tests, against your own RSpace instance
export RSPACE_URL=https://<your-rspace-domain>
export RSPACE_API_KEY=<your-api-key>
poetry run pytest -m integration

Community projects

See what others have built on top of RSpace and RSpace Python SDK on the Community Projects page. Built something with this client? Share it in an office hour or open a PR to add it.

Contributing

Contributions of all sizes are welcome — from a typo fix to a new feature. See CONTRIBUTING.md for how to get started, DEVELOPING.md for local setup and running tests, and the Guide to the RSpace Project for the project's wider vision and governance.

License & security

Apache 2.0 — see LICENSE. Security policy is maintained org-wide at rspace-os/.github.