Python tools for RSpace

Scripts and tools for using the RSpace API through Python.

The RSpace API

You can use the RSpace API through python to create, list, upload, and manage many aspects of your RSpace objects. However, some features can only be done through the RSpace user interface online.

Use of the API can be complicated if all you want to do is perform simple tasks. However, if you want to e.g. replicate the same task many times, or if you want to integrate RSpace into your analysis workflow by automatically upload any results/plots/documents etc, the API can help and improve your efficiency and robustness.

The Python API tools can be found on GitHub at https://github.com/rspace-os/rspace-client-python. You should refer to the official github RSpace repository in the future, as the present notebook may run out of date.

You can also read more about the RSpace API at https://rspace.ntnu.no/public/apiDocs.

Requirements

Use of the API through python depends on the rspace_client==2.5.0 package found on both PyPi and conda. In addition, a few other requirements are useful. It is advised that a repository for RSpace API use includes at least these packages:

rspace-client==2.5.0
tabulate
jupyter
jupyterlab
matplotlib
numpy
scipy
markdown
json2html
pymdown-extensions
seaborn
pandas

Preparations

In order to use the API through python, you will need to do some preparations first, such as setting up an environment. Depedning on your python installation/distribution, this will vary. Here, we assume that you have a conda flavoured distribution (such as anaconda, miniconda, miniforge, etc).

Setting up environment

There are many ways of setting up an enviornment for using the RSpace API. Below follows three different examples. Choose the one that suits you best.

Only RSpace API

If you are only interested in using the RSpace API, you can limit yourself to a very simple and clean installation. However, you won't be able to do much interesting with this installation, and you won't be able to run the code in this repository.

Create a new environment for pure RSpace through conda (but use pip for rspace) in the terminal (windows users should use the "Anaconda Prompt" that is easily found using windows search):

conda create -n RSpace pip
conda activate RSpace
pip install rspace_client==2.5.0

Using `requirements.txt`

The code in this repository will need some additional other packages and the following will create an environment for you that works with the code in this repository. Remember to navigate to where requirements.txt is located before running the commands in your terminal:

conda create -n RSpace pip
conda activate RSpace
pip install -r requirements.txt

Other packages

If you want an environment with other packages as well you should try installing them when creating the repository:

conda create -n RSpace pip pyxem=0.20.0 hyperspy hyperspy-gui-traitsui hyperspy-gui-ipywidgets tabulate jupyter jupyterlab matplotlib numpy scipy markdown json2html pymdown-extensions seaborn pandas pyqt qtpy
conda activate RSpace
pip install rspace_client==2.5.0

API Key

Next, you need to get your API key from RSpace. Your API key is equivalent to a password, and should be treated as a secret. A few key points to remember is:

NEVER share your API key
NEVER include your API key directly in scripts or notebooks
Be CAREFUL if you enter your API key as input to scripts through the command-console. It will be stored in readable clear text in the console log!

We will get back to how to use your API key in a more secure way later on.

Getting your API Key

To get your API key:

If your API key for some reason gets compromised, or if you lose it, you can always repeat the steps above to regenerate the key. This will render any previous API key invalid. You can also revoke the key if you want to disable API access altogether.

Adding your key to the system environmental variables

To use your API key in scripts or on notebooks without adding it as clear text to files or in the command line, you can instead add the API key to the system environmental variables. This allows you to get the API key through python with commands such as

import os
os.getenv("RSPACE_API_KEY")

How to add your API key to the system environmental variables varies from system to system.

Windows

On Windows, you can add your API key to the system environmental variables by (see example images after the list):

Search for "environment" in the start menu (you should get a hit for "Edit the system environment variables").
Under "User variables for ..." click "New".
Enter a suitable variable name (e.g. "RSPACE_API_KEY") and enter the API key you got from RSpace as the value.

Linux

In linux you can add your RSpace API key to the system environment variables by editing your bashrc file (note that this involves storing the key in an unsecured text file and poses a potential security risk).

Before running your scripts, run RSPACE_API_KEY="<key>" directly before you run the script, and then unset RSPACE_API_KEY afterwards:

RSPACE_API_KEY="<your key>"
python create_document.py
unset RSPACE_API_KEY

Adding the API key to bashrc is discouraged, use other dedicated password managers instead.

Using the API

You should now be able to use e.g. this notebook. Use of the API is relatively straight forward, and you can usually find good examples and demos at https://github.com/rspace-os/rspace-client-python/tree/master/examples.

Most of the API commands returns a dictionary with the response from the RSpace server.

License

NTNU-RSpace-ELN/Python-tools-for-Rspace

About

Resources

License

Stars

Watchers

Forks

Releases

Packages 0

Languages

Packages