#! /bin/python3
import json
from .req_util import OS_request_gen
from .url import url_gen
from .. import config_manager
[docs]class institutes():
"""Handles the API calls for the institutes
Handles the OpenSpecimen API calls for the institutes. This class can
create, delete, update institutes. One can search via different parameters for an institute and
get all Collection protocols corresponding to an institute. Get one or all institutes.
Note
-----
In order to use this and also the other classes, the user has to know OpenSpecimen. In the core classes, one can
just pass the parameters via a JSON-formatted string. This means the user has to know the keywords.
The API calls are documented in https://openspecimen.atlassian.net/wiki/spaces/CAT/pages/1116035/REST+APIs and
the calls refer to this site. More details can be seen in the documentation.
Examples
--------
Code examples, where the institutes are handled, is in the Jupyter-Notebook:
$ jupyter notebook main.ipynb
"""
def __init__(self):
"""Constructor of the Class Institutes
Constructor of the class institutes can handle the basic API-calls
of the institutes in OpenSpecimen. Connects this class to OpenSpecimen
specific URL Generator Class (os_core/url.py)
Parameters
----------
base_url : string
URL to openspecimen, has the format: http(s)://<host>:<port>/openspecimen/rest/ng
auth : tuple
Consists of two strings ( loginname , password)
"""
self.base_url = config_manager.get_url() + '/institutes'
self.auth = config_manager.get_auth()
self.OS_request_gen = OS_request_gen(self.auth)
self.urls = url_gen()
[docs] def ausgabe(self):
"""Testing of the URL and Authentification.
If there are any unexpected errors, one can easily test if the URL and login data is spelled correctly.
The function prints the URL and login data to the output terminal, which was handed over to the class.
"""
print(self.base_url, self.OS_request_gen.auth)
[docs] def create_institute(self, params):
"""Create an Institute.
Creates an institute in OpenSpecimen. In order to use this function one has to know
the parameters which OpenSpecimen needs to create an institute. One can use it via the os_util class
institute_util. This allows just the basic definition.
Parameters
----------
params : string
JSON formatted string with Parameters: name (Name of the Institute)
Returns
-------
json-dict
Either details of the created institute as JSON-dict or the OpenSpecimen's error message.
"""
url = self.base_url + '/'
payload = params
r = self.OS_request_gen.post_request(url, payload)
return json.loads(r.text)
[docs] def delete_institute(self, inid):
"""Delete an Institute
Delete an existing institute in OpenSpecimen with ID <inid>.
The ID is created from OpenSpecimen and can, for Examples, be seen in the GUI
under Institutes. When clicking on the institute, the URL looks like:
http(s)://<host>:<port>/openspecimen/institutes/{inid}/overview .
Otherwise, one can search with the function search_institutes for Examples by name and extract the ID from there.
Parameters
---------
inid : int
The ID of the Institute, generated by the system, will get converted to a string.
Returns
-------
JSON-dict
Details of the deleted institute or the OpenSpecimen's error message.
"""
endpoint = '/' + str(inid)
url = self.base_url + endpoint
r = self.OS_request_gen.delete_request(url)
return json.loads(r.text)
[docs] def search_institutes(self, substring):
"""Search for Institutes with specific substring.
Search for one or more institutes with the substring. The search URL looks like:
http(s)://<host>:<port>/openspecimen/rest/np/institutes?{param_1}={value_1}&...&{param_x}={value_x}
Parameters
----------
substring : string
Substring of the Institutename.
Returns
-------
JSON-dict
Details of all matching institutes or the OpenSpecimen's error message.
"""
endpoint = '?name=' + str(substring)
url = self.base_url + endpoint
r = self.OS_request_gen.get_request(url)
return json.loads(r.text)
[docs] def get_all_institutes(self):
"""Get all Institutes
Get all institutes within the OpenSpecimen distribution, which is defined in the base_url.
Returns
-------
JSON-dict
Details of all institutes which are in the OpenSpecimen Distribution.
"""
url = self.base_url
r = self.OS_request_gen.get_request(url)
return json.loads(r.text)
[docs] def get_institute(self, inid):
"""Get the institute with the ID inid
Get the details of the Institute with the unique ID inid.
This ID is automatically generated by OpenSpecimen at Protocol creation.
Parameters
----------
inid : int
The System's ID of the Institute, will be converted to a string.
Returns
-------
JSON-dict
Details of the Institute with the specified ID, or the OpenSpecimen error message.
"""
endpoint = '/' + str(inid)
url = self.base_url + endpoint
r = self.OS_request_gen.get_request(url)
return json.loads(r.text)
[docs] def update_institute(self, inid, params):
"""Updates an existing Institute with ID inid with the Parameters params
Updates an existing institute with the automatically generated OpenSpecimen's system wide
unique Institute ID instituteid, with the Parameters params which are passed to the function.
The ID of the institute has to be known and can, for Examples, be seen in the GUI by clicking on
the institutes, which has the format http(s)://<host>:<port>/openspecimen/institutes/{inid}/....or via the function search_institutes.
Parameters
---------
instituteid : int
Unique Institute ID which is generated automatically from the system. It will be converted to a string.
institutename : string
New name of the institute, if it is left empty, nothing will be updated.
Returns
-------
JSON-dict
JSON-dict with the details of the updated institute or the OpenSpecimen's error message.
"""
endpoint = '/' + str(inid)
url = self.base_url + endpoint
payload = params
r = self.OS_request_gen.put_request(url, payload)
return json.loads(r.text)