elapi 2.3.2__tar.gz → 2.4.0__tar.gz

{elapi-2.3.2 → elapi-2.4.0}/PKG-INFO

@@ -1,16 +1,14 @@
 Metadata-Version: 2.4
 Name: elapi
-Version: 2.3.2
+Version: 2.4.0
 Summary: elAPI is a powerful, extensible API client for eLabFTW.
-Project-URL: Homepage, https://www.urz.uni-heidelberg.de/de/service-katalog/software-und-anwendungen/elabftw
-Project-URL: Repository, https://github.com/uhd-urz/elAPI.git
-Project-URL: Issues, https://github.com/uhd-urz/elAPI/issues
-Project-URL: Changelog, https://github.com/uhd-urz/elAPI/blob/main/CHANGELOG.md
-Author-email: "Alexander Haller, Mahadi Xion" <elabftw@uni-heidelberg.de>
-Maintainer-email: Mahadi Xion <mahadi.xion@urz.uni-heidelberg.de>
+Keywords: elabftw,api
+Author: Alexander Haller, Mahadi Xion
+Author-email: Alexander Haller, Mahadi Xion <elabftw@uni-heidelberg.de>
 License-Expression: AGPL-3.0-only
 License-File: LICENSE
-Keywords: api,elabftw
+License-File: src/elapi/_vendor/__init__.py
+License-File: src/elapi/_vendor/haggis/LICENSE
 Classifier: Development Status :: 5 - Production/Stable
 Classifier: Framework :: AnyIO
 Classifier: Framework :: AsyncIO
@@ -22,20 +20,30 @@ Classifier: Topic :: Internet :: WWW/HTTP
 Classifier: Topic :: Software Development :: Libraries :: Python Modules
 Classifier: Topic :: System :: Systems Administration
 Classifier: Topic :: Utilities
-Requires-Python: <4,>=3.9.0
-Requires-Dist: click<8.2,>=8.1.8
-Requires-Dist: dynaconf<4,>=3.2.0
-Requires-Dist: h2<5,>=4.1.0
-Requires-Dist: httpx-auth<0.18,>=0.17.0
-Requires-Dist: httpx<0.25,>=0.24.1
-Requires-Dist: mistune<4,>=3.0.2
-Requires-Dist: pyyaml<7,>=6.0.1
-Requires-Dist: rich<14,>=13.8.0
-Requires-Dist: typer[all]<0.10,>=0.9.0
+Requires-Dist: dynaconf>=3.2.0,<4
+Requires-Dist: httpx[http2]>=0.28.1,<0.29
+Requires-Dist: httpx-auth>=0.23.1,<0.24
+Requires-Dist: rich>=13.8.0,<14
+Requires-Dist: typer[all]>=0.9.0,<0.10
+Requires-Dist: pyyaml==6.0.2
+Requires-Dist: mistune==3.1.3
+Requires-Dist: click>=8.1.8,<8.2
+Requires-Dist: httpx-limiter>=0.4.0,<0.5
+Requires-Dist: jinja2>=3.1.6,<3.2 ; extra == 'mail'
+Requires-Dist: nameparser>=1.1.3 ; extra == 'mail'
+Requires-Dist: yagmail>=0.15.293,<0.16 ; extra == 'mail'
+Requires-Dist: python-dateutil>=2.9.0.post0,<3 ; extra == 'uhd-urz'
+Requires-Dist: tenacity>=9.1.2,<10 ; extra == 'uhd-urz'
+Requires-Dist: uvloop>=0.21.0,<0.22 ; extra == 'uhd-urz'
+Maintainer: Mahadi Xion
+Maintainer-email: Mahadi Xion <mahadi.xion@urz.uni-heidelberg.de>
+Requires-Python: >=3.11.0, <4
+Project-URL: Changelog, https://github.com/uhd-urz/elAPI/blob/main/CHANGELOG.md
+Project-URL: Homepage, https://www.urz.uni-heidelberg.de/de/service-katalog/software-und-anwendungen/elabftw
+Project-URL: Issues, https://github.com/uhd-urz/elAPI/issues
+Project-URL: Repository, https://github.com/uhd-urz/elAPI.git
+Provides-Extra: mail
 Provides-Extra: uhd-urz
