elapi 1.0.7.dev1__tar.gz → 1.0.7.dev3__tar.gz

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

@@ -1,12 +1,12 @@
 Metadata-Version: 2.1
 Name: elapi
-Version: 1.0.7.dev1
-Summary: elAPI is a powerful, extensible API interface to eLabFTW built for the University Computing Centre (URZ, FIRE division) at Universität Heidelberg.
+Version: 1.0.7.dev3
+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
 Keywords: elabftw,api
-Author: Alexander Haller
-Author-email: alexander.haller@urz.uni-heidelberg.de
+Author: Alexander Haller, Mahadi Xion
+Author-email: elabftw@uni-heidelberg.de
 Maintainer: Mahadi Xion
 Maintainer-email: mahadi.xion@urz.uni-heidelberg.de
 Requires-Python: >=3.9.0,<4.0.0
@@ -38,7 +38,10 @@ Description-Content-Type: text/markdown
 
 # elAPI
 
-elAPI is a powerful, extensible API interface to eLabFTW. It supports serving almost all kinds of requests documented in
+elAPI is a powerful, extensible API client for eLabFTW built for
+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) at
+Universität Heidelberg. It supports serving almost all kinds of requests documented on
 [eLabFTW API documentation](https://doc.elabftw.net/api/v2/) with ease. elAPI treats eLabFTW API endpoints as its
 arguments.
 
@@ -55,18 +58,47 @@ $ elapi get users --id <id>
 
 ## Installation
 
-Support for installing packages with `pip install --user` has been deprecated with the adoption of [PEP 688](https://peps.python.org/pep-0668/) on many systems like [Debian 12](https://bugs.debian.org/cgi-bin/bugreport.cgi?bug=1030335#5).
-We recommend [`pipx`](https://pipx.pypa.io/stable/) for installing elAPI.
+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. 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.
+
+### Install elAPI as a CLI tool
+
+Support for installing Python packages with `pip install --user` has been deprecated with the adoption
+of [PEP 688](https://peps.python.org/pep-0668/) on many systems
+like [Debian 12](https://bugs.debian.org/cgi-bin/bugreport.cgi?bug=1030335#5).
+We recommend [`pipx`](https://pipx.pypa.io/stable/) for installing elAPI for use of its CLI functionalities. Pipx
+installs packages in isolated virtual environments, so Pipx-installed elAPI should not conflict with elAPI installed
+inside other virtual environments.
 
 ```shell
 $ pipx install elapi
 ```
 
-Of course, `pip install --user elapi` might continue to work on some systems.
+After installation with Pipx is complete, you would also be able to run elAPI just by entering the `elapi` command on
+the
+terminal.
+
+### Install elAPI as a library
+
+It is recommended to install elAPI inside a Python virtual environment 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.
 
 ## Configuration
 
-elAPI needs to be configured first before we can do anything useful with it. elAPI supports a YAML configuration file in
+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.
+
+### Quick configuration
+
+You can run `elapi init` to simplify the configuration process. You will be prompted with questions
+about your eLabFTW server with examples to help you fill in the answers.
+
+### Advanced configuration
+
+elAPI supports a YAML configuration file in
 the following locations.
 
 - Current directory: `./elapi.yml`
@@ -74,12 +106,12 @@ the following locations.
 - Root directory: `/etc/elapi.yml`
 
 elAPI supports configuration overloading. I.e., a keyword set in root configuration file `/etc/elapi.yml` can be
-overriden by setting a different value in user configuration file `$HOME/.config/elapi.yml`. In terms of precedence,
+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.
 
 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 the user configuration file.
+purposes it would be safe to store everything in `$HOME/.config/elapi.yml`.
 
 ```yaml
 # elAPI configuration
@@ -94,13 +126,13 @@ export_dir: ~/Downloads/elAPI
 unsafe_api_token_warning: yes
 ```
 
-We can get an overview of detected configurations.
+You can get an overview of detected configurations.
 
 ```shell
 $ elapi show-config
 ```
 
-If both `host` and `api_token` are detected, we are good to go!
+If both `host` and `api_token` are detected, you are good to go!
 
 ## Usage
 
@@ -112,14 +144,14 @@ $ elapi --help
 
 ### `GET` requests
 
-We can request an overview of running eLabFTW server.
+Request an overview of running eLabFTW server:
 
 ```shell
 $ elapi get info -F yml
 # Here -F (or --format) defines the output format
 ```
 
-We can request a list o all active experiments and export it to a `JSON` file.
+You can request a list o all active experiments and export it to a `JSON` file.
 
 ```shell
 $ elapi get experiments --export ~/Downoads/experiments.json
@@ -127,7 +159,7 @@ $ elapi get experiments --export ~/Downoads/experiments.json
 
 ### `POST` requests
 
-We can create a new user by the name 'John Doe'.
+Create a new user by the name 'John Doe':
 
 ```shell
 $ elapi post users --id <user id> -d '{"firstname": "John", "lastname": "Doe", "email": "test_test@itnerd.de"}'
@@ -135,46 +167,70 @@ $ elapi post users --id <user id> -d '{"firstname": "John", "lastname": "Doe", "
 
 ### `PATCH` requests
 
-We can update an existing user's email address.
+Update an existing user's email address:
 
 ```shell
 $ elapi patch users --id <user id> -d '{"email": "new_email@itnerd.de"}'
 ```
 
-`patch` command allows us to make changes to eLabFTW server settings. E.g., we can update the time (in minutes)
+`patch` command allows us to make changes to eLabFTW server settings. E.g., you can update the time (in minutes)
 after which the authentication cookie will expire.
 
 ```shell
 $ elapi patch config -d '{"cookie_validity_time": 43200}'
 ```
 
-We can publish an announcement to all the members.
+You can publish an announcement to all the members.
 
 ```shell
 $ elapi patch config -d '{"announcement": "Notice: Server will be down tomorrow at midnight due to scheduled maintenance."}'
 ```
 
-### Bill teams
+### `DELETE` requests
 
-We can generate invoice for eLabFTW teams.
+Delete all the tags associated to an experiment:
 
 ```shell
-$ elapi bill-teams generate-invoice
+$ elapi delete experiments -i <experiment ID> --sub tags
 ```
 
-We may just want to have a look at the billing information without generating invoice.
+You can reset the configuration to default values.
 
 ```shell
-$ elapi bill-teams info -F yaml
+$ elapi delete config
 ```
 
-We can also export this information as a `YAML` file to the export directory defined in configuration
-file (`export_dir`).
+### `experiments` plugin
+
+`experiments` plugin enables experiments-specific actions. You can download an experiment in PDF by its "Unique eLabID"
+to `~/Downloads` directory.
 
 ```shell
-elapi bill-teams info -F yaml --export
+$ elapi experiments get -i <experiment unique elabid> -F pdf --export ~/Downloads/
 ```
 
+Append text in markdown to an existing experiment by its ID:
+
+```shell
+$ elapi experiments append --id <experiment ID> -M -t "**New content.**"
+```
+
+You can also upload an attachment to an experiment.
+
+```shell
+$ elapi experiments upload-attachment --id <experiment ID> --path <path to attachment file> --comment <comment for your attachment>
+```
+
+### Bill teams
+
+You can get a list of all teams and its users for billing purposes and export it to home directory.
+
+```shell
+$ elapi bill-teams teams-info --export ~
+```
+
+Most sub-commands available under `elapi bill-teams` plugin are for Universität Heidelberg specific use-cases.
+
 ## Open-source
 
 elAPI is open-source and published under AGPLv3 license. The repository is however hosted internally within

elapi-1.0.7.dev3/README.md

@@ -0,0 +1,201 @@
+# elAPI
+
+elAPI is a powerful, extensible API client for eLabFTW built for
+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) at
+Universität Heidelberg. It supports serving almost all kinds of requests documented on
+[eLabFTW API documentation](https://doc.elabftw.net/api/v2/) with ease. elAPI treats eLabFTW API endpoints as its
+arguments.
+
+**Example:**
+
+From [the documentation](https://doc.elabftw.net/api/v2/#/Users/read-user):
+> GET /users/{id}
+
+With elAPI you can do the following:
+
+```sh
+$ elapi get users --id <id>
+```
+
+## Installation
+
+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. 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.
+
+### Install elAPI as a CLI tool
+
+Support for installing Python packages with `pip install --user` has been deprecated with the adoption
+of [PEP 688](https://peps.python.org/pep-0668/) on many systems
+like [Debian 12](https://bugs.debian.org/cgi-bin/bugreport.cgi?bug=1030335#5).
+We recommend [`pipx`](https://pipx.pypa.io/stable/) for installing elAPI for use of its CLI functionalities. Pipx
+installs packages in isolated virtual environments, so Pipx-installed elAPI should not conflict with elAPI installed
+inside other virtual environments.
+
+```shell
+$ pipx install elapi
+```
+
+After installation with Pipx is complete, you would also be able to run elAPI just by entering the `elapi` command on
+the
+terminal.
+
+### Install elAPI as a library
+
+It is recommended to install elAPI inside a Python virtual environment 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.
+
+## 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.
+
+### Quick configuration
+
+You can run `elapi init` to simplify the configuration process. You will be prompted with questions
+about your eLabFTW server with examples to help you fill in the answers.
+
+### Advanced configuration
+
+elAPI supports a YAML configuration file in
+the following locations.
+
+- Current directory: `./elapi.yml`
+- User directory: `$HOME/.config/elapi.yml`
+- Root directory: `/etc/elapi.yml`
+
+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.
+
+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`.
+
+```yaml
+# elAPI configuration
+# Saved in `$HOME/.config/elapi.yml`
+
+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.
+export_dir: ~/Downloads/elAPI
+unsafe_api_token_warning: yes
+```
+
+You can get an overview of detected configurations.
+
+```shell
+$ elapi show-config
+```
+
+If both `host` and `api_token` are detected, you are good to go!
+
+## Usage
+
+elAPI can be invoked from the command-line.
+
+```shell
+$ elapi --help 
+```
+
+### `GET` requests
+
+Request an overview of running eLabFTW server:
+
+```shell
+$ elapi get info -F yml
+# Here -F (or --format) defines the output format
+```
+
+You can request a list o all active experiments and export it to a `JSON` file.
+
+```shell
+$ elapi get experiments --export ~/Downoads/experiments.json
+```
+
+### `POST` requests
+
+Create a new user by the name 'John Doe':
+
+```shell
+$ elapi post users --id <user id> -d '{"firstname": "John", "lastname": "Doe", "email": "test_test@itnerd.de"}'
+```
+
+### `PATCH` requests
+
+Update an existing user's email address:
+
+```shell
+$ elapi patch users --id <user id> -d '{"email": "new_email@itnerd.de"}'
+```
+
+`patch` command allows us to make changes to eLabFTW server settings. E.g., you can update the time (in minutes)
+after which the authentication cookie will expire.
+
+```shell
+$ elapi patch config -d '{"cookie_validity_time": 43200}'
+```
+
+You can publish an announcement to all the members.
+
+```shell
+$ elapi patch config -d '{"announcement": "Notice: Server will be down tomorrow at midnight due to scheduled maintenance."}'
+```
+
+### `DELETE` requests
+
+Delete all the tags associated to an experiment:
+
+```shell
+$ elapi delete experiments -i <experiment ID> --sub tags
+```
+
+You can reset the configuration to default values.
+
+```shell
+$ elapi delete config
+```
+
+### `experiments` plugin
+
+`experiments` plugin enables experiments-specific actions. You can download an experiment in PDF by its "Unique eLabID"
+to `~/Downloads` directory.
+
+```shell
+$ elapi experiments get -i <experiment unique elabid> -F pdf --export ~/Downloads/
+```
+
+Append text in markdown to an existing experiment by its ID:
+
+```shell
+$ elapi experiments append --id <experiment ID> -M -t "**New content.**"
+```
+
+You can also upload an attachment to an experiment.
+
+```shell
+$ elapi experiments upload-attachment --id <experiment ID> --path <path to attachment file> --comment <comment for your attachment>
+```
+
+### Bill teams
+
+You can get a list of all teams and its users for billing purposes and export it to home directory.
+
+```shell
+$ elapi bill-teams teams-info --export ~
+```
+
+Most sub-commands available under `elapi bill-teams` plugin are for Universität Heidelberg specific use-cases.
+
+## Open-source
+
+elAPI is open-source and published under AGPLv3 license. The repository is however hosted internally within
+Universität Heidelberg's network. The codebase can still be accessed from [PyPI](https://pypi.org/project/elapi/#files).
+If you express interest in having the repository made completely public, or if you have any question, feel free
+to [contact us](mailto:elabftw@uni-heidelberg.de).

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

@@ -1,11 +1,9 @@
 [tool.poetry]
 name = "elapi"
-version = "1.0.7-dev1"
-description = """elAPI is a powerful, extensible API interface to eLabFTW built for \
-the University Computing Centre (URZ, FIRE division) at Universität Heidelberg."""
+version = "1.0.7.dev3"
+description = "elAPI is a powerful, extensible API client for eLabFTW."
 authors = [
-    "Alexander Haller <alexander.haller@urz.uni-heidelberg.de>",
-    "Mahadi Xion <mahadi.xion@urz.uni-heidelberg.de>",
+    "Alexander Haller, Mahadi Xion <elabftw@uni-heidelberg.de>",
 ]
 maintainers = [
     "Mahadi Xion <mahadi.xion@urz.uni-heidelberg.de>",

elapi-1.0.7.dev3/src/elapi/VERSION

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

elapi-1.0.7.dev3/src/elapi/_exceptions.py

@@ -0,0 +1 @@
+class NoException(Exception): ...

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

@@ -154,7 +154,7 @@ class ElabFTWURL:
     @endpoint_id.setter
     def endpoint_id(self, value):
         if value is not None:
-            if not re.match(r"^\w+$", value := str(value)):
+            if not re.match(r"^(\d+)$|^(me)$", 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 +173,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"^\w+$", value := str(value)):
+            if not re.match(r"^(\d+)$|^(me)$", value := str(value)):
                 raise ElabFTWURLError("Invalid sub-endpoint ID (or entity sub-ID).")
             self._sub_endpoint_id = value
         else:

elapi-1.0.7.dev3/src/elapi/cli/__init__.py

@@ -0,0 +1 @@
+from ..plugins.commons.cli_helpers import CLIExport, CLIFormat, OrderedCommands  # noqa: F401

{elapi-1.0.7.dev1 → elapi-1.0.7.dev3}/src/elapi/cli/doc.py

@@ -71,12 +71,17 @@ __PARAMETERS__doc__ = {
               f"If _--format/-F_ is absent, then {APP_NAME} can use the file extension as the data format. "
               f"If _--format/-F_ is also present, then file extension is ignored, "
               f"and --format value takes precedence.\n",
+    "export_overwrite": f"If given --export/-e path is a file, but it already **exists**, "
+                        f"{APP_NAME} will not overwrite the file by default, and will instead use the "
+                        f"fallback location. _--overwrite_ needs to be passed if {APP_NAME} should overwrite "
+                        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 falls back to 'txt'.",
+              "If an unsupported format value is provided then the output format "
+              f"falls back to `{DEFAULT_EXPORT_DATA_FORMAT.upper()}`.",
     "no_keys": "Do not show the names of configuration keywords.",
     "init_host": 'The host URL of your eLabFTW instance. It will look like \"https://demo.elabftw.net/api/v2\".',
     "init_api_token": 'API token (or API key) of your eLabFTW instance. You can generate it from eLabFTW "User Panel". '

{elapi-1.0.7.dev1 → elapi-1.0.7.dev3}/src/elapi/cli/elapi.py

@@ -21,10 +21,10 @@ from typing_extensions import Annotated
 
 from ._plugin_handler import internal_plugin_typer_apps
 from .doc import __PARAMETERS__doc__ as docs
-from .helpers import OrderedCommands
 from .. import APP_NAME
 from ..configuration import EXPORT_DIR
 from ..loggers import Logger
+from ..plugins.commons.cli_helpers import OrderedCommands
 from ..styles import get_custom_help_text
 from ..styles import stdin_console, stderr_console
 
@@ -101,6 +101,7 @@ def init(
     from ..configuration import LOCAL_CONFIG_LOC
     from ..validators import Validate, ValidationError
     from ..validators import PathValidator
+    from ..path import ProperPath
     from time import sleep
 
     with stdin_console.status(
@@ -119,27 +120,42 @@ def init(
             )
             raise typer.Exit(1)
         else:
-            with LOCAL_CONFIG_LOC.open(mode="r+") as f:
-                if f.read():
-                    logger.error(
-                        f"A configuration file '{LOCAL_CONFIG_LOC}' already exists and it's not empty! "
-                        f"It's ambiguous what to do in this situation. {APP_NAME} will abort. "
-                        f"Configuration initialization has failed!"
-                    )
-                    raise typer.Exit(1)
+            path = ProperPath(LOCAL_CONFIG_LOC)
+            try:
+                with path.open(mode="r") as f:
+                    if f.read():
+                        logger.error(
+                            f"A configuration file '{LOCAL_CONFIG_LOC}' already exists and it's not empty! "
+                            f"It's ambiguous what to do in this situation."
+                        )
+                        logger.error("Configuration initialization has failed!")
+                        raise typer.Exit(1)
+            except path.PathException as e:
+                if isinstance(e, FileNotFoundError):
+                    path.create()
                 else:
+                    logger.error(e)
+                    logger.error("Configuration initialization has failed!")
+                    raise typer.Exit(1)
+            try:
+                with path.open(mode="w") as f:
                     _configuration_yaml_text = f"""host: {host_url}
-api_token: {api_token}
-export_dir: {export_directory}
-unsafe_api_token_warning: yes
-"""
+    api_token: {api_token}
+    export_dir: {export_directory}
+    unsafe_api_token_warning: yes
+    """
                     f.write(_configuration_yaml_text)
-            stdin_console.print(
-                "Configuration file has been successfully created! "
-                f"Run '{APP_NAME} show-config' to see the configuration path "
-                "and more configuration details.",
-                style="green",
-            )
+            except path.PathException as e:
+                logger.error(e)
+                logger.error("Configuration initialization has failed!")
+                raise typer.Exit(1)
+            else:
+                stdin_console.print(
+                    "Configuration file has been successfully created! "
+                    f"Run '{APP_NAME} show-config' to see the configuration path "
+                    "and more configuration details.",
+                    style="green",
+                )
 
 
 @app.command(short_help="Make `GET` requests to eLabFTW endpoints.")
@@ -179,6 +195,10 @@ def get(
         ),
     ] = False,
     _export_dest: Annotated[Optional[str], typer.Argument(hidden=True)] = None,
+    export_overwrite: Annotated[
+        bool,
+        typer.Option("--overwrite", help=docs["export_overwrite"], show_default=False),
+    ] = False,
 ) -> dict:
     """
     Make `GET` requests to eLabFTW endpoints as documented in
@@ -200,9 +220,9 @@ def get(
     import re
     from .. import APP_NAME
     from ..api import GETRequest, ElabFTWURLError
-    from .helpers import CLIExport, CLIFormat
+    from ..plugins.commons.cli_helpers import CLIExport, CLIFormat
     from ..validators import Validate, HostIdentityValidator
-    from ..plugins.utils import Export
+    from ..plugins.commons import Export
     from ..styles import Highlight
 
     validate_config = Validate(HostIdentityValidator())
@@ -219,7 +239,9 @@ def get(
             style="red",
         )
         raise typer.Exit(1)
-    data_format, export_dest, export_file_ext = CLIExport(data_format, _export_dest)
+    data_format, export_dest, export_file_ext = CLIExport(
+        data_format, _export_dest, export_overwrite
+    )
     if not query:
         format = CLIFormat(data_format, export_file_ext)
     else:
@@ -324,7 +346,7 @@ def post(
 
     With `elapi` you can do the following:
     <br/>
-    `$ elapi post users --id <user id> -d '{"firstname": "John", "lastname": "Doe", "email": "test_test@itnerd.de"}'`
+    `$ elapi post users -d '{"firstname": "John", "lastname": "Doe", "email": "test_test@itnerd.de"}'`
     will create a new user.
     """
     import ast
@@ -332,7 +354,7 @@ def post(
     from ..api import POSTRequest, ElabFTWURLError
     from json import JSONDecodeError
     from ..validators import Validate, HostIdentityValidator
-    from ..plugins.utils import get_location_from_headers
+    from ..plugins.commons import get_location_from_headers
     from ..styles import Format, Highlight
     from ..path import ProperPath
 
@@ -670,7 +692,7 @@ def show_config(
     no_keys: Annotated[
         Optional[bool],
         typer.Option("--no-keys", help=docs["no_keys"], show_default=True),
-    ] = True,
+    ] = False,
 ) -> None:
     """
     Get information about detected configuration values.