elapi 1.0.7.dev3__tar.gz → 1.0.7.dev5__tar.gz

{elapi-1.0.7.dev3 → elapi-1.0.7.dev5}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: elapi
-Version: 1.0.7.dev3
+Version: 1.0.7.dev5
 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
@@ -27,12 +27,12 @@ Classifier: Topic :: Software Development :: Libraries :: Python Modules
 Classifier: Topic :: System :: Systems Administration
 Classifier: Topic :: Utilities
 Requires-Dist: dynaconf (>=3.2.0,<4.0.0)
+Requires-Dist: h2 (>=4.1.0,<5.0.0)
 Requires-Dist: httpx (>=0.24.1,<0.25.0)
 Requires-Dist: httpx-auth (>=0.17.0,<0.18.0)
 Requires-Dist: mistune (>=3.0.2,<4.0.0)
-Requires-Dist: python-dateutil (>=2.8.2,<3.0.0)
 Requires-Dist: pyyaml (>=6.0.1,<7.0.0)
-Requires-Dist: tenacity (>=8.2.3,<9.0.0)
+Requires-Dist: tenacity (>=8.4.2,<9.0.0)
 Requires-Dist: typer[all] (>=0.9.0,<0.10.0)
 Description-Content-Type: text/markdown
 
@@ -111,7 +111,7 @@ configuration file present in the currently active directory has the highest pri
 directory has the lowest.
 
 The following parameters are currently configurable, with `host` and `api_token` being the required fields. For testing
-purposes it would be safe to store everything in `$HOME/.config/elapi.yml`.
+purposes, it would be safe to store everything in `$HOME/.config/elapi.yml`.
 
 ```yaml
 # elAPI configuration
@@ -124,12 +124,42 @@ api_token: <token with at least read-access>
 # 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
 ```
 
-You can get an overview of detected configurations.
+`export_dir` is where elAPI will export response content to if no path is provided to `--export/-E`.
+When `unsafe_api_token_warning` is `True`, elAPI will show a warning if you're storing `elapi.yml` in the current
+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.
+
+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.
 
 ```shell
 $ elapi show-config
+
+
+                                                       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
+
+Detected configuration sources that are in use:
+
+ • USER LEVEL: /Users/<username>/.config/elapi.yml
+
 ```
 
 If both `host` and `api_token` are detected, you are good to go!

{elapi-1.0.7.dev3 → elapi-1.0.7.dev5}/README.md

@@ -73,7 +73,7 @@ configuration file present in the currently active directory has the highest pri
 directory has the lowest.
 
 The following parameters are currently configurable, with `host` and `api_token` being the required fields. For testing
-purposes it would be safe to store everything in `$HOME/.config/elapi.yml`.
+purposes, it would be safe to store everything in `$HOME/.config/elapi.yml`.
 
 ```yaml
 # elAPI configuration
@@ -86,12 +86,42 @@ api_token: <token with at least read-access>
 # 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
 ```
 
-You can get an overview of detected configurations.
+`export_dir` is where elAPI will export response content to if no path is provided to `--export/-E`.
+When `unsafe_api_token_warning` is `True`, elAPI will show a warning if you're storing `elapi.yml` in the current
+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.
+
+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.
 
 ```shell
 $ elapi show-config
+
+
+                                                       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
+
+Detected configuration sources that are in use:
+
+ • USER LEVEL: /Users/<username>/.config/elapi.yml
+
 ```
 
 If both `host` and `api_token` are detected, you are good to go!

{elapi-1.0.7.dev3 → elapi-1.0.7.dev5}/pyproject.toml

@@ -1,6 +1,6 @@
 [tool.poetry]
 name = "elapi"
