Merge pull request #164 from uhd-urz/dev

Final merge before the release.

Author: mhxion

CHANGELOG.md

@@ -5,7 +5,25 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
-## [2.4.1] - 2025-10-26
+## [2.4.2] - 2025-09-22
+
+This release brings some minor bug fixes and improvements.
+
+### Added
+
+- elAPI `whoami` that shows information about the eLab user (see [documentation](https://github.com/uhd-urz/elAPI/tree/main?tab=readme-ov-file#elapi-whoami))
+- New configuration field `async_capacity` that lets you the maximum number of in-flight requests (see [documentation](https://github.com/uhd-urz/elAPI/tree/dev?tab=readme-ov-file#configuration))
+- Improved `bill-teams` retry strategy that uses `async_capacity`
+
+### Fixed
+
+- Fix #162, #155, #19, #8
+
+### Changes
+
+- Replace HTTPX's back-end with `aiohttp`. This fixes #162. 
+
+## [2.4.1] - 2025-08-26
 
 > [!NOTE]
 > This release deprecates support for Python versions 3.9 and 3.10.
@@ -17,7 +35,7 @@ This is a hotfix release. See the [version 2.4.0 changelog](https://github.com/u
 - Rollback [httpx-limiter](https://midnighter.github.io/httpx-limiter/) to version 0.3.0. The version 0.4.0 would break elAPI support on Pyodide (see GH #160)
 
 
-## [2.4.0] - 2025-10-25
+## [2.4.0] - 2025-08-25
 
 > [!NOTE]
 > This release deprecates support for Python versions 3.9 and 3.10.

README.md

@@ -85,7 +85,9 @@ $ elapi init
 <video src='https://github.com/user-attachments/assets/8d5f69ed-b644-4d75-b816-d06d4e937105'> </video>
 <p align="center">elapi init demo</p>
 
-That's all! Run [`elapi show-config`](#show-config) to view your configuration details.
+That's all! Run [`elapi whoami`](#elapi-whoami) to see a short summary of your eLab user. Run [
+`elapi show-config`](#show-config) to view
+your configuration details.
 
 ## Compatibility
 
@@ -128,7 +130,8 @@ unsafe_api_token_warning: true
 enable_http2: false
 verify_ssl: true
 timeout: 90
-async_rate_limit: 100
+async_rate_limit: 20
+async_capacity: 500
 development_mode: false
 ```
 
@@ -144,9 +147,13 @@ development_mode: false
 - `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.
 - `async_rate_limit` controls the maximum number of requests per second (i.e., throughput) you want to make to the
-  server. Default `async_rate_limit` is `null` which is to say no limit. An eLab server might be configured to limit
+  server. The default `async_rate_limit` is `null` which means no limit. An eLab server might be configured to limit
   a high number of requests to prevent spam, `async_rate_limit` can then be set to the maximum number of requests
   allowed by the server.
+- `async_capacity` controls the maximum number of in-flight async requests. The default `async_capacity` is `null` which
+  means no limit on capacity. Both `async_rate_limit` and `async_capacity` can be used to better limit the traffic load
+  put on the server. See this [SA answer](https://stackoverflow.com/a/52100884/7696241) about how they differ from each
+  other.
 - `development_mode` can be set to `True` to show debug logs, Python traceback on the CLI instead of a clean exit, etc.
   This mode should not be turned on for production-ready scripts.
 
@@ -170,6 +177,33 @@ as detected by `elapi show-config`. All plugins will also automatically listen t
 be useful to set certain configurations temporarily. E.g., `elapi --OC '{"timeout": 300"}' get info` will override
 the `timeout` from the configuration files.
 
+## elAPI `whoami`
+
+Oftentimes, you work with multiple API tokens/keys for multiple teams on multiple eLab servers. elAPI enables robust
+workflow management with built-in [advanced configuration](#advanced-configuration) orchestration. During development
+though,
+juggling between multiple API keys can still lead to confusion as to which API key is being actually used. elAPI version
+`2.4.1` adds the `whomai` command that shows the essential information about the requesting eLab user.
+
+```shell
+$ elapi whoami
+```
+
+![elapi whoami output](https://heibox.uni-heidelberg.de/f/e3096d5659db45e58a94/?dl=1)
+
+So, if your API task requires write permission, but only `Read-only` is shown next to the API key, you know you're using
+the wrong API key. But having to run `elapi whoami` every single time for this would be cumbersome. So, we added the
+`whoami` information to the debug messages. To enable debug messages, set `development_mode` to `True` in
+the [configuration file](#configuration). Once set, before any elAPI command and plugin is run, elAPI will show the
+`whoami` information in the debug messages.
+
+```shell
+DEBUG    Based on the detected configuration, the requests will be made to the server                                         get_whoami.py:114
+         https://elabftw-dev-002.uni-heidelberg.de (eLabFTW version: 5.2.8), with API token '84-fc******2a384' (Read/Write),
+         by user 'John Doe' (ID: 2607), from team 'North Kathy' (ID: 19), in user group 'User', not as a sysadmin. Scopes:
+         experiments = 'Team', items = 'Team', experiments_templates = 'Team', teamgroups = 'Everything'
+```
+
 ## Examples and usage
 
 Check out the [examples directory](https://github.com/uhd-urz/elAPI/tree/main/examples) for some comprehensive code
@@ -270,7 +304,8 @@ $ elapi experiments upload-attachment --id <experiment ID> --path <path to attac
 
 Sometimes when a script has finished, you and your team would want to receive an email about its success/failure. elAPI
 offers a no-code solution for this: the `mail` plugin. The `mail` plugin is not enabled by default. To enable it,
-install elAPI with the optional dependency `mail`: `pip install elapi[mail]` or `uv add elapi[mail]`. [__See the wiki__](https://github.com/uhd-urz/elAPI/wiki/mail-plugin) to read more about how to configure the `mail` plugin with your
+install elAPI with the optional dependency `mail`: `pip install elapi[mail]` or `uv add elapi[mail]`. [__See the wiki
+__](https://github.com/uhd-urz/elAPI/wiki/mail-plugin) to read more about how to configure the `mail` plugin with your
 mail server configuration and trigger conditions. In a
 nutshell, the `mail` plugin will scan the logs when a script/plugin is done to look for pre-configured trigger
 conditions, and if found, it will send an email. The trigger conditions can be atomic and scope-based, i.e., an email

pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "elapi"
-version = "2.4.1"
+version = "2.4.2"
 description = "elAPI is a powerful, extensible API client for eLabFTW."
 authors = [{ name = "Alexander Haller, Mahadi Xion", email = "elabftw@uni-heidelberg.de" }]
 requires-python = ">=3.11.0,<4"
@@ -34,6 +34,7 @@ dependencies = [
     "mistune==3.1.3",
     "click>=8.1.8,<8.2",
     "httpx-limiter>=0.3.0,<0.4.0",
+    "httpx-aiohttp>=0.1.8,<0.2",
 ]
 license-files = [
     "LICENSE",

src/elapi/VERSION

@@ -1 +1 @@
-2.4.1
+2.4.2

src/elapi/_names.py

@@ -27,7 +27,6 @@
 ENV_XDG_DATA_HOME: str = "XDG_DATA_HOME"
 ENV_XDG_DOWNLOAD_DIR: str = "XDG_DOWNLOAD_DIR"
 ENV_XDG_CONFIG_HOME: str = "XDG_CONFIG_HOME"
-TMP_DIR: Path = Path(f"/var/tmp/{APP_NAME}")
 
 # Fallback definitions
 FALLBACK_DIR: Path = user_home / ".local/share" / APP_NAME
@@ -48,6 +47,7 @@
 KEY_EXPORT_DIR: str = "EXPORT_DIR"
 KEY_UNSAFE_TOKEN_WARNING: str = "UNSAFE_API_TOKEN_WARNING"
 KEY_ENABLE_HTTP2: str = "ENABLE_HTTP2"
+KEY_ASYNC_CAPACITY: str = "ASYNC_CAPACITY"
 KEY_VERIFY_SSL: str = "VERIFY_SSL"
 KEY_TIMEOUT: str = "TIMEOUT"
 KEY_ASYNC_RATE_LIMIT: str = "ASYNC_RATE_LIMIT"

src/elapi/api/__init__.py

@@ -1,18 +1,36 @@
-# ruff: noqa: F401
+__all__ = [
+    "SessionDefaults",
+    "SimpleClient",
+    "GlobalSharedSession",
+    "APIRequest",
+    "ElabFTWURLError",
+    "ElabFTWURL",
+    "GETRequest",
+    "AsyncGETRequest",
+    "POSTRequest",
+    "AsyncPOSTRequest",
+    "PATCHRequest",
+    "AsyncPATCHRequest",
+    "DELETERequest",
+    "AsyncDELETERequest",
+    "FixedEndpoint",
+    "FixedAsyncEndpoint",
+]
+
 from .api import (
-    SessionDefaults,
-    SimpleClient,
-    GlobalSharedSession,
     APIRequest,
-    ElabFTWURLError,
-    ElabFTWURL,
-    GETRequest,
+    AsyncDELETERequest,
     AsyncGETRequest,
-    POSTRequest,
-    AsyncPOSTRequest,
-    PATCHRequest,
     AsyncPATCHRequest,
+    AsyncPOSTRequest,
     DELETERequest,
-    AsyncDELETERequest,
+    ElabFTWURL,
+    ElabFTWURLError,
+    GETRequest,
+    GlobalSharedSession,
+    PATCHRequest,
+    POSTRequest,
+    SessionDefaults,
+    SimpleClient,
 )
-from .endpoint import FixedEndpoint, FixedAsyncEndpoint
+from .endpoint import FixedAsyncEndpoint, FixedEndpoint