elapi 1.0.7.dev8__tar.gz → 2.0.1__tar.gz

{elapi-1.0.7.dev8 → elapi-2.0.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: elapi
-Version: 1.0.7.dev8
+Version: 2.0.1
 Summary: elAPI is a powerful, extensible API client for eLabFTW.
 Home-page: https://www.urz.uni-heidelberg.de/en/service-catalogue/software-and-applications/elabftw
 License: AGPL-3.0-only
@@ -36,16 +36,21 @@ Requires-Dist: python-dateutil (>=2.8.2,<3.0.0) ; extra == "uhd-urz"
 Requires-Dist: pyyaml (>=6.0.1,<7.0.0)
 Requires-Dist: tenacity (>=8.2.3,<9.0.0) ; extra == "uhd-urz"
 Requires-Dist: typer[all] (>=0.9.0,<0.10.0)
+Project-URL: Repository, https://github.com/uhd-urz/elAPI/
 Description-Content-Type: text/markdown
 
 # elAPI
 
-elAPI is a powerful, extensible API client for eLabFTW built for
-the [University Computing Centre](https://www.urz.uni-heidelberg.de/en) (
-URZ, [FIRE](https://www.urz.uni-heidelberg.de/en/node/64/organisation/future-it-research-education) division) at
-Universität Heidelberg. It supports serving almost all kinds of requests documented on
-[eLabFTW API documentation](https://doc.elabftw.net/api/v2/) with ease. elAPI treats eLabFTW API endpoints as its
-arguments.
+[![Package version](https://badge.fury.io/py/elapi.svg/?branch=main)](https://pypi.org/project/elapi)
+
+elAPI is a powerful, extensible API client for eLabFTW developed at
+the [University Computing Centre](https://www.urz.uni-heidelberg.de/en)
+(URZ, [FIRE](https://www.urz.uni-heidelberg.de/en/node/64/organisation/future-it-research-education) division) of
+[University of Heidelberg](https://www.uni-heidelberg.de/en). It supports serving all kinds of requests documented on
+[eLabFTW API documentation](https://doc.elabftw.net/api/v2/) with ease. elAPI provides a simple interface via its CLI
+executable, and numerous advanced APIs when it is used directly as a Python package.
+
+![elAPI features in a nutshell](./.assets/elapi_features.svg)
 
 **Example:**
 
@@ -55,9 +60,14 @@ From [the documentation](https://doc.elabftw.net/api/v2/#/Users/read-user):
 With elAPI you can do the following:
 
 ```sh
-$ elapi get users --id <id>
+$ elapi get experiments -f csv --export ~/Downloads/
 ```
 
+Once the command is run, in the background, elAPI will read host (eLab server) address, API key and various other
+settings (see [configuration](#configuration)) from the configuration file `elapi.yml`, perform validation (e.g.,
+whether the server address is valid), fetch all _experiments_ list, convert them to `CSV`, and export them to your
+local `~/Downloads/` folder.
+
 ## Installation
 
 elAPI can be used both as a CLI tool and as a Python library. If you are interested in simply using elAPI's
@@ -123,10 +133,12 @@ host: <host API url>
 # Example: https://demo.elabftw.net/api/v2/
 # Note the host URL ends with the API endpoint
 api_token: <token with at least read-access>
-# You can generate an API token from eLabFTW user panel -> API keys tab.
+# "A.k.a API key". You can generate an API token from eLabFTW user panel -> API keys tab.
 export_dir: ~/Downloads/elAPI
-unsafe_api_token_warning: yes
-enable_http2: no
+unsafe_api_token_warning: true
+enable_http2: false
+verify_ssl: true
+timeout: 90
 ```
 
 `export_dir` is where elAPI will export response content to if no path is provided to `--export/-E`.
@@ -134,7 +146,11 @@ When `unsafe_api_token_warning` is `True`, elAPI will show a warning if you're s
 working directory, as it typically happens that developers accidentally commit and push configuration files with
 secrets. `enable_http2` enables HTTP/2 protocol support which by default is turned off. Be aware
 of [known issues](https://github.com/encode/httpx/discussions/2112) with
-HTTP/2 if you are making async requests with heavy load.
+HTTP/2 if you are making async requests with heavy load. `verify_ssl` can be turned off with `False` if you are trying
+out a development server that doesn't provide a valid SSL certificate. `timeout` can be modified to your needs. E.g., a
+poor internet connection might benefit from a higher timeout number. THe default timeout is `90` seconds.
+
+### `show-config`
 
 You can get an overview of detected configuration with `elapi show-config`. `show-config` makes it easier to verify
 which configuration values are actually used by elAPI, if you are working with multiple configuration files.
@@ -142,30 +158,40 @@ which configuration values are actually used by elAPI, if you are working with m
 ```shell
 $ elapi show-config
 
-
-                                                       elapi configuration information
+elapi configuration information
 
 The following debug information includes configuration values and their sources as detected by elapi.
 
 ▌ Name [Key]: Value ← Source
 
- • Log file path: /Users/<username>/.local/share/elapi/elapi.log
- • Host address [host]: https://demo.elabftw.net/api/v2 ← USER LEVEL
- • API Token [api_token]: 00-55******55555 ← USER LEVEL
- • Export directory [export_dir]: /Users/<username>/Downloads/elapi ← USER LEVEL
- • App data directory: /Users/<username>/.local/share/elapi
- • Caching directory: /private/var/tmp/elapi
- • Unsafe API token use warning [unsafe_api_token_warning]: Yes ← USER LEVEL
- • Enable HTTP/2 [enable_http2]: Yes ← USER LEVEL
+• Log file path: /Users/ <username >/.local/share/elapi/elapi.log
+• Host address [host]: https://demo.elabftw.net/api/v2 ← USER LEVEL
+• API Token [api_token]: 00-55******55555 ← USER LEVEL
+• Export directory [export_dir]: /Users/ ← USER LEVEL <username >/Downloads/elapi
+• App data directory: /Users/ <username >/.local/share/elapi
+• Third-party plugins directory: /Users/ <username >/.local/share/elapi/plugins
+• Caching directory: /private/var/tmp/elapi
+• Unsafe API token use warning [unsafe_api_token_warning]: True ← USER LEVEL
+• Enable HTTP/2 [enable_http2]: False ← USER LEVEL
+• Verify SSL certificate [verify_ssl]: True ← USER LEVEL
+• Timeout duration [timeout]: 90.0 seconds ← USER LEVEL
+• Development mode [development_mode]: False ← USER LEVEL
 
 Detected configuration sources that are in use:
 
- • USER LEVEL: /Users/<username>/.config/elapi.yml
+• USER LEVEL: /Users/ <username >/.config/elapi.yml
 
 ```
 
 If both `host` and `api_token` are detected, you are good to go!
 
+### Override configuration
+
+elAPI now supports `--override/--OC` as a global option that can be used to override the configuration parameters
+as detected by `elapi show-cofig`. All plugins will also automatically listen to the overridden configuration. This can
+be useful to set certain configurations temporarily. E.g., `elapi --OC '{"timeout": 300"}' get info` will override
+the `timeout` from the configuration files.
+
 ## Usage
 
 elAPI can be invoked from the command-line.
@@ -253,19 +279,59 @@ You can also upload an attachment to an experiment.
 $ elapi experiments upload-attachment --id <experiment ID> --path <path to attachment file> --comment <comment for your attachment>
 ```
 
-### Bill teams
+### Plugins
 
-You can get a list of all teams and its users for billing purposes and export it to home directory.
+elAPI has seamless support with tight-integration for third-party plugins. A simple third-party plugin can be created in
+a few easy steps:
 
-```shell
-$ elapi bill-teams teams-info --export ~
+1. Create a new subfolder under `~/.local/share/elapi/plugins` with the name for your new plugin (e.g, a folder named
+   "test")
+2. Create a `cli.py` in the subfolder with the following snippet:
+
+```python
+from elapi.plugins.commons import Typer
+
+app = Typer(name="test", help="Test plugin.")
+
+```
+
+3. Run `elapi` again to see your plugin name under `Third-party plugins` list
+
+Plugins are integrated in a way such that a plugin will **not** fail elAPI. So, even if one erroneous plugin is loaded,
+all
+other plugins and elAPI itself will remain unaffected. elAPI will show the error message on the "Message" panel.
+
+If you try to import a package that is not a dependency of elAPI inside `cli.py`, your plugin will fail. In that case,
+you want to create a plugin metadata file `elapi_plugin_metadata.yml` (notice only `.yml` extension is allowed), and
+define the virtual environment that your plugin specifically requires.
+
+```python
+import requests
+
+from elapi.api import GETRequest
+from elapi.plugins.commons import Typer
+
+# Plugin metadata
+app = Typer(name="awesome", help="An awesome elAPI plugin.")
+
+
+@app.command(name="get-request", short_help=f"Make a GET request")
+def get_request(endpoint_name):
+    r = GETRequest()
+    print(r(endpoint_name).json())
+
+
+@app.command(name="get-wiki-status", short_help=f"Show status of Wikipedia")
+def wiki_status():
+    r = requests.get("https://wikipedia.org")
+    print(r)
 ```
 
-Most sub-commands available under `elapi bill-teams` plugin are for Universität Heidelberg specific use-cases.
+And the path to virtual environment will be defined in the metadata file:
 
-## Open-source
+```yaml
+plugin_name: test
+cli_script: ./cli.py  # Path to the cli.py script
+venv_dir: ./.venv  # Path to the virtual environment
+```
 
-elAPI is open-source and published under AGPLv3 license. The repository is however hosted internally within
-Universität Heidelberg's network. The codebase can still be accessed from [PyPI](https://pypi.org/project/elapi/#files).
-If you express interest in having the repository made completely public, or if you have any question, feel free
-to [contact us](mailto:elabftw@uni-heidelberg.de).

{elapi-1.0.7.dev8 → elapi-2.0.1}/README.md

@@ -1,11 +1,15 @@
 # elAPI
 
-elAPI is a powerful, extensible API client for eLabFTW built for
-the [University Computing Centre](https://www.urz.uni-heidelberg.de/en) (
-URZ, [FIRE](https://www.urz.uni-heidelberg.de/en/node/64/organisation/future-it-research-education) division) at
-Universität Heidelberg. It supports serving almost all kinds of requests documented on
-[eLabFTW API documentation](https://doc.elabftw.net/api/v2/) with ease. elAPI treats eLabFTW API endpoints as its
-arguments.
+[![Package version](https://badge.fury.io/py/elapi.svg/?branch=main)](https://pypi.org/project/elapi)
+
+elAPI is a powerful, extensible API client for eLabFTW developed at
+the [University Computing Centre](https://www.urz.uni-heidelberg.de/en)
+(URZ, [FIRE](https://www.urz.uni-heidelberg.de/en/node/64/organisation/future-it-research-education) division) of
+[University of Heidelberg](https://www.uni-heidelberg.de/en). It supports serving all kinds of requests documented on
+[eLabFTW API documentation](https://doc.elabftw.net/api/v2/) with ease. elAPI provides a simple interface via its CLI
+executable, and numerous advanced APIs when it is used directly as a Python package.
+
+![elAPI features in a nutshell](./.assets/elapi_features.svg)
 
 **Example:**
 
@@ -15,9 +19,14 @@ From [the documentation](https://doc.elabftw.net/api/v2/#/Users/read-user):
 With elAPI you can do the following:
 
 ```sh
-$ elapi get users --id <id>
+$ elapi get experiments -f csv --export ~/Downloads/
 ```
 
+Once the command is run, in the background, elAPI will read host (eLab server) address, API key and various other
+settings (see [configuration](#configuration)) from the configuration file `elapi.yml`, perform validation (e.g.,
+whether the server address is valid), fetch all _experiments_ list, convert them to `CSV`, and export them to your
+local `~/Downloads/` folder.
+
 ## Installation
 
 elAPI can be used both as a CLI tool and as a Python library. If you are interested in simply using elAPI's
@@ -83,10 +92,12 @@ host: <host API url>
 # Example: https://demo.elabftw.net/api/v2/
 # Note the host URL ends with the API endpoint
 api_token: <token with at least read-access>
-# You can generate an API token from eLabFTW user panel -> API keys tab.
+# "A.k.a API key". You can generate an API token from eLabFTW user panel -> API keys tab.
 export_dir: ~/Downloads/elAPI
-unsafe_api_token_warning: yes
-enable_http2: no
+unsafe_api_token_warning: true
+enable_http2: false
+verify_ssl: true
+timeout: 90
 ```
 
 `export_dir` is where elAPI will export response content to if no path is provided to `--export/-E`.
@@ -94,7 +105,11 @@ When `unsafe_api_token_warning` is `True`, elAPI will show a warning if you're s
 working directory, as it typically happens that developers accidentally commit and push configuration files with
 secrets. `enable_http2` enables HTTP/2 protocol support which by default is turned off. Be aware
 of [known issues](https://github.com/encode/httpx/discussions/2112) with
-HTTP/2 if you are making async requests with heavy load.
+HTTP/2 if you are making async requests with heavy load. `verify_ssl` can be turned off with `False` if you are trying
+out a development server that doesn't provide a valid SSL certificate. `timeout` can be modified to your needs. E.g., a
+poor internet connection might benefit from a higher timeout number. THe default timeout is `90` seconds.
+
+### `show-config`
 
 You can get an overview of detected configuration with `elapi show-config`. `show-config` makes it easier to verify
 which configuration values are actually used by elAPI, if you are working with multiple configuration files.
@@ -102,30 +117,40 @@ which configuration values are actually used by elAPI, if you are working with m
 ```shell
 $ elapi show-config
 
-
-                                                       elapi configuration information
+elapi configuration information
 
 The following debug information includes configuration values and their sources as detected by elapi.
 
 ▌ Name [Key]: Value ← Source
 
- • Log file path: /Users/<username>/.local/share/elapi/elapi.log
- • Host address [host]: https://demo.elabftw.net/api/v2 ← USER LEVEL
- • API Token [api_token]: 00-55******55555 ← USER LEVEL
- • Export directory [export_dir]: /Users/<username>/Downloads/elapi ← USER LEVEL
- • App data directory: /Users/<username>/.local/share/elapi
- • Caching directory: /private/var/tmp/elapi
- • Unsafe API token use warning [unsafe_api_token_warning]: Yes ← USER LEVEL
- • Enable HTTP/2 [enable_http2]: Yes ← USER LEVEL
+• Log file path: /Users/ <username >/.local/share/elapi/elapi.log
+• Host address [host]: https://demo.elabftw.net/api/v2 ← USER LEVEL
+• API Token [api_token]: 00-55******55555 ← USER LEVEL
+• Export directory [export_dir]: /Users/ ← USER LEVEL <username >/Downloads/elapi
+• App data directory: /Users/ <username >/.local/share/elapi
+• Third-party plugins directory: /Users/ <username >/.local/share/elapi/plugins
+• Caching directory: /private/var/tmp/elapi
+• Unsafe API token use warning [unsafe_api_token_warning]: True ← USER LEVEL
+• Enable HTTP/2 [enable_http2]: False ← USER LEVEL
+• Verify SSL certificate [verify_ssl]: True ← USER LEVEL
+• Timeout duration [timeout]: 90.0 seconds ← USER LEVEL
+• Development mode [development_mode]: False ← USER LEVEL
 
 Detected configuration sources that are in use:
 
- • USER LEVEL: /Users/<username>/.config/elapi.yml
+• USER LEVEL: /Users/ <username >/.config/elapi.yml
 
 ```
 
 If both `host` and `api_token` are detected, you are good to go!
 
+### Override configuration
+
+elAPI now supports `--override/--OC` as a global option that can be used to override the configuration parameters
+as detected by `elapi show-cofig`. All plugins will also automatically listen to the overridden configuration. This can
+be useful to set certain configurations temporarily. E.g., `elapi --OC '{"timeout": 300"}' get info` will override
+the `timeout` from the configuration files.
+
 ## Usage
 
 elAPI can be invoked from the command-line.
@@ -213,19 +238,58 @@ You can also upload an attachment to an experiment.
 $ elapi experiments upload-attachment --id <experiment ID> --path <path to attachment file> --comment <comment for your attachment>
 ```
 
-### Bill teams
+### Plugins
 
-You can get a list of all teams and its users for billing purposes and export it to home directory.
+elAPI has seamless support with tight-integration for third-party plugins. A simple third-party plugin can be created in
+a few easy steps:
+
+1. Create a new subfolder under `~/.local/share/elapi/plugins` with the name for your new plugin (e.g, a folder named
+   "test")
+2. Create a `cli.py` in the subfolder with the following snippet:
+
+```python
+from elapi.plugins.commons import Typer
+
+app = Typer(name="test", help="Test plugin.")
 
-```shell
-$ elapi bill-teams teams-info --export ~
 ```
 
-Most sub-commands available under `elapi bill-teams` plugin are for Universität Heidelberg specific use-cases.
+3. Run `elapi` again to see your plugin name under `Third-party plugins` list
+
+Plugins are integrated in a way such that a plugin will **not** fail elAPI. So, even if one erroneous plugin is loaded,
+all
+other plugins and elAPI itself will remain unaffected. elAPI will show the error message on the "Message" panel.
 
-## Open-source
+If you try to import a package that is not a dependency of elAPI inside `cli.py`, your plugin will fail. In that case,
+you want to create a plugin metadata file `elapi_plugin_metadata.yml` (notice only `.yml` extension is allowed), and
+define the virtual environment that your plugin specifically requires.
 
-elAPI is open-source and published under AGPLv3 license. The repository is however hosted internally within
-Universität Heidelberg's network. The codebase can still be accessed from [PyPI](https://pypi.org/project/elapi/#files).
-If you express interest in having the repository made completely public, or if you have any question, feel free
-to [contact us](mailto:elabftw@uni-heidelberg.de).
+```python
+import requests
+
+from elapi.api import GETRequest
+from elapi.plugins.commons import Typer
+
+# Plugin metadata
+app = Typer(name="awesome", help="An awesome elAPI plugin.")
+
+
+@app.command(name="get-request", short_help=f"Make a GET request")
+def get_request(endpoint_name):
+    r = GETRequest()
+    print(r(endpoint_name).json())
+
+
+@app.command(name="get-wiki-status", short_help=f"Show status of Wikipedia")
+def wiki_status():
+    r = requests.get("https://wikipedia.org")
+    print(r)
+```
+
+And the path to virtual environment will be defined in the metadata file:
+
+```yaml
+plugin_name: test
+cli_script: ./cli.py  # Path to the cli.py script
+venv_dir: ./.venv  # Path to the virtual environment
+```

{elapi-1.0.7.dev8 → elapi-2.0.1}/pyproject.toml

@@ -1,6 +1,6 @@
 [tool.poetry]
 name = "elapi"
-version = "1.0.7.dev8"
+version = "2.0.1"
 description = "elAPI is a powerful, extensible API client for eLabFTW."
 authors = [
     "Alexander Haller, Mahadi Xion <elabftw@uni-heidelberg.de>",
@@ -10,6 +10,7 @@ maintainers = [
 ]
 readme = "README.md"
 homepage = "https://www.urz.uni-heidelberg.de/en/service-catalogue/software-and-applications/elabftw"
+repository = "https://github.com/uhd-urz/elAPI/"
 license = "AGPL-3.0-only"
 keywords = ["elabftw", "api"]
 classifiers = [
@@ -26,6 +27,9 @@ classifiers = [
     "Topic :: Utilities",
 ]
 
+[project.urls]
+Changelog = "https://github.com/uhd-urz/elAPI/blob/main/CHANGELOG.md"
+
 [tool.poetry.scripts]
 elapi = "elapi.cli.elapi:app"
 

elapi-2.0.1/src/elapi/VERSION

@@ -0,0 +1 @@
+2.0.1

{elapi-1.0.7.dev8 → elapi-2.0.1}/src/elapi/_names.py

@@ -5,8 +5,10 @@ from pathlib import Path
 # In which case, import their counterparts from src/config.py
 # name definitions
 APP_NAME: str = "elapi"
+APP_BRAND_NAME: str = "elAPI"
 LOG_FILE_NAME: str = f"{APP_NAME}.log"
-CONFIG_FILE_NAME: str = f"{APP_NAME}.yml"
+CONFIG_FILE_EXTENSION: str = "yml"
+CONFIG_FILE_NAME: str = f"{APP_NAME}.{CONFIG_FILE_EXTENSION}"
 DEFAULT_EXPORT_DATA_FORMAT: str = "json"
 user_home: Path = Path.home()
 cur_dir: Path = Path.cwd()
@@ -41,6 +43,7 @@ KEY_UNSAFE_TOKEN_WARNING: str = "UNSAFE_API_TOKEN_WARNING"
 KEY_ENABLE_HTTP2: str = "ENABLE_HTTP2"
 KEY_VERIFY_SSL: str = "VERIFY_SSL"
 KEY_TIMEOUT: str = "TIMEOUT"
+KEY_DEVELOPMENT_MODE: str = "DEVELOPMENT_MODE"
 
 # Log data directory with root permission
 LOG_DIR_ROOT: Path = Path(f"/var/log/{APP_NAME}")

{elapi-1.0.7.dev8 → elapi-2.0.1}/src/elapi/api/api.py

@@ -5,6 +5,7 @@ from typing import Union, Optional, Tuple
 from httpx import Response, Client, AsyncClient, Limits
 from httpx_auth import HeaderApiKey
 
+from .. import APP_NAME
 from ..configuration import (
     TOKEN_BEARER,
     get_active_host,
@@ -19,6 +20,9 @@ class APIRequest(ABC):
     __slots__ = "keep_session_open", "_client", "host", "api_token", "header_name"
 
     def __init__(self, keep_session_open: bool = False, **kwargs):
+        from ..utils import check_reserved_keyword
+        from .._names import CONFIG_FILE_NAME
+
         self.host: str = get_active_host()
         self.api_token: str = get_active_api_token().token
         self.header_name: str = TOKEN_BEARER
@@ -27,13 +31,23 @@ class APIRequest(ABC):
         verify_ssl = get_active_verify_ssl()
         timeout = get_active_timeout()
         _client = Client if not self.is_async_client else AsyncClient
-        self._client: Union[Client, AsyncClient] = _client(
-            auth=HeaderApiKey(api_key=self.api_token, header_name=self.header_name),
-            http2=enable_http2,
-            verify=verify_ssl,
-            timeout=timeout,
-            **kwargs,
-        )
+        try:
+            self._client: Union[Client, AsyncClient] = _client(
+                auth=HeaderApiKey(api_key=self.api_token, header_name=self.header_name),
+                http2=enable_http2,
+                verify=verify_ssl,
+                timeout=timeout,
+                **kwargs,
+            )
+        except TypeError as e:
+            check_reserved_keyword(
+                e,
+                what=f"{APP_NAME}",
+                against=f"abstract class {APIRequest.__name__}, "
+                f"so the parameter remains user-configurable "
+                f"through {CONFIG_FILE_NAME} configuration file",
+            )
+            raise e
 
     # noinspection PyMethodOverriding
     def __init_subclass__(cls, /, is_async_client: bool = False, **kwargs):