elapi 2.0.0__tar.gz → 2.0.1__tar.gz

{elapi-2.0.0 → elapi-2.0.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: elapi
-Version: 2.0.0
+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
@@ -41,16 +41,16 @@ Description-Content-Type: text/markdown
 
 # elAPI
 
-<a href="https://pypi.org/project/elapi/">
-    <img src="https://badge.fury.io/py/elapi.svg" alt="Package version">
-</a>
-<br />
-<br />
+[![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
+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.
+[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:**
 
@@ -60,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
@@ -128,7 +133,7 @@ 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: true
 enable_http2: false
@@ -279,8 +284,8 @@ $ elapi experiments upload-attachment --id <experiment ID> --path <path to attac
 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")
+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

{elapi-2.0.0 → elapi-2.0.1}/README.md

@@ -1,15 +1,15 @@
 # elAPI
 
-<a href="https://pypi.org/project/elapi/">
-    <img src="https://badge.fury.io/py/elapi.svg" alt="Package version">
-</a>
-<br />
-<br />
+[![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
+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.
+[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:**
 
@@ -19,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
@@ -87,7 +92,7 @@ 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: true
 enable_http2: false
@@ -238,8 +243,8 @@ $ elapi experiments upload-attachment --id <experiment ID> --path <path to attac
 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")
+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

{elapi-2.0.0 → elapi-2.0.1}/pyproject.toml

@@ -1,6 +1,6 @@
 [tool.poetry]
 name = "elapi"
-version = "2.0.0"
+version = "2.0.1"
 description = "elAPI is a powerful, extensible API client for eLabFTW."
 authors = [
     "Alexander Haller, Mahadi Xion <elabftw@uni-heidelberg.de>",

elapi-2.0.1/src/elapi/VERSION

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

{elapi-2.0.0 → elapi-2.0.1}/src/elapi/cli/_plugin_handler.py

@@ -82,25 +82,47 @@ class ExternalPluginLocationValidator(Validator):
         import os
         import yaml
         from ..configuration import (
+            APP_BRAND_NAME,
             EXTERNAL_LOCAL_PLUGIN_METADATA_FILE_NAME,
             EXTERNAL_LOCAL_PLUGIN_TYPER_APP_FILE_NAME,
             EXTERNAL_LOCAL_PLUGIN_METADATA_FILE_KEY_FILE_EXISTS,
             EXTERNAL_LOCAL_PLUGIN_METADATA_FILE_KEY_CLI_SCRIPT_PATH,
             EXTERNAL_LOCAL_PLUGIN_METADATA_FILE_KEY_VENV_PATH,
             EXTERNAL_LOCAL_PLUGIN_METADATA_FILE_KEY_PLUGIN_NAME,
+            EXTERNAL_LOCAL_PLUGIN_METADATA_FILE_NAME_PREFIX,
             CANON_YAML_EXTENSION,
+            CONFIG_FILE_EXTENSION,
         )
 
+        _CANON_PLUGIN_METADATA_FILE_NAME: str = (
+            f"{EXTERNAL_LOCAL_PLUGIN_METADATA_FILE_NAME_PREFIX}.{CANON_YAML_EXTENSION}"
+        )
         parsed_metadata: dict = {
             EXTERNAL_LOCAL_PLUGIN_METADATA_FILE_KEY_FILE_EXISTS: None,
             EXTERNAL_LOCAL_PLUGIN_METADATA_FILE_KEY_CLI_SCRIPT_PATH: None,
-            # EXTERNAL_LOCAL_PLUGIN_METADATA_FILE_KEY_VENV_PATH: None,
             EXTERNAL_LOCAL_PLUGIN_METADATA_FILE_KEY_PLUGIN_NAME: None,
         }
 
         if self.location.is_dir():
             actual_cwd = Path.cwd()
             os.chdir(self.location)
+            if (
+                _canon_plugin_metadata_file := (
+                    self.location / _CANON_PLUGIN_METADATA_FILE_NAME
+                )
+            ).exists():
+                import logging
+
+                message = (
+                    f"File '{_canon_plugin_metadata_file.name}' detected in location {_canon_plugin_metadata_file}. "
+                    f"If it is meant to be an {APP_BRAND_NAME} plugin metadata file, "
+                    f"please rename the file extension from '{CANON_YAML_EXTENSION}' "
+                    f"to '{CONFIG_FILE_EXTENSION}'. "
+                    f"{APP_BRAND_NAME} only supports '{CONFIG_FILE_EXTENSION}' "
+                    f"as file extension for plugin metadata files."
+                )
+                add_message(message, logging.INFO)
+
             if (
                 plugin_metadata_file := (
                     self.location / EXTERNAL_LOCAL_PLUGIN_METADATA_FILE_NAME
@@ -136,7 +158,7 @@ class ExternalPluginLocationValidator(Validator):
                         else:
                             try:
                                 CLI_SCRIPT_PATH = ProperPath(CLI_SCRIPT_PATH)
-                            except ValueError:
+                            except (TypeError, ValueError):
                                 raise ValidationError(
                                     f"Key '{EXTERNAL_LOCAL_PLUGIN_METADATA_FILE_KEY_CLI_SCRIPT_PATH}' "
                                     f"exists in {plugin_metadata_file}, but its assigned "
@@ -164,7 +186,7 @@ class ExternalPluginLocationValidator(Validator):
                         else:
                             try:
                                 VENV_PATH = ProperPath(VENV_PATH)
-                            except ValueError:
+                            except (TypeError, ValueError):
                                 raise ValidationError(
                                     f"Key '{EXTERNAL_LOCAL_PLUGIN_METADATA_FILE_KEY_VENV_PATH}' "
                                     f"exists in {plugin_metadata_file}, but its assigned "

{elapi-2.0.0 → elapi-2.0.1}/src/elapi/cli/_venv_state_manager.py

@@ -6,7 +6,7 @@ from ..path import ProperPath
 VENV_INDICATOR_DIR_NAME: str = "site-packages"
 
 
-def switch_venv_state(status: bool, /, venv_dir: Union[Path, ProperPath]):
+def switch_venv_state(state: bool, /, venv_dir: Union[Path, ProperPath]):
     import sys
 
     site_packages = sorted(
@@ -20,7 +20,7 @@ def switch_venv_state(status: bool, /, venv_dir: Union[Path, ProperPath]):
         )
     for unique_dir in site_packages:
         unique_dir = str(unique_dir)
-        if status is True:
+        if state is True:
             sys.path.insert(1, unique_dir)
             return
         else:

{elapi-2.0.0 → elapi-2.0.1}/src/elapi/cli/elapi.py

@@ -135,6 +135,21 @@ def cli_startup(
                     reinitiate_config(ignore_essential_validation=True)
 
 
+def cli_switch_venv_state(state: bool, /) -> None:
+    import click
+    from ._venv_state_manager import switch_venv_state
+
+    try:
+        venv_dir = EXTERNAL_LOCAL_PLUGIN_NAME_REGISTRY[
+            click.get_current_context().command.name
+        ].venv
+    except KeyError:
+        ...
+    else:
+        if venv_dir is not None:
+            switch_venv_state(state, venv_dir)
+
+
 def cli_startup_for_plugins(
     override_config: Annotated[
         Optional[str],
@@ -147,21 +162,10 @@ def cli_startup_for_plugins(
         ),
     ] = None,
 ):
-    import click
     from ..styles import print_typer_error
     from ..validators import Exit
-    from ._venv_state_manager import switch_venv_state
-
-    try:
-        switch_venv_state(
-            True,
-            EXTERNAL_LOCAL_PLUGIN_NAME_REGISTRY[
-                click.get_current_context().command.name
-            ].venv,
-        )
-    except KeyError:
-        ...
 
+    cli_switch_venv_state(True)
     if override_config is not None:
         print_typer_error(
             f"--override-config/--OC can only be passed after "
@@ -172,18 +176,7 @@ def cli_startup_for_plugins(
 
 
 def cli_cleanup_for_third_party_plugins(*args, override_config=None):
-    import click
-    from ._venv_state_manager import switch_venv_state
-
-    try:
-        switch_venv_state(
-            False,
-            EXTERNAL_LOCAL_PLUGIN_NAME_REGISTRY[
-                click.get_current_context().command.name
-            ].venv,
-        )
-    except KeyError:
-        ...
+    cli_switch_venv_state(False)
 
 
 for _app in internal_plugin_typer_apps:

{elapi-2.0.0 → elapi-2.0.1}/src/elapi/configuration/__init__.py

@@ -30,6 +30,7 @@ from .config import (
     ENABLE_HTTP2,
     DEVELOPMENT_MODE,
     TMP_DIR,
+    CONFIG_FILE_EXTENSION,
     CANON_YAML_EXTENSION,
     EXTERNAL_LOCAL_PLUGIN_DIRECTORY_NAME,
     EXTERNAL_LOCAL_PLUGIN_DIR,

{elapi-2.0.0 → elapi-2.0.1}/src/elapi/configuration/config.py

@@ -65,7 +65,7 @@ for path in [
     if path.exists():
         message = (
             f"File '{_CANON_CONFIG_FILE_NAME}' detected in location {path}. "
-            f"If it is meant to be {APP_NAME} configuration file, "
+            f"If it is meant to be an {APP_NAME} configuration file, "
             f"please rename the file extension from '{CANON_YAML_EXTENSION}' "
             f"to '{CONFIG_FILE_EXTENSION}'. {APP_NAME} only supports '{CONFIG_FILE_EXTENSION}' "
             f"as file extension for configuration files."

elapi-2.0.0/src/elapi/VERSION

@@ -1 +0,0 @@
-2.0.0