-Requires-Dist: python-dateutil<3,>=2.9.0.post0; extra == 'uhd-urz'
-Requires-Dist: tenacity<10,>=9.0.0; extra == 'uhd-urz'
-Requires-Dist: uvloop<0.21,>=0.20.0; extra == 'uhd-urz'
 Description-Content-Type: text/markdown
 
 <p align="center">
@@ -47,23 +55,24 @@ Description-Content-Type: text/markdown
 <img alt="Package version" src="https://badge.fury.io/py/elapi.svg/?branch=main" />
    </a>
 <a href="#compatibility">
-   <img alt="Static Badge" src="https://img.shields.io/badge/python-3.9%20%7C%203.10%20%7C%203.11%20%7C%203.12-%230d7dbe">
+   <img alt="Static Badge" src="https://img.shields.io/badge/python-3.11%20%7C%203.12%20%7C%203.13-%230d7dbe">
    <img alt="Static Badge" src="https://img.shields.io/badge/eLabFTW%20support-4.5%2B%20%7C%205.0%20%7C%205.1-%2323b3be">
 </a>
 </p>
 
 elAPI is a powerful, extensible API client for [eLabFTW](https://www.elabftw.net/) 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 in
-[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.
+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). elAPI has complete support
+for [eLabFTW REST APIv2](https://doc.elabftw.net/api/v2/). elAPI executable comes with a simple CLI interface for
+performing fast and quick API tasks. elAPI Python package brings a suite of convenience APIs to help streamline advanced
+API automation tasks. Check out our [examples](#examples-and-usage).
 
 <img src="https://heibox.uni-heidelberg.de/f/7714c7eeb0f54a3ba318/?dl=1" alt="elAPI features in a nutshell" />
 
 **Example:**
 
-From [the documentation](https://doc.elabftw.net/api/v2/#/Users/read-user):
+From [the API documentation](https://doc.elabftw.net/api/v2/#/Users/read-user):
 > GET /users/{id}
 
 With elAPI you can do the following:
@@ -97,8 +106,8 @@ the terminal. You can move on to ["Getting started"](#getting-started).
 
 elAPI can be used both as a CLI tool and as a Python library. If you are interested in simply using elAPI's
 off-the-shelf features from the command-line, install elAPI as a CLI tool (see ["Installation"](#installation)). If you
-intend to write automation script for eLabFTW, you should install elAPI as a library inside a virtual environment. Of
-course, if you're interested in both, you can have elAPI installed in both ways.
+intend to write an automation script for eLabFTW, you should install elAPI as a library inside a virtual environment. Of
+course, if you need both, you can have elAPI installed in both ways.
 
 > [!NOTE]
 > Support for installing Python packages with `pip install --user` has been deprecated with the adoption
@@ -108,9 +117,9 @@ course, if you're interested in both, you can have elAPI installed in both ways.
 ### Installing elAPI as a library
 
 It is recommended to install elAPI inside a Python virtual environment with your preferred package manager (`pip`,
-`poetry`, `pipenv`, `rye`, `uv`, etc.) for use of its rich APIs for
-working with eLabFTW. From inside a virtual environment, elAPI CLI can be invoked with `python -m elapi.cli`.
-At the moment, though, the documentation about using elAPI as a library is severely lacking.
+`poetry`, `pipenv`, `rye`, `uv`, etc.). With `uv`, for example, run `uv add elapi`. From inside a virtual environment,
+elAPI CLI can be invoked with `python -m elapi.cli`. At the moment, though, the documentation about using elAPI as a
+library is severely lacking.
 
 ## Getting started
 
@@ -128,20 +137,19 @@ That's all! Run [`elapi show-config`](#show-config) to view your configuration d
 
 ## Compatibility
 
-elAPI is compatible with the following Python versions: `3.9`, `3.10`, `3.11`, `3.12`. elAPI supports
+elAPI is compatible with the following Python versions: `3.11`, `3.12`. elAPI supports
 the [eLabFTW REST API v2](https://doc.elabftw.net/api/v2/), and can be used with the following eLabFTW
-versions: `4.5`, `4.6`, `4.7`, `4.8`, `4.9`, `4.10`, `5.0`, `5.1`.
+versions: `4.5`, `4.6`, `4.7`, `4.8`, `4.9`, `4.10`, `5.0`, `5.1`, `5.2`, and above.
 
 ## Configuration
 
 elAPI needs to be configured first before you can do anything useful with it. Mainly, elAPI needs to know your eLabFTW
-server's API URL and your API key (or token) for access. See quick configuration method
+server's API URL and your API key (or token) for access. See a quick configuration method
 in "[Getting started](#getting-started)" before you dive into the advanced settings.
 
 ### Advanced configuration
 
-elAPI supports a YAML configuration file in
-the following locations.
+elAPI supports a YAML configuration file in the following locations.
 
 - Current directory: `./elapi.yml`
 - User directory: `$HOME/.config/elapi.yml`
@@ -149,11 +157,10 @@ the following locations.
 
 elAPI supports configuration overloading. I.e., a keyword set in root configuration file `/etc/elapi.yml` can be
 overridden by setting a different value in user configuration file `$HOME/.config/elapi.yml`. In terms of precedence,
-configuration file present in the currently active directory has the highest priority, and configuration in root
-directory has the lowest.
+a configuration file present in the currently active directory has the highest priority, and a configuration file in the
+root 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`.
+The following parameters are currently configurable, with `host` and `api_token` being the required fields.
 
 ```yaml
 # elAPI configuration
@@ -169,6 +176,8 @@ unsafe_api_token_warning: true
 enable_http2: false
 verify_ssl: true
 timeout: 90
+async_rate_limit: 100
+development_mode: false
 ```
 
 - `export_dir` is where elAPI will export response content to if no path is explicitly provided to `--export/-E`.
@@ -182,14 +191,20 @@ timeout: 90
   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.
+- `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
+  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.
+- `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.
 
 ### `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.
+which configuration values are actually used by elAPI – especially if you are working with multiple configuration files.
 
 ```shell
-$ elapi show-config  # system username: "culdesac" 
+$ elapi show-config  # host username: "culdesac" 
 ```
 
 ![elAPI show-config output](https://heibox.uni-heidelberg.de/f/00a8dabbf2124087aae4/?dl=1)
@@ -229,7 +244,7 @@ $ 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.
+of the team with team ID 1.
 
 ```shell
 $ elapi get -H teams --id 1
@@ -266,7 +281,7 @@ $ elapi patch config -d '{"announcement": "Notice: Server will be down tomorrow
 
 ### `DELETE` requests
 
-Delete all the tags associated to an experiment:
+Delete all the tags associated with an experiment:
 
 ```shell
 $ elapi delete experiments -i <experiment ID> --sub tags
@@ -287,7 +302,7 @@ to `~/Downloads` directory.
 $ elapi experiments get -i <experiment unique elabid> -F pdf --export ~/Downloads/
 ```
 
-Append text in markdown to an existing experiment by its ID:
+Append text in Markdown to an existing experiment by its ID:
 
 ```shell
 $ elapi experiments append --id <experiment ID> -M -t "**New content.**"
@@ -299,12 +314,25 @@ 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>
 ```
 
+### `mail` built-in plugin
+
+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
+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
+can be sent only when a specific plugin task/command is finished, and/or when a matching log state and/or a matching log
+pattern is found.
+
+<img alt="elAPI email trigger screenshot" src="https://github.com/user-attachments/assets/2dc0df3e-0d91-41f3-af28-4040da641a70" />
+
 ## Creating a plugin
 
-elAPI has seamless support with tight-integration for third-party plugins. A simple third-party plugin can be created in
+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
+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:
 
@@ -318,8 +346,7 @@ 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.
+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
@@ -347,7 +374,7 @@ def wiki_status():
     print(r)
 ```
 
-And the path to virtual environment will be defined in the metadata file:
+And, the path to the virtual environment will be defined in the metadata file:
 
 ```yaml
 # elapi_plugin_metadata.yml

{elapi-2.3.2 → elapi-2.4.0}/README.md

@@ -7,23 +7,24 @@
 <img alt="Package version" src="https://badge.fury.io/py/elapi.svg/?branch=main" />
    </a>
 <a href="#compatibility">
-   <img alt="Static Badge" src="https://img.shields.io/badge/python-3.9%20%7C%203.10%20%7C%203.11%20%7C%203.12-%230d7dbe">
+   <img alt="Static Badge" src="https://img.shields.io/badge/python-3.11%20%7C%203.12%20%7C%203.13-%230d7dbe">
    <img alt="Static Badge" src="https://img.shields.io/badge/eLabFTW%20support-4.5%2B%20%7C%205.0%20%7C%205.1-%2323b3be">
 </a>
 </p>
 
 elAPI is a powerful, extensible API client for [eLabFTW](https://www.elabftw.net/) 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 in
-[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.
+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). elAPI has complete support
+for [eLabFTW REST APIv2](https://doc.elabftw.net/api/v2/). elAPI executable comes with a simple CLI interface for
+performing fast and quick API tasks. elAPI Python package brings a suite of convenience APIs to help streamline advanced
+API automation tasks. Check out our [examples](#examples-and-usage).
 
 <img src="https://heibox.uni-heidelberg.de/f/7714c7eeb0f54a3ba318/?dl=1" alt="elAPI features in a nutshell" />
 
 **Example:**
 
-From [the documentation](https://doc.elabftw.net/api/v2/#/Users/read-user):
+From [the API documentation](https://doc.elabftw.net/api/v2/#/Users/read-user):
 > GET /users/{id}
 
 With elAPI you can do the following:
@@ -57,8 +58,8 @@ the terminal. You can move on to ["Getting started"](#getting-started).
 
 elAPI can be used both as a CLI tool and as a Python library. If you are interested in simply using elAPI's
 off-the-shelf features from the command-line, install elAPI as a CLI tool (see ["Installation"](#installation)). If you
-intend to write automation script for eLabFTW, you should install elAPI as a library inside a virtual environment. Of
-course, if you're interested in both, you can have elAPI installed in both ways.
+intend to write an automation script for eLabFTW, you should install elAPI as a library inside a virtual environment. Of
+course, if you need both, you can have elAPI installed in both ways.
 
 > [!NOTE]
 > Support for installing Python packages with `pip install --user` has been deprecated with the adoption
@@ -68,9 +69,9 @@ course, if you're interested in both, you can have elAPI installed in both ways.
 ### Installing elAPI as a library
 
 It is recommended to install elAPI inside a Python virtual environment with your preferred package manager (`pip`,
-`poetry`, `pipenv`, `rye`, `uv`, etc.) for use of its rich APIs for
-working with eLabFTW. From inside a virtual environment, elAPI CLI can be invoked with `python -m elapi.cli`.
-At the moment, though, the documentation about using elAPI as a library is severely lacking.
+`poetry`, `pipenv`, `rye`, `uv`, etc.). With `uv`, for example, run `uv add elapi`. From inside a virtual environment,
+elAPI CLI can be invoked with `python -m elapi.cli`. At the moment, though, the documentation about using elAPI as a
+library is severely lacking.
 
 ## Getting started
 
@@ -88,20 +89,19 @@ That's all! Run [`elapi show-config`](#show-config) to view your configuration d
 
 ## Compatibility
 
-elAPI is compatible with the following Python versions: `3.9`, `3.10`, `3.11`, `3.12`. elAPI supports
+elAPI is compatible with the following Python versions: `3.11`, `3.12`. elAPI supports
 the [eLabFTW REST API v2](https://doc.elabftw.net/api/v2/), and can be used with the following eLabFTW
-versions: `4.5`, `4.6`, `4.7`, `4.8`, `4.9`, `4.10`, `5.0`, `5.1`.
+versions: `4.5`, `4.6`, `4.7`, `4.8`, `4.9`, `4.10`, `5.0`, `5.1`, `5.2`, and above.
 
 ## Configuration
 
 elAPI needs to be configured first before you can do anything useful with it. Mainly, elAPI needs to know your eLabFTW
-server's API URL and your API key (or token) for access. See quick configuration method
+server's API URL and your API key (or token) for access. See a quick configuration method
 in "[Getting started](#getting-started)" before you dive into the advanced settings.
 
 ### Advanced configuration
 
-elAPI supports a YAML configuration file in
-the following locations.
+elAPI supports a YAML configuration file in the following locations.
 
 - Current directory: `./elapi.yml`
 - User directory: `$HOME/.config/elapi.yml`
@@ -109,11 +109,10 @@ the following locations.
 
 elAPI supports configuration overloading. I.e., a keyword set in root configuration file `/etc/elapi.yml` can be
 overridden by setting a different value in user configuration file `$HOME/.config/elapi.yml`. In terms of precedence,
-configuration file present in the currently active directory has the highest priority, and configuration in root
-directory has the lowest.
+a configuration file present in the currently active directory has the highest priority, and a configuration file in the
+root 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`.
+The following parameters are currently configurable, with `host` and `api_token` being the required fields.
 
 ```yaml
 # elAPI configuration
@@ -129,6 +128,8 @@ unsafe_api_token_warning: true
 enable_http2: false
 verify_ssl: true
 timeout: 90
+async_rate_limit: 100
+development_mode: false
 ```
 
 - `export_dir` is where elAPI will export response content to if no path is explicitly provided to `--export/-E`.
@@ -142,14 +143,20 @@ timeout: 90
   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.
+- `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
+  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.
+- `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.
 
 ### `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.
+which configuration values are actually used by elAPI – especially if you are working with multiple configuration files.
 
 ```shell
-$ elapi show-config  # system username: "culdesac" 
+$ elapi show-config  # host username: "culdesac" 
 ```
 
 ![elAPI show-config output](https://heibox.uni-heidelberg.de/f/00a8dabbf2124087aae4/?dl=1)
@@ -189,7 +196,7 @@ $ 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.
+of the team with team ID 1.
 
 ```shell
 $ elapi get -H teams --id 1
@@ -226,7 +233,7 @@ $ elapi patch config -d '{"announcement": "Notice: Server will be down tomorrow
 
 ### `DELETE` requests
 
-Delete all the tags associated to an experiment:
+Delete all the tags associated with an experiment:
 
 ```shell
 $ elapi delete experiments -i <experiment ID> --sub tags
@@ -247,7 +254,7 @@ to `~/Downloads` directory.
 $ elapi experiments get -i <experiment unique elabid> -F pdf --export ~/Downloads/
 ```
 
-Append text in markdown to an existing experiment by its ID:
+Append text in Markdown to an existing experiment by its ID:
 
 ```shell
 $ elapi experiments append --id <experiment ID> -M -t "**New content.**"
@@ -259,12 +266,25 @@ 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>
 ```
 
+### `mail` built-in plugin
+
+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
+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
+can be sent only when a specific plugin task/command is finished, and/or when a matching log state and/or a matching log
+pattern is found.
+
+<img alt="elAPI email trigger screenshot" src="https://github.com/user-attachments/assets/2dc0df3e-0d91-41f3-af28-4040da641a70" />
+
 ## Creating a plugin
 
-elAPI has seamless support with tight-integration for third-party plugins. A simple third-party plugin can be created in
+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
+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:
 
@@ -278,8 +298,7 @@ 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.
+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
@@ -307,7 +326,7 @@ def wiki_status():
     print(r)
 ```
 
-And the path to virtual environment will be defined in the metadata file:
+And, the path to the virtual environment will be defined in the metadata file:
 
 ```yaml
 # elapi_plugin_metadata.yml

{elapi-2.3.2 → elapi-2.4.0}/pyproject.toml

@@ -1,9 +1,9 @@
 [project]
 name = "elapi"
-version = "2.3.2"
+version = "2.4.0"
 description = "elAPI is a powerful, extensible API client for eLabFTW."
 authors = [{ name = "Alexander Haller, Mahadi Xion", email = "elabftw@uni-heidelberg.de" }]
-requires-python = ">=3.9.0,<4"
+requires-python = ">=3.11.0,<4"
 readme = "README.md"
 license = "AGPL-3.0-only"
 maintainers = [{ name = "Mahadi Xion", email = "mahadi.xion@urz.uni-heidelberg.de" }]
@@ -26,21 +26,30 @@ classifiers = [
 ]
 dependencies = [
     "dynaconf>=3.2.0,<4",
-    "httpx>=0.24.1,<0.25",
-    "httpx-auth>=0.17.0,<0.18",
+    "httpx[http2]>=0.28.1,<0.29",
+    "httpx-auth>=0.23.1,<0.24",
     "rich>=13.8.0,<14",
     "typer[all]>=0.9.0,<0.10",
-    "pyyaml>=6.0.1,<7",
-    "mistune>=3.0.2,<4",
-    "h2>=4.1.0,<5",
-    "click>=8.1.8,<8.2"
+    "pyyaml==6.0.2",
+    "mistune==3.1.3",
+    "click>=8.1.8,<8.2",
+    "httpx-limiter>=0.4.0,<0.5",
+]
+license-files = [
+    "LICENSE",
+    "src/elapi/_vendor/*/LICENSE"
 ]
 
 [project.optional-dependencies]
 uhd-urz = [
     "python-dateutil>=2.9.0.post0,<3",
-    "tenacity>=9.0.0,<10",
-    "uvloop>=0.20.0,<0.21",
+    "tenacity>=9.1.2,<10",
+    "uvloop>=0.21.0,<0.22",
+]
+mail = [
+    "jinja2>=3.1.6,<3.2",
+    "nameparser>=1.1.3",
+    "yagmail>=0.15.293,<0.16",
 ]
 
 [project.urls]
@@ -53,8 +62,19 @@ Changelog = "https://github.com/uhd-urz/elAPI/blob/main/CHANGELOG.md"
 elapi = "elapi.cli.elapi:app"
 
 [build-system]
-requires = ["hatchling"]
-build-backend = "hatchling.build"
+requires = ["uv_build>=0.7.19,<0.8.0"]
+build-backend = "uv_build"
 
 [dependency-groups]
-dev = ["ptpython>=3.0.23,<4"]
+dev = [
+    "pip>=25.1.1", # vendy requires pip
+    "ptpython>=3.0.23,<4",
+    "vendy>=0.0.3",
+]
+
+[tool.vendy]
+target = 'src/elapi/'
+# vendy will auto-crate src/elapi/_vendor
+packages = [
+    "haggis==0.14.1",
+]

elapi-2.4.0/src/elapi/VERSION

@@ -0,0 +1 @@
+2.4.0

elapi-2.4.0/src/elapi/_core_init/__init__.py

@@ -0,0 +1,55 @@
+__all__ = [
+    "DefaultLogLevels",
+    "LogMessageTuple",
+    "SimpleLogger",
+    "STDERRBaseHandler",
+    "Logger",
+    "BaseHandler",
+    "LoggerUtil",
+    "add_logging_level",
+    "get_app_version",
+    "NoException",
+    "GlobalCLIResultCallback",
+    "GlobalCLISuperStartupCallback",
+    "ResultCallbackHandler",
+    "GlobalLogRecordContainer",
+    "GlobalCLIGracefulCallback",
+    "LogItemList",
+    "PatternNotFoundError",
+]
+import logging
+
+from .._vendor import haggis
+from .._vendor.haggis.logs import add_logging_level
+from ._loggers import (
+    BaseHandler,
+    DefaultLogLevels,
+    GlobalLogRecordContainer,
+    Logger,
+    LoggerUtil,
+    LogItemList,
+    LogMessageTuple,
+    ResultCallbackHandler,
+    SimpleLogger,
+    STDERRBaseHandler,
+)
+from ._utils import (
+    GlobalCLIGracefulCallback,
+    GlobalCLIResultCallback,
+    GlobalCLISuperStartupCallback,
+    NoException,
+    PatternNotFoundError,
+    get_app_version,
+)
+
+haggis.logs.logging = logging
+
+try:
+    # Python 3.13 deprecated _acquireLock, _releaseLock
+    # Based on https://github.com/celery/billiard/issues/403, commit 81cc942
+    logging._acquireLock, logging._releaseLock = (
+        logging._prepareFork,
+        logging._afterFork,
+    )
+except AttributeError:
+    ...

elapi-2.4.0/src/elapi/_core_init/_loggers/__init__.py

@@ -0,0 +1,26 @@
+__all__ = [
+    "DefaultLogLevels",
+    "LogMessageTuple",
+    "SimpleLogger",
+    "STDERRBaseHandler",
+    "Logger",
+    "BaseHandler",
+    "LoggerUtil",
+    "ResultCallbackHandler",
+    "GlobalLogRecordContainer",
+    "LogItemList",
+]
+from .base import (
+    DefaultLogLevels,
+    Logger,
+    LoggerUtil,
+    LogMessageTuple,
+    SimpleLogger,
+)
+from .handlers import (
+    BaseHandler,
+    LogItemList,
+    GlobalLogRecordContainer,
+    ResultCallbackHandler,
+    STDERRBaseHandler,
+)