elapi 2.0.1__tar.gz → 2.1.0__tar.gz

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: elapi
-Version: 2.0.1
+Version: 2.1.0
 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
@@ -50,7 +50,7 @@ the [University Computing Centre](https://www.urz.uni-heidelberg.de/en)
 [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)
+<img src="https://heibox.uni-heidelberg.de/f/7714c7eeb0f54a3ba318/?dl=1" alt="elAPI features in a nutshell" />
 
 **Example:**
 
@@ -60,7 +60,7 @@ From [the documentation](https://doc.elabftw.net/api/v2/#/Users/read-user):
 With elAPI you can do the following:
 
 ```sh
-$ elapi get experiments -f csv --export ~/Downloads/
+$ elapi get experiments --format csv --export ~/Downloads/
 ```
 
 Once the command is run, in the background, elAPI will read host (eLab server) address, API key and various other
@@ -146,9 +146,10 @@ 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. `verify_ssl` can be turned off with `False` if you are trying
+HTTP/2 if you are making async requests with a heavy load. `verify_ssl` can be turned off with value `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.
+poor internet connection might benefit from a higher timeout number. The default timeout is `90` seconds.
 
 ### `show-config`
 
@@ -215,6 +216,13 @@ You can request a list o all active experiments and export it to a `JSON` file.
 $ elapi get experiments --export ~/Downoads/experiments.json
 ```
 
+Enable built-in syntax highlighting with `--highlight` or `-H`. Here, the following command will fetch team information
+of team with team ID 1.
+
+```shell
+$ elapi get -H teams --id 1
+```
+
 ### `POST` requests
 
 Create a new user by the name 'John Doe':

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

@@ -9,7 +9,7 @@ the [University Computing Centre](https://www.urz.uni-heidelberg.de/en)
 [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)
+<img src="https://heibox.uni-heidelberg.de/f/7714c7eeb0f54a3ba318/?dl=1" alt="elAPI features in a nutshell" />
 
 **Example:**
 
@@ -19,7 +19,7 @@ From [the documentation](https://doc.elabftw.net/api/v2/#/Users/read-user):
 With elAPI you can do the following:
 
 ```sh
-$ elapi get experiments -f csv --export ~/Downloads/
+$ elapi get experiments --format csv --export ~/Downloads/
 ```
 
 Once the command is run, in the background, elAPI will read host (eLab server) address, API key and various other
@@ -105,9 +105,10 @@ 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. `verify_ssl` can be turned off with `False` if you are trying
+HTTP/2 if you are making async requests with a heavy load. `verify_ssl` can be turned off with value `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.
+poor internet connection might benefit from a higher timeout number. The default timeout is `90` seconds.
 
 ### `show-config`
 
@@ -174,6 +175,13 @@ You can request a list o all active experiments and export it to a `JSON` file.
 $ elapi get experiments --export ~/Downoads/experiments.json
 ```
 
+Enable built-in syntax highlighting with `--highlight` or `-H`. Here, the following command will fetch team information
+of team with team ID 1.
+
+```shell
+$ elapi get -H teams --id 1
+```
+
 ### `POST` requests
 
 Create a new user by the name 'John Doe':

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

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

elapi-2.1.0/src/elapi/VERSION

@@ -0,0 +1 @@
+2.1.0

{elapi-2.0.1 → elapi-2.1.0}/src/elapi/api/api.py

@@ -22,6 +22,14 @@ class APIRequest(ABC):
     def __init__(self, keep_session_open: bool = False, **kwargs):
         from ..utils import check_reserved_keyword
         from .._names import CONFIG_FILE_NAME
+        from ..utils import missing_warning
+        from ..configuration import (
+            KEY_HOST,
+            KEY_API_TOKEN,
+            KEY_ENABLE_HTTP2,
+            KEY_VERIFY_SSL,
+            KEY_TIMEOUT,
+        )
 
         self.host: str = get_active_host()
         self.api_token: str = get_active_api_token().token
@@ -30,6 +38,15 @@ class APIRequest(ABC):
         enable_http2 = get_active_enable_http2()
         verify_ssl = get_active_verify_ssl()
         timeout = get_active_timeout()
+
+        for field in (
+            (KEY_HOST, self.host),
+            (KEY_API_TOKEN, self.api_token),
+            (KEY_ENABLE_HTTP2, enable_http2),
+            (KEY_VERIFY_SSL, verify_ssl),
+            (KEY_TIMEOUT, timeout),
+        ):
+            missing_warning(field)
         _client = Client if not self.is_async_client else AsyncClient
         try:
             self._client: Union[Client, AsyncClient] = _client(
@@ -70,6 +87,11 @@ class APIRequest(ABC):
         if not self.client.is_closed:
             self.client.close()
 
+    @abstractmethod
+    async def aclose(self):
+        if not self.client.is_closed:
+            await self.client.aclose()
+
     @abstractmethod
     def __call__(self, *args, **kwargs):
         response = self._make(*args, **kwargs)
@@ -77,6 +99,16 @@ class APIRequest(ABC):
             self.close()
         return response
 
+    @abstractmethod
+    async def __acall__(self, *args, **kwargs):
+        response = await self._make(
+            *args,
+            **kwargs,
+        )
+        if not self.keep_session_open:
+            await self.aclose()
+        return response
+
 
 class ElabFTWURLError(Exception): ...
 
@@ -266,6 +298,11 @@ class GETRequest(APIRequest):
     def close(self):
         super().close()
 
+    def aclose(self):
+        raise NotImplementedError(
+            f"{GETRequest.__name__} is not async and only supports 'close' method."
+        )
+
     def __call__(
         self,
         endpoint_name: str,
@@ -284,6 +321,12 @@ class GETRequest(APIRequest):
             **kwargs,
         )
 
+    def __acall__(self, *args, **kwargs):
+        raise NotImplementedError(
+            "__acall__ cannot be called directly. It's mainly an async"
+            " placeholder for __call__. Please use __call__ instead."
+        )
+
 
 class POSTRequest(APIRequest):
     __slots__ = ()
@@ -320,6 +363,11 @@ class POSTRequest(APIRequest):
     def close(self):
         super().close()
 
+    def aclose(self):
+        raise NotImplementedError(
+            f"{POSTRequest.__name__} is not async and only supports 'close' method."
+        )
+
     def __call__(
         self,
         endpoint_name: str,
@@ -338,6 +386,12 @@ class POSTRequest(APIRequest):
             **kwargs,
         )
 
+    def __acall__(self, *args, **kwargs):
+        raise NotImplementedError(
+            "__acall__ cannot be called directly. It's mainly an async"
+            " placeholder for __call__. Please use __call__ instead."
+        )
+
 
 class AsyncPOSTRequest(APIRequest, is_async_client=True):
     __slots__ = ()
@@ -372,9 +426,13 @@ class AsyncPOSTRequest(APIRequest, is_async_client=True):
             **kwargs,
         )
 
-    async def close(self):
-        if not self.client.is_closed:
-            await self.client.aclose()
+    async def aclose(self):
+        await super().aclose()
+
+    def close(self):
+        raise NotImplementedError(
+            f"{AsyncPOSTRequest.__name__} is async and only supports 'aclose' method."
+        )
 
     async def __call__(
         self,
@@ -385,7 +443,7 @@ class AsyncPOSTRequest(APIRequest, is_async_client=True):
         query: Optional[dict] = None,
         **kwargs,
     ) -> Response:
-        response = await self._make(
+        return await super().__acall__(
             endpoint_name,
             endpoint_id,
             sub_endpoint_name,
@@ -393,9 +451,12 @@ class AsyncPOSTRequest(APIRequest, is_async_client=True):
             query,
             **kwargs,
         )
-        if not self.keep_session_open:
-            await self.close()
-        return response
+
+    def __acall__(self, *args, **kwargs):
+        raise NotImplementedError(
+            "__acall__ cannot be called directly. It's mainly an async"
+            " placeholder for __call__. Please use __call__ instead."
+        )
 
 
 class AsyncGETRequest(APIRequest, is_async_client=True):
@@ -422,10 +483,15 @@ class AsyncGETRequest(APIRequest, is_async_client=True):
             url.get(), headers=headers or {"Accept": "application/json"}, **kwargs
         )
 
-    async def close(self):
+    async def aclose(self):
         if not self.client.is_closed:
             await self.client.aclose()
 
+    def close(self):
+        raise NotImplementedError(
+            f"{AsyncGETRequest.__name__} is async and only supports 'aclose' method."
+        )
+
     async def __call__(
         self,
         endpoint_name: str,
@@ -435,7 +501,7 @@ class AsyncGETRequest(APIRequest, is_async_client=True):
         query: Optional[dict] = None,
         **kwargs,
     ) -> Response:
-        response = await self._make(
+        return await super().__acall__(
             endpoint_name,
             endpoint_id,
             sub_endpoint_name,
@@ -443,9 +509,12 @@ class AsyncGETRequest(APIRequest, is_async_client=True):
             query,
             **kwargs,
         )
-        if not self.keep_session_open:
-            await self.close()
-        return response
+
+    def __acall__(self, *args, **kwargs):
+        raise NotImplementedError(
+            "__acall__ cannot be called directly. It's mainly an async"
+            " placeholder for __call__. Please use __call__ instead."
+        )
 
 
 class PATCHRequest(APIRequest):
@@ -476,6 +545,11 @@ class PATCHRequest(APIRequest):
     def close(self):
         super().close()
 
+    def aclose(self):
+        raise NotImplementedError(
+            f"{PATCHRequest.__name__} is not async and only supports 'close' method."
+        )
+
     def __call__(
         self,
         endpoint_name: str,
@@ -494,6 +568,12 @@ class PATCHRequest(APIRequest):
             **kwargs,
         )
 
+    def __acall__(self, *args, **kwargs):
+        raise NotImplementedError(
+            "__acall__ cannot be called directly. It's mainly an async"
+            " placeholder for __call__. Please use __call__ instead."
+        )
+
 
 class AsyncPATCHRequest(APIRequest, is_async_client=True):
     __slots__ = ()
@@ -526,10 +606,15 @@ class AsyncPATCHRequest(APIRequest, is_async_client=True):
             **kwargs,
         )
 
-    async def close(self):
+    async def aclose(self):
         if not self.client.is_closed:
             await self.client.aclose()
 
+    def close(self):
+        raise NotImplementedError(
+            f"{AsyncPATCHRequest.__name__} is async and only supports 'aclose' method."
+        )
+
     async def __call__(
         self,
         endpoint_name: str,
@@ -539,7 +624,7 @@ class AsyncPATCHRequest(APIRequest, is_async_client=True):
         query: Optional[dict] = None,
         **kwargs,
     ) -> Response:
-        response = await self._make(
+        return await super().__acall__(
             endpoint_name,
             endpoint_id,
             sub_endpoint_name,
@@ -547,9 +632,12 @@ class AsyncPATCHRequest(APIRequest, is_async_client=True):
             query,
             **kwargs,
         )
-        if not self.keep_session_open:
-            await self.close()
-        return response
+
+    def __acall__(self, *args, **kwargs):
+        raise NotImplementedError(
+            "__acall__ cannot be called directly. It's mainly an async"
+            " placeholder for __call__. Please use __call__ instead."
+        )
 
 
 class DELETERequest(APIRequest):
@@ -572,6 +660,11 @@ class DELETERequest(APIRequest):
     def close(self):
         super().close()
 
+    def aclose(self):
+        raise NotImplementedError(
+            f"{DELETERequest.__name__} is not async and only supports 'close' method."
+        )
+
     def __call__(
         self,
         endpoint_name: str,
@@ -590,6 +683,12 @@ class DELETERequest(APIRequest):
             **kwargs,
         )
 
+    def __acall__(self, *args, **kwargs):
+        raise NotImplementedError(
+            "__acall__ cannot be called directly. It's mainly an async"
+            " placeholder for __call__. Please use __call__ instead."
+        )
+
 
 class AsyncDELETERequest(APIRequest, is_async_client=True):
     __slots__ = ()
@@ -617,10 +716,15 @@ class AsyncDELETERequest(APIRequest, is_async_client=True):
             **kwargs,
         )
 
-    async def close(self):
+    async def aclose(self):
         if not self.client.is_closed:
             await self.client.aclose()
 
+    def close(self):
+        raise NotImplementedError(
+            f"{AsyncDELETERequest.__name__} is async and only supports 'aclose' method."
+        )
+
     async def __call__(
         self,
         endpoint_name: str,
@@ -630,7 +734,7 @@ class AsyncDELETERequest(APIRequest, is_async_client=True):
         query: Optional[dict] = None,
         **kwargs,
     ) -> Response:
-        response = await self._make(
+        return await super().__acall__(
             endpoint_name,
             endpoint_id,
             sub_endpoint_name,
@@ -638,6 +742,9 @@ class AsyncDELETERequest(APIRequest, is_async_client=True):
             query,
             **kwargs,
         )
-        if not self.keep_session_open:
-            await self.close()
-        return response
+
+    def __acall__(self, *args, **kwargs):
+        raise NotImplementedError(
+            "__acall__ cannot be called directly. It's mainly an async"
+            " placeholder for __call__. Please use __call__ instead."
+        )

{elapi-2.0.1 → elapi-2.1.0}/src/elapi/api/endpoint.py

@@ -82,11 +82,11 @@ class FixedAsyncEndpoint:
             query,
         )
 
-    async def close(self):
-        await self._get_session.close()
-        await self._post_session.close()
-        await self._patch_session.close()
-        await self._delete_session.close()
+    async def aclose(self):
+        await self._get_session.aclose()
+        await self._post_session.aclose()
+        await self._patch_session.aclose()
+        await self._delete_session.aclose()
 
 
 class FixedEndpoint:

{elapi-2.0.1 → elapi-2.1.0}/src/elapi/cli/doc.py

@@ -82,11 +82,11 @@ __PARAMETERS__doc__ = {
                         f"an existing file when exporting.",
     "data_format": f"Format style for the output. Supported values are: {supported_highlighting_formats}. "
               f"The values are case insensitive. The default format is `{DEFAULT_EXPORT_DATA_FORMAT.upper()}`. "
-              "When 'txt' is used, the response will be sent in *original*, un-formatted (almost), "
-              "without syntax highlighting. This can be utilized if one wishes to pipe the output "
-              " to some external formatting program like `less`. "
               "If an unsupported format value is provided then the output format "
               f"falls back to `{DEFAULT_EXPORT_DATA_FORMAT.upper()}`.",
+    "highlight_syntax": "Enable syntax highlighting for shown output if possible. Default is **False**. "
+                        "Tools like `jq` or `less` might behave erratically when syntax highlighted output "
+                        "is piped to them.",
     "verify": "SSL certificates are verified for HTTPS requests by default. Passing _'--verify False'_ will "
               "disable the verification. This can be useful during local development. You can also pass a "
               "path to SSL certificate (a.k.a CA bundle) file to --verify.",

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

@@ -12,6 +12,7 @@ documented in https://doc.elabftw.net/api/v2/ with ease.
         $ elapi get users --id <id>
 """
 
+import sys
 from functools import partial
 from typing import Optional
 
@@ -84,7 +85,6 @@ def cli_startup(
         minimal_active_configuration,
     )
     from ..configuration.config import APIToken
-    from ..configuration.validators import MainConfigurationValidator
     from ..core_validators import Exit
     from ..configuration import reinitiate_config
     from ..plugins.commons.get_data_from_input_or_path import get_structured_data
@@ -121,8 +121,7 @@ def cli_startup(
             and ctx.command.name != calling_sub_command_name
         ):
             if argv[-1] != (ARG_TO_SKIP := "--help") or ARG_TO_SKIP not in argv:
-                if override_config or not MainConfigurationValidator.ALREADY_VALIDATED:
-                    reinitiate_config()
+                reinitiate_config()
         else:
             if calling_sub_command_name in SENSITIVE_PLUGIN_NAMES:
                 if override_config:
@@ -431,6 +430,15 @@ def get(
         Optional[str],
         typer.Option("--format", "-F", help=docs["data_format"], show_default=False),
     ] = None,
+    highlight_syntax: Annotated[
+        Optional[bool],
+        typer.Option(
+            "--highlight",
+            "-H",
+            help=docs["highlight_syntax"],
+            show_default=True,
+        ),
+    ] = False,
     export: Annotated[
         Optional[bool],
         typer.Option(
@@ -581,11 +589,17 @@ def get(
                 f"{export.destination} in {export.format_name} format."
             )
     else:
-        highlight = Highlight(format.name)
-        if not raw_response.is_success:
-            stderr_console.print(highlight(formatted_data))
-            raise Exit(1)
-        stdin_console.print(highlight(formatted_data))
+        if highlight_syntax is True:
+            highlight = Highlight(format.name)
+            if not raw_response.is_success:
+                stderr_console.print(highlight(formatted_data))
+                raise Exit(1)
+            stdin_console.print(highlight(formatted_data))
+        else:
+            if not raw_response.is_success:
+                typer.echo(formatted_data, file=sys.stderr)
+                raise Exit(1)
+            typer.echo(formatted_data)
     return response_data
 
 
@@ -631,6 +645,15 @@ def post(
         str,
         typer.Option("--format", "-F", help=docs["data_format"], show_default=False),
     ] = "json",
+    highlight_syntax: Annotated[
+        Optional[bool],
+        typer.Option(
+            "--highlight",
+            "-H",
+            help=docs["highlight_syntax"],
+            show_default=True,
+        ),
+    ] = False,
     headers: Annotated[
         Optional[str],
         typer.Option("--headers", help=docs["headers"], show_default=False),
@@ -791,11 +814,17 @@ def post(
             )
             raise typer.Exit(1)
     else:
-        highlight = Highlight(format.name)
-        if not raw_response.is_success:
-            stderr_console.print(highlight(formatted_data))
-            raise typer.Exit(1)
-        stdin_console.print(highlight(formatted_data))
+        if highlight_syntax is True:
+            highlight = Highlight(format.name)
+            if not raw_response.is_success:
+                stderr_console.print(highlight(formatted_data))
+                raise Exit(1)
+            stdin_console.print(highlight(formatted_data))
+        else:
+            if not raw_response.is_success:
+                typer.echo(formatted_data, file=sys.stderr)
+                raise Exit(1)
+            typer.echo(formatted_data)
         return formatted_data
 
 
@@ -833,6 +862,15 @@ def patch(
         str,
         typer.Option("--format", "-F", help=docs["data_format"], show_default=False),
     ] = "json",
+    highlight_syntax: Annotated[
+        Optional[bool],
+        typer.Option(
+            "--highlight",
+            "-H",
+            help=docs["highlight_syntax"],
+            show_default=True,
+        ),
+    ] = False,
     headers: Annotated[
         Optional[str],
         typer.Option("--headers", help=docs["headers"], show_default=False),
@@ -936,11 +974,17 @@ def patch(
             )
             raise typer.Exit(1)
     else:
-        highlight = Highlight(format.name)
-        if not raw_response.is_success:
-            stderr_console.print(highlight(formatted_data))
-            raise typer.Exit(1)
-        stdin_console.print(highlight(formatted_data))
+        if highlight_syntax is True:
+            highlight = Highlight(format.name)
+            if not raw_response.is_success:
+                stderr_console.print(highlight(formatted_data))
+                raise Exit(1)
+            stdin_console.print(highlight(formatted_data))
+        else:
+            if not raw_response.is_success:
+                typer.echo(formatted_data, file=sys.stderr)
+                raise Exit(1)
+            typer.echo(formatted_data)
         return formatted_data
 
 
@@ -974,6 +1018,15 @@ def delete(
         str,
         typer.Option("--format", "-F", help=docs["data_format"], show_default=False),
     ] = "json",
+    highlight_syntax: Annotated[
+        Optional[bool],
+        typer.Option(
+            "--highlight",
+            "-H",
+            help=docs["highlight_syntax"],
+            show_default=True,
+        ),
+    ] = False,
     headers: Annotated[
         Optional[str],
         typer.Option("--headers", help=docs["headers"], show_default=False),
@@ -1076,11 +1129,17 @@ def delete(
             )
             raise typer.Exit(1)
     else:
-        highlight = Highlight(format.name)
-        if not raw_response.is_success:
-            stderr_console.print(highlight(formatted_data))
-            raise typer.Exit(1)
-        stdin_console.print(highlight(formatted_data))
+        if highlight_syntax is True:
+            highlight = Highlight(format.name)
+            if not raw_response.is_success:
+                stderr_console.print(highlight(formatted_data))
+                raise Exit(1)
+            stdin_console.print(highlight(formatted_data))
+        else:
+            if not raw_response.is_success:
+                typer.echo(formatted_data, file=sys.stderr)
+                raise Exit(1)
+            typer.echo(formatted_data)
         return formatted_data
 
 

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

@@ -59,3 +59,6 @@ from .overridable_vars import (
     get_active_timeout,
     get_development_mode,
 )
+
+if get_development_mode() is False:
+    reinitiate_config(ignore_essential_validation=True)