-version = "1.0.7.dev3"
+version = "1.0.7.dev5"
 description = "elAPI is a powerful, extensible API client for eLabFTW."
 authors = [
     "Alexander Haller, Mahadi Xion <elabftw@uni-heidelberg.de>",
@@ -36,9 +36,18 @@ httpx = "^0.24.1"
 httpx-auth = "^0.17.0"
 typer = { extras = ["all"], version = "^0.9.0" }
 pyyaml = "^6.0.1"
-python-dateutil = "^2.8.2"
-tenacity = "^8.2.3"
 mistune = "^3.0.2"
+h2 = "^4.1.0"
+tenacity = "^8.4.2"
+
+[project.optional-dependencies]
+uhd-urz = ["python-dateutil=^2.8.2", "tenacity=^8.2.3"]
+
+[tool.poetry.group.uhd-urz]
+optional = true
+
+[tool.poetry.group.uhd-urz.dependencies]
+python-dateutil = "^2.8.2"
 
 [tool.poetry.group.dev.dependencies]
 ptpython = "^3.0.23"

elapi-1.0.7.dev5/src/elapi/VERSION

@@ -0,0 +1 @@
+1.0.7.dev5

{elapi-1.0.7.dev3 → elapi-1.0.7.dev5}/src/elapi/_names.py

@@ -38,6 +38,9 @@ KEY_HOST: str = "HOST"
 KEY_API_TOKEN: str = "API_TOKEN"
 KEY_EXPORT_DIR: str = "EXPORT_DIR"
 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"
 
 # Log data directory with root permission
 LOG_DIR_ROOT: Path = Path(f"/var/log/{APP_NAME}")

elapi-1.0.7.dev5/src/elapi/api/__init__.py

@@ -0,0 +1,15 @@
+# ruff: noqa: F401
+from .api import (
+    APIRequest,
+    ElabFTWURLError,
+    ElabFTWURL,
+    GETRequest,
+    AsyncGETRequest,
+    POSTRequest,
+    AsyncPOSTRequest,
+    PATCHRequest,
+    AsyncPATCHRequest,
+    DELETERequest,
+    AsyncDELETERequest,
+)
+from .endpoint import FixedEndpoint, FixedAsyncEndpoint

{elapi-1.0.7.dev3/src/elapi → elapi-1.0.7.dev5/src/elapi/api}/api.py

@@ -5,21 +5,33 @@ from typing import Union, Optional, Tuple
 from httpx import Response, Client, AsyncClient, Limits
 from httpx_auth import HeaderApiKey
 
-from .configuration import API_TOKEN, TOKEN_BEARER, HOST
+from ..configuration import (
+    TOKEN_BEARER,
+    get_active_host,
+    get_active_api_token,
+    get_active_enable_http2,
+    get_active_verify_ssl,
+    get_active_timeout,
+)
 
 
 class APIRequest(ABC):
-    __slots__ = "keep_session_open", "_client"
-    host: str = HOST
-    api_token: str = API_TOKEN
-    header_name: str = TOKEN_BEARER
+    __slots__ = "keep_session_open", "_client", "host", "api_token", "header_name"
 
     def __init__(self, keep_session_open: bool = False, **kwargs):
+        self.host: str = get_active_host()
+        self.api_token: str = get_active_api_token().token
+        self.header_name: str = TOKEN_BEARER
         self.keep_session_open = keep_session_open
+        enable_http2 = get_active_enable_http2()
+        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),
-            verify=True,
+            http2=enable_http2,
+            verify=verify_ssl,
+            timeout=timeout,
             **kwargs,
         )
 
@@ -94,13 +106,15 @@ class ElabFTWURL:
             "experiments_status",
             "items_status",
             "teamgroups",
+            "tags",
         ),
         "todolist": (),
         "unfinished_steps": (),
         "users": ("notifications",),
         "idps": (),
+        "import": (),
+        "exports": (),
     }
