|
| 1 | +# Backend Documentation |
| 2 | + |
| 3 | +## General Framework |
| 4 | +The backend for this extension is built as a Jupyter Server Extension. The project entry points are specified with the `pyproject.toml` file in the root directory. These point to the `zenodo_jupyterlab.server` module, which contains the `extenion.py` and `__init__.py` files which run the function that sets up the API handlers defined within other files in that directory. This guide will go through each section, with explanation of functionality. |
| 5 | + |
| 6 | +# Files in `zenodo_jupyterlab/server/` |
| 7 | + |
| 8 | +## `extension.py` |
| 9 | +`_load_jupyter_server_extenion` is a basic function that calls on `setup_handlers` which is defined in `handlers.py` and passes the `server_app.web_app` object. This is automatically passed via the server extension points. |
| 10 | + |
| 11 | +## `__init__.py` |
| 12 | +Defines the `_jupyter_server_extension_points` function that signals to the primary extension in `pyproject.toml` how to access the server extension and to build when it built. |
| 13 | + |
| 14 | +## `handlers.py` |
| 15 | +This file generates the API endpoints for use by the frontend components. All handlers inherit from `jupyter_server.base.handlers.APIHandler` (except the XSRFTokenHandler inherits from JupyterHandler). For simplicity, parameters are placed within the function definitions here, though they are accessed via the `APIHandler.get_argument()` function because they are URI encoded in the API calls. In addition, return statements are defined plainly here, though they are actually returned via the `APIHandler.finish()` function. |
| 16 | + |
| 17 | +### `class EnvHandler` |
| 18 | +Interacts with environmental variables in the Jupyter instance. Exploits the `os` module. |
| 19 | +#### `get(env_var: string)` |
| 20 | +Simple function to return the value of a stored environmental variable. Returns a dict containing the variable name and value. |
| 21 | +> **Returns:** `{env_var: *value*}` |
| 22 | +
|
| 23 | +#### `post(key: string, value: string)` |
| 24 | +Simple function to set the value of an environmental variable. Returns a dict with the parameters. |
| 25 | +> **Returns:** `{key, value}` |
| 26 | +
|
| 27 | +### `class XSRFTokenHandler` |
| 28 | +Note: this inherits from JupyterHandler, not APIHandler. |
| 29 | + |
| 30 | +#### `get(self: JupyterHandler)` |
| 31 | +Accesses JupyterHandler.xsrf_token and returns it. |
| 32 | +> **Returns:** `{'xsrfToken': xsrf_token}` |
| 33 | +
|
| 34 | +### `class Search RecordHandler` |
| 35 | +Handler designed to interact with `searchRecords` function defined in [`search.py`](#search). |
| 36 | + |
| 37 | +#### `get(search_field: string, page: int, communities: string)` |
| 38 | +Awaits response from `searchRecords` after passing all of the arguments and returns the list of corresponding records (max size: 25). |
| 39 | +> **Returns:** `{'records': *response*}` |
| 40 | +
|
| 41 | +### `class SearchCommunityHandler` |
| 42 | +Handler designed to interact with `searchCommunities` function defined in [`search.py`](#search). |
| 43 | + |
| 44 | +#### `get(search_field: string, page: int)` |
| 45 | +Awaits response from `searchCommunities` after passing all of the arguments and returns the list of corresponding communities (max size: 25). |
| 46 | +> **Returns:** `{'communities': *response*}` |
| 47 | +
|
| 48 | +### `class RecordInfoHandler` |
| 49 | +Handler designed to interact with `recordInformation` function defined in [`search.py`](#search). |
| 50 | + |
| 51 | +#### `get(record-id: string)` |
| 52 | +Awaits response from `recordInformation` after passing the `record-id` and returns the desired data. |
| 53 | +> **Returns:** `{'data': *response*}` |
| 54 | +
|
| 55 | +### `class FileBrowserHandler` |
| 56 | +Interacts with environmental information about the folder and files in the `$HOME` directory and child directories. |
| 57 | + |
| 58 | +#### `get(path: string) |
| 59 | +Pulls the Jupyter instance home directory from the `$HOME` environmental variable. Then appends the path passed to this to generate a relative path and verifies whether it exists (if not, returns an "error"). Exploits the `os.listdir` function to iterate through entries within the folder. Note: it explicitly ignores all entries that start with ".", though, in principle, these should be excluded by `listdir`. It then accumulates a list of directories of entry information: |
| 60 | +```json |
| 61 | +entry = { |
| 62 | + "name": file name, |
| 63 | + "type": directory or file, |
| 64 | + "path": relative path from home directory, |
| 65 | + "modified": isoformatted timestamp of last modification, |
| 66 | + "size": size |
| 67 | +} |
| 68 | +``` |
| 69 | +This information is all drawn from the returned data from `os.listdir`. |
| 70 | +> **Returns:** `{'entries': *list of entry dictionaries*}` |
| 71 | +
|
| 72 | +### `class ZenodoAPIHandler` |
| 73 | +Interacts with all functions that make calls to the `eossr.api.zenodo.ZenodoAPI` object. They are contained within this class to limit the need of generating new `ZenodoAPI` objects with each interaction. |
| 74 | + |
| 75 | +#### `property zAPI` |
| 76 | +Once logged in, this will hold a `ZenodoAPI` object initialized with the input access token and sandbox boolean. As long as they do not log in again, this object will remain for the lifetime of the Jupyter instance. |
| 77 | + |
| 78 | +#### `post(form_data: json dictionary)` |
| 79 | +Takes in a `form_data` JSON dictionary, that contains at least an `action` entry, which specifies which code to run. |
| 80 | + |
| 81 | +##### `if action == 'check-connection'` |
| 82 | +Verifies the validity of a Zenodo access token via the `checkZenodoConnection` function defined in [`testConnection.py`](#testConnection). If valid, sets `zAPI` to an initialized `ZenodoAPI` object. Returns the response from the called function. |
| 83 | +> **Returns:** `{'status': *response*}` |
| 84 | +
|
| 85 | +##### `if action == 'upload'` |
| 86 | +Interacts with the `upload` function defined in `upload.py`. If `zAPI` is not yet initialized, the function returns a status of "Please log in before attempting to upload." Otherwise, returns the response from the function. |
| 87 | +> **Returns:** `{'status': *response*}` |
| 88 | +
|
| 89 | +### `class ServerInfoHandler` |
| 90 | + |
| 91 | +#### `get` |
| 92 | +Retrieves the home directory. |
| 93 | +> **Returns:** `{'root_dir': *home directory*}` |
| 94 | +
|
| 95 | +### `setup_handlers` |
| 96 | +`setup_handlers(web_app)` |
| 97 | + |
| 98 | +Defines the API endpoints for access from the frontend. Builds the urls off of the "web_app" base path and "zenodo-jupyterlab". Thus all handlers are of the form: base_path + "zenodo-jupyterlab-*action*". This function then adds these endpoints to the web_app. |
| 99 | + |
| 100 | +## `search.py` |
| 101 | +This files handles all search requests to Zenodo via the [`eOSSR`](https://gitlab.com/escape-ossr/eossr) library. |
| 102 | + |
| 103 | +### `searchRecords` |
| 104 | +`searchRecords(search_field: string, page: int, **kwargs)` |
| 105 | + |
| 106 | +Calls the `eossr.api.zenodo.search_records` with the given arguments, as well as restricts the size of the response to 25 (i.e. passes `size = 25` as well). Parses the returned list of `eossr.api.zenodo.Record` objects and returns a list of the following kinds of dictionaries: |
| 107 | +```json |
| 108 | +record = { |
| 109 | + "id": Record ID, |
| 110 | + "title": Record title, |
| 111 | + "date": Date Published, |
| 112 | + "resource_type": Records resource type (from within the metadata) |
| 113 | +} |
| 114 | +``` |
| 115 | +If this call to `eOSSR` fails, the function simply returns `["failed"]`. |
| 116 | +> **Returns:** [list of records] |
| 117 | +
|
| 118 | +### `searchCommunities` |
| 119 | +`searchCommunities(search_field: string, page: int)` |
| 120 | + |
| 121 | +Calls the `eossr.api.zenodo.search_communities` with the given arguments, as well as restricts the size of the response to 25 (i.e. passes `size = 25` as well). Parses the returned list of dictionaries and returns a list of the following kinds of dictionaries: |
| 122 | +```json |
| 123 | +community = { |
| 124 | + "id": Community ID, |
| 125 | + "title": Community title, |
| 126 | + "date": Date Published, |
| 127 | +} |
| 128 | +``` |
| 129 | +If this call to `eOSSR` fails, the function simply returns `["failed"]`. |
| 130 | +> **Returns:** [list of communities] |
| 131 | +
|
| 132 | +### `recordInformation` |
| 133 | +`recordInformation(recordID: string)` |
| 134 | + |
| 135 | +Returns more specific information about a specified record via `eossr.api.zenodo.get_record`. Parses the returned data from this function and creates the following dictionary: |
| 136 | +```json |
| 137 | +record= { |
| 138 | + 'authors': authors with affiliations as listed in the record, |
| 139 | + 'filelist': the list of files (full download links) attached to record |
| 140 | +} |
| 141 | +``` |
| 142 | +Note: The existing information such as title and id are still held on the frontend in the tabular display, so no need to repass that information. Secondary note: if this call fails, this function returns `{"status": "failed"}`. |
| 143 | +> **Returns:** *record* |
| 144 | +
|
| 145 | +## `testConnection.py` |
| 146 | +File devoted to validating Zenodo access tokens. |
| 147 | + |
| 148 | +### `checkZenodoConnection` |
| 149 | +Extracts the access token and sandbox boolean from the environmental variables `ZENODO_API_KEY` and `ZENODO_SANDBOX`, respectively. Parses the string value of the sandbox boolean into a Python boolean (stored as a string due to the mismatch is syntax between Typescript and Python booleans). Creates a `eossr.api.zenodo.ZenodoAPI` object with those extracted variables as arguments and stores it in `zAPI`. Then, uses the `eossr.api.zenodo.ZenodoAPI.query_user_deposits` function and extracts the status from this response, which indicates whether or not the access token is valid or if a connection can be made to the Zenodo REST API. If either stage fails, `zAPI` is initialized to `None` and the query status is set to 0. |
| 150 | +> **Returns:** status code of the query, `zAPI` |
| 151 | +
|
| 152 | +## `upload.py` |
| 153 | +Devoted to generating and populating new Zenodo record deposits. |
| 154 | + |
| 155 | +### `createDeposit` |
| 156 | +`createDeposit(zAPI: eossr.api.zenodo.ZenodoAPI)` |
| 157 | + |
| 158 | +Uses `eossr.api.zenodo.ZenodoAPI.create_new_deposit` to create an empty deposit. Note: whether or not this deposit exists on Zenodo or Zenodo Sandbox is entirely dependent on what option the user selected when logging in. |
| 159 | +> **Returns:** ID of the newly created record |
| 160 | +
|
| 161 | +### `createMetadata` |
| 162 | +`createMetadata(zAPI: eossr.api.zenodo.ZenodoAPI, recordID: int, form_data: FormData object)` |
| 163 | + |
| 164 | +*Work in Progress*\ |
| 165 | +Extracts title from form_data and creates a JSON dict as follows: |
| 166 | +```json |
| 167 | +json_metadata = { |
| 168 | + "title": given title |
| 169 | +} |
| 170 | +``` |
| 171 | +Uses `eossr.api.zenodo.ZenodoAPI.set_deposit_metadata` to take in the recordID and the JSON data and add this metadata to the existing Zenodo object. |
| 172 | +> **Returns:** *response* |
| 173 | +
|
| 174 | +### `upload` |
| 175 | +`upload(zAPI: eossr.api.zenodo.ZenodoAPI, form_data: FormData object)` |
| 176 | + |
| 177 | +Verifies if zAPI has been initialized; if not, returns `None`. Calls `createDeposit` and passes `zAPI` and captures returns record ID. Then uses this record ID, form_data, and the `zAPI` to call `createMetadata`. |
| 178 | +> **Returns:** "Success" if *response* doesn't equal `None` |
0 commit comments