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.
pip install rspace-clientimport 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).
| Feature | What it does |
|---|---|
| Documents & basic/advanced search | Create, read, and update documents; search by tag, name, form, or date; page through results |
| Inventory: samples, subsamples, containers | Create and manage samples, split/duplicate subsamples, organise items into containers |
| Instruments & Instrument Templates (new in 2.7.0, RSpace 2.24) | Create, update, and manage Inventory instruments and instrument templates |
| Export | Async export of a user's or group's work (or specific documents/notebooks/folders) to HTML or XML, with progress polling |
| PyFilesystem access | GalleryFilesystem and InventoryAttachmentFilesystem implement the PyFilesystem API for Gallery files and Inventory attachments |
Notebook / Jupyter / R interop (notebook_sync) |
Helpers for round-tripping data between RSpace notebook entries and Jupyter or R workflows |
| Activity / audit trail | Query "who did what, when" for a record or across a date range |
| Forms | Create, publish, share, and list custom forms; create documents from them |
Full worked examples for every feature above are in the Usage Guide.
| Python | 3.9 or later (see pyproject.toml) |
| RSpace ELN API | 1.69 or later |
| RSpace Inventory API | 1.73 or later |
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.
Runnable scripts in examples/ (run with python3 examples/<script>.py $RSPACE_URL $RSPACE_API_KEY from that folder):
| Script | What it demonstrates |
|---|---|
status.py |
Check RSpace server status and API version |
create_document.py |
Create a document, upload a file, and link the file into it |
create_folder_and_notebook.py |
Create, retrieve, and delete folders and notebooks |
create_form.py |
Create a custom form and list/page through published forms |
create_sample.py |
Create an Inventory sample, including one with barcodes |
download_attachments.py |
Download file attachments from a document |
export_records.py |
Export a selection of documents/notebooks/folders |
freezer.py |
Build a freezer → shelf → rack → tray → box container hierarchy in Inventory |
get_activity.py |
Query the audit trail for a document, or for recent create/edit activity |
import_directory.py |
Import a local directory of files into RSpace |
import_word_file.py |
Import a Word (.docx) file as an RSpace document |
paging_through_results.py |
Page through document search results via HATEOAS links |
paging_through_users.py |
Page through users and batch-process accounts (admin use case) |
search_documents_by_form.py |
Find and export documents created from a specific form |
share_documents.py |
Share a newly created document with a group |
tree_upload.py |
Bulk-import a converted eCAT export (folders of .docx/images) with resume/log support |
Interactive notebooks in jupyter_notebooks/:
| Notebook | What it demonstrates |
|---|---|
rspace_demo.ipynb |
Full round-trip workflow: pull data from RSpace, analyse it, write results back |
rspace-demo-kaggle-v11.ipynb |
The same round-trip workflow using a Kaggle dataset — matches the walkthrough video |
samples_to_lom.ipynb |
Bulk-creates a notebook entry per sample assay, each with a List of Materials linking back to the sample's physical location |
(proteins.csv and temp_data.csv in the same folder are sample data used by these notebooks.)
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.
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.
Apache 2.0 — see LICENSE. Security policy is maintained org-wide at rspace-os/.github.