-    host = APIRequest.host
 
     def __init__(
         self,
@@ -116,6 +130,18 @@ class ElabFTWURL:
         self.sub_endpoint_id = sub_endpoint_id
         self.query = query
 
+    @property
+    def host(self) -> str:
+        return get_active_host()
+
+    @host.setter
+    def host(self, value):
+        raise AttributeError("Host value cannot be modified!")
+
+    @host.deleter
+    def host(self):
+        raise AttributeError("Host cannot be deleted!")
+
     @property
     def endpoint_name(self) -> str:
         return self._endpoint_name
@@ -138,10 +164,19 @@ class ElabFTWURL:
     @sub_endpoint_name.setter
     def sub_endpoint_name(self, value: str):
         if value is not None:
-            if value.lower() not in ElabFTWURL.VALID_ENDPOINTS[self.endpoint_name]:
+            if value.lower() not in (
+                valid_sub_endpoint_name := ElabFTWURL.VALID_ENDPOINTS[
+                    self.endpoint_name
+                ]
+            ):
+                if not valid_sub_endpoint_name:
+                    raise ElabFTWURLError(
+                        f"Endpoint '{self._endpoint_name}' does not have any sub-endpoint!"
+                    )
+
                 raise ElabFTWURLError(
                     f"A Sub-endpoint for endpoint '{self._endpoint_name}' must be "
-                    f"one of valid eLabFTW sub-endpoints: {', '.join(ElabFTWURL.VALID_ENDPOINTS[self.endpoint_name])}."
+                    f"one of valid eLabFTW sub-endpoints: {', '.join(valid_sub_endpoint_name)}."
                 )
             self._sub_endpoint_name = value
         else:
@@ -154,7 +189,7 @@ class ElabFTWURL:
     @endpoint_id.setter
     def endpoint_id(self, value):
         if value is not None:
-            if not re.match(r"^(\d+)$|^(me)$", value := str(value)):
+            if not re.match(r"^(\d+)$|^(me)$|^(current)$", value := str(value)):
                 # Although, eLabFTW primarily supports integer-only IDs, there are exceptions, like the alias
                 # ID "me" for receiving one's own user information.
                 raise ElabFTWURLError("Invalid endpoint ID (or entity ID).")
@@ -173,7 +208,7 @@ class ElabFTWURL:
                 "Sub-endpoint ID cannot be defined without first specifying its sub-endpoint name."
             )
         if value is not None:
-            if not re.match(r"^(\d+)$|^(me)$", value := str(value)):
+            if not re.match(r"^(\d+)$|^(me)$|^(current)$", value := str(value)):
                 raise ElabFTWURLError("Invalid sub-endpoint ID (or entity sub-ID).")
             self._sub_endpoint_id = value
         else:
@@ -191,7 +226,7 @@ class ElabFTWURL:
 
     def get(self) -> str:
         url = (
-            f"{ElabFTWURL.host}/{self.endpoint_name}/{self.endpoint_id}/"
+            f"{self.host}/{self.endpoint_name}/{self.endpoint_id}/"
             f"{self.sub_endpoint_name}/{self.sub_endpoint_id}"
         ).rstrip("/")
         if self.query:
@@ -205,12 +240,14 @@ class GETRequest(APIRequest):
     def __init__(self, **kwargs):
         super().__init__(**kwargs)
 
-    def _make(self, *args) -> Response:
+    def _make(self, *args, headers: Optional[dict] = None, **kwargs) -> Response:
         endpoint_name, endpoint_id, sub_endpoint_name, sub_endpoint_id, query = args
         url = ElabFTWURL(
             endpoint_name, endpoint_id, sub_endpoint_name, sub_endpoint_id, query
         )
-        return super().client.get(url.get(), headers={"Accept": "application/json"})
+        return super().client.get(
+            url.get(), headers=headers or {"Accept": "application/json"}, **kwargs
+        )
 
     def close(self):
         super().close()
@@ -222,9 +259,15 @@ class GETRequest(APIRequest):
         sub_endpoint_name: Optional[str] = None,
         sub_endpoint_id: Union[int, str, None] = None,
         query: Optional[dict] = None,
+        **kwargs,
     ) -> Response:
         return super().__call__(
-            endpoint_name, endpoint_id, sub_endpoint_name, sub_endpoint_id, query
+            endpoint_name,
+            endpoint_id,
+            sub_endpoint_name,
+            sub_endpoint_id,
+            query,
+            **kwargs,
         )
 
 
@@ -234,7 +277,7 @@ class POSTRequest(APIRequest):
     def __init__(self, **kwargs):
         super().__init__(**kwargs)
 
-    def _make(self, *args, **kwargs) -> Response:
+    def _make(self, *args, headers: Optional[dict] = None, **kwargs) -> Response:
         endpoint_name, endpoint_id, sub_endpoint_name, sub_endpoint_id, query = args
         url = ElabFTWURL(
             endpoint_name, endpoint_id, sub_endpoint_name, sub_endpoint_id, query
@@ -246,7 +289,8 @@ class POSTRequest(APIRequest):
         files = kwargs.pop("files", None)
         return super().client.post(
             url.get(),
-            headers={
+            headers=headers
+            or {
                 "Accept": "*/*",
                 # If json argument isn't empty, '"Content-Type": "application/json"' is automatically set.
                 # '"Content-Type": "multipart/form-data"', takes no effect, and
@@ -284,16 +328,19 @@ class POSTRequest(APIRequest):
 class AsyncPOSTRequest(APIRequest, is_async_client=True):
     __slots__ = ()
 
-    def __init__(self, **kwargs):
+    def __init__(
+        self,
+        limits=Limits(
+            max_connections=100, max_keepalive_connections=30, keepalive_expiry=60
+        ),
+        **kwargs,
+    ):
         super().__init__(
-            timeout=180,
-            limits=Limits(
-                max_connections=100, max_keepalive_connections=30, keepalive_expiry=60
-            ),
+            limits=limits,
             **kwargs,
         )
 
-    async def _make(self, *args, **kwargs) -> Response:
+    async def _make(self, *args, headers: Optional[dict] = None, **kwargs) -> Response:
         endpoint_name, endpoint_id, sub_endpoint_name, sub_endpoint_id, query = args
         url = ElabFTWURL(
             endpoint_name, endpoint_id, sub_endpoint_name, sub_endpoint_id, query
@@ -305,7 +352,7 @@ class AsyncPOSTRequest(APIRequest, is_async_client=True):
         files = kwargs.pop("files", None)
         return await super().client.post(
             url.get(),
-            headers={"Accept": "*/*"},
+            headers=headers or {"Accept": "*/*"},
             json=data,
             files=files,
             **kwargs,
@@ -340,23 +387,25 @@ class AsyncPOSTRequest(APIRequest, is_async_client=True):
 class AsyncGETRequest(APIRequest, is_async_client=True):
     __slots__ = ()
 
-    def __init__(self, **kwargs):
+    def __init__(
+        self,
+        limits=Limits(
+            max_connections=100, max_keepalive_connections=30, keepalive_expiry=60
+        ),
+        **kwargs,
+    ):
         super().__init__(
-            timeout=180,
-            limits=Limits(
-                max_connections=100, max_keepalive_connections=30, keepalive_expiry=60
-            ),
+            limits=limits,
             **kwargs,
         )
 
-    async def _make(self, *args) -> Response:
+    async def _make(self, *args, headers: Optional[dict] = None, **kwargs) -> Response:
         endpoint_name, endpoint_id, sub_endpoint_name, sub_endpoint_id, query = args
         url = ElabFTWURL(
             endpoint_name, endpoint_id, sub_endpoint_name, sub_endpoint_id, query
         )
         return await super().client.get(
-            url.get(),
-            headers={"Accept": "application/json"},
+            url.get(), headers=headers or {"Accept": "application/json"}, **kwargs
         )
 
     async def close(self):
@@ -370,9 +419,15 @@ class AsyncGETRequest(APIRequest, is_async_client=True):
         sub_endpoint_name: Optional[str] = None,
         sub_endpoint_id: Union[int, str, None] = None,
         query: Optional[dict] = None,
+        **kwargs,
     ) -> Response:
         response = await self._make(
-            endpoint_name, endpoint_id, sub_endpoint_name, sub_endpoint_id, query
+            endpoint_name,
+            endpoint_id,
+            sub_endpoint_name,
+            sub_endpoint_id,
+            query,
+            **kwargs,
         )
         if not self.keep_session_open:
             await self.close()
@@ -385,7 +440,7 @@ class PATCHRequest(APIRequest):
     def __init__(self, **kwargs):
         super().__init__(**kwargs)
 
-    def _make(self, *args, **kwargs) -> Response:
+    def _make(self, *args, headers: Optional[dict] = None, **kwargs) -> Response:
         endpoint_name, endpoint_id, sub_endpoint_name, sub_endpoint_id, query = args
         url = ElabFTWURL(
             endpoint_name, endpoint_id, sub_endpoint_name, sub_endpoint_id, query
@@ -396,7 +451,8 @@ class PATCHRequest(APIRequest):
         }
         return super().client.patch(
             url.get(),
-            headers={
+            headers=headers
+            or {
                 "Accept": "application/json"
             },  # '"Content-Type": "application/json"' is passed automatically when json argument is passed.
             json=data,
@@ -428,16 +484,19 @@ class PATCHRequest(APIRequest):
 class AsyncPATCHRequest(APIRequest, is_async_client=True):
     __slots__ = ()
 
-    def __init__(self, **kwargs):
+    def __init__(
+        self,
+        limits=Limits(
+            max_connections=100, max_keepalive_connections=30, keepalive_expiry=60
+        ),
+        **kwargs,
+    ):
         super().__init__(
-            timeout=180,
-            limits=Limits(
-                max_connections=100, max_keepalive_connections=30, keepalive_expiry=60
-            ),
+            limits=limits,
             **kwargs,
         )
 
-    async def _make(self, *args, **kwargs) -> Response:
+    async def _make(self, *args, headers: Optional[dict] = None, **kwargs) -> Response:
         endpoint_name, endpoint_id, sub_endpoint_name, sub_endpoint_id, query = args
         url = ElabFTWURL(
             endpoint_name, endpoint_id, sub_endpoint_name, sub_endpoint_id, query
@@ -448,7 +507,7 @@ class AsyncPATCHRequest(APIRequest, is_async_client=True):
         }
         return await super().client.patch(
             url.get(),
-            headers={"Accept": "application/json"},
+            headers=headers or {"Accept": "application/json"},
             json=data,
             **kwargs,
         )
@@ -485,13 +544,15 @@ class DELETERequest(APIRequest):
     def __init__(self, **kwargs):
         super().__init__(**kwargs)
 
-    def _make(self, *args) -> Response:
+    def _make(self, *args, headers: Optional[dict] = None, **kwargs) -> Response:
         endpoint_name, endpoint_id, sub_endpoint_name, sub_endpoint_id, query = args
         url = ElabFTWURL(
             endpoint_name, endpoint_id, sub_endpoint_name, sub_endpoint_id, query
         )
         return super().client.delete(
-            url.get(), headers={"Accept": "*/*", "Content-Type": "application/json"}
+            url.get(),
+            headers=headers or {"Accept": "*/*", "Content-Type": "application/json"},
+            **kwargs,
         )
 
     def close(self):
@@ -504,32 +565,42 @@ class DELETERequest(APIRequest):
         sub_endpoint_name: Optional[str] = None,
         sub_endpoint_id: Union[int, str, None] = None,
         query: Optional[dict] = None,
+        **kwargs,
     ) -> Response:
         return super().__call__(
-            endpoint_name, endpoint_id, sub_endpoint_name, sub_endpoint_id, query
+            endpoint_name,
+            endpoint_id,
+            sub_endpoint_name,
+            sub_endpoint_id,
+            query,
+            **kwargs,
         )
 
 
 class AsyncDELETERequest(APIRequest, is_async_client=True):
     __slots__ = ()
 
-    def __init__(self, **kwargs):
+    def __init__(
+        self,
+        limits=Limits(
+            max_connections=100, max_keepalive_connections=30, keepalive_expiry=60
+        ),
+        **kwargs,
+    ):
         super().__init__(
-            timeout=180,
-            limits=Limits(
-                max_connections=100, max_keepalive_connections=30, keepalive_expiry=60
-            ),
+            limits=limits,
             **kwargs,
         )
 
-    async def _make(self, *args) -> Response:
+    async def _make(self, *args, headers: Optional[dict] = None, **kwargs) -> Response:
         endpoint_name, endpoint_id, sub_endpoint_name, sub_endpoint_id, query = args
         url = ElabFTWURL(
             endpoint_name, endpoint_id, sub_endpoint_name, sub_endpoint_id, query
         )
         return await super().client.delete(
             url.get(),
-            headers={"Accept": "*/*", "Content-Type": "application/json"},
+            headers=headers or {"Accept": "*/*", "Content-Type": "application/json"},
+            **kwargs,
         )
 
     async def close(self):
@@ -543,9 +614,15 @@ class AsyncDELETERequest(APIRequest, is_async_client=True):
         sub_endpoint_name: Optional[str] = None,
         sub_endpoint_id: Union[int, str, None] = None,
         query: Optional[dict] = None,
+        **kwargs,
     ) -> Response:
         response = await self._make(
-            endpoint_name, endpoint_id, sub_endpoint_name, sub_endpoint_id, query
+            endpoint_name,
+            endpoint_id,
+            sub_endpoint_name,
+            sub_endpoint_id,
+            query,
+            **kwargs,
         )
         if not self.keep_session_open:
             await self.close()