elapi 1.0.7.dev1__py3-none-any.whl → 1.0.7.dev2__py3-none-any.whl

elapi/VERSION

@@ -1 +1 @@
-1.0.7-dev1
+1.0.7-dev2

elapi/_exceptions.py

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

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/cli/__init__.py

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

elapi/cli/doc.py

@@ -76,7 +76,8 @@ __PARAMETERS__doc__ = {
               "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/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.")
@@ -200,9 +216,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())
@@ -324,7 +340,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 +348,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 +686,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.

elapi/path.py

@@ -7,13 +7,14 @@ from pathlib import Path
 from shutil import rmtree
 from typing import Union, TextIO, Generator
 
+from ._exceptions import NoException
 from .loggers import SimpleLogger
 
 
 class ProperPath:
     def __init__(
         self,
-        name: Union[str, Path, None],
+        name: Union[str, Path, None, "ProperPath"],
         env_var: bool = False,
         kind: Union[str, None] = "",
         err_logger: logging.Logger = SimpleLogger(),
@@ -22,6 +23,7 @@ class ProperPath:
         self.env_var = env_var
         self.kind = kind
         self.err_logger = err_logger
+        self.PathException = NoException
 
     def __str__(self):
         return str(self.expanded)
@@ -62,6 +64,24 @@ class ProperPath:
             raise ValueError("'err_logger' must be a logging.Logger instance!")
         self._err_logger = value
 
+    @property
+    def PathException(self) -> type:
+        return self._PathException
+
+    # noinspection PyAttributeOutsideInit
+    @PathException.setter
+    def PathException(self, value: type) -> None:
+        if not issubclass(value, (Exception, BaseException)):
+            raise ValueError(
+                "Only an instance of Exception or BaseException can be "
+                "assigned to descriptor PathException."
+            )
+        self._PathException = value
+
+    @PathException.deleter
+    def PathException(self):
+        raise AttributeError("PathException cannot be deleted!")
+
     @property
     def expanded(self) -> Path:
         if self.env_var:
@@ -134,10 +154,24 @@ class ProperPath:
                 (path_parent / path_file).touch(exist_ok=True)
             elif self.kind == "dir":
                 path.mkdir(parents=True, exist_ok=True)
-        except PermissionError as e:
+        except (exception := PermissionError) as e:
             message = f"Permission to create {self._error_helper_compare_path_source(self.name, path)} is denied."
             self.err_logger.error(message)
+            self.PathException = exception
+            raise e
+        except (exception := NotADirectoryError) as e:
+            # Both "file" and "dir" cases are handled, but when path is under special files like
+            # /dev/null/<directory name>, os.mkdir() will throw NotADirectoryError.
+            message = f"Couldn't create {self._error_helper_compare_path_source(self.name, path)}."
+            self.err_logger.error(message)
+            self.PathException = exception
             raise e
+        except (exception := OSError) as os_err:
+            # When an attempt to create a file or directory inside root (e.g., '/foo')
+            # is made, OS can throw OSError with error no. 30 instead of PermissionError.
+            self.err_logger.error(os_err)
+            self.PathException = exception
+            raise os_err
         else:
             return path
 
@@ -153,10 +187,12 @@ class ProperPath:
             file.unlink()
         except FileNotFoundError as e:
             # unlink() throws FileNotFoundError when a directory is passed as it expects files only
-            raise ValueError(f"{file} doesn't exist or isn't a valid file!") from e
-        except PermissionError as e:
+            self.PathException = exception = ValueError
+            raise exception(f"{file} doesn't exist or isn't a valid file!") from e
+        except (exception := PermissionError) as e:
             message = f"Permission to remove {self._error_helper_compare_path_source(self.name, file)} is denied."
             self.err_logger.warning(message)
+            self.PathException = exception
             raise e
         if verbose:
             self.err_logger.info(f"Deleted: {file}")
@@ -187,42 +223,53 @@ class ProperPath:
 
     @contextmanager
     def open(
-        self, mode="r", encoding: Union[str, None] = None
+        self,
+        mode="r",
+        encoding: Union[str, None] = None,
+        **kwargs,
     ) -> Generator[TextIO, None, None]:
         path = self.expanded.resolve()
         file: Union[TextIO, None] = None
         try:
             # this try block doesn't yield anything yet. Here, we want to catch possible errors that occur
             # before the file is opened. E.g., FileNotFoundError
-            file: TextIO = path.open(mode=mode, encoding=encoding)
-        except FileNotFoundError as e:
+            file: TextIO = path.open(mode=mode, encoding=encoding, **kwargs)
+        except (exception := FileNotFoundError) as e:
             message = f"File in {path} couldn't be found while trying to open it with mode '{mode}'!"
             self.err_logger.warning(message)
+            self.PathException = exception
             raise e
 
-        except PermissionError as e:
+        except (exception := PermissionError) as e:
             message = (
                 f"Permission denied while trying to open file with mode '{mode}' for "
                 f"{self._error_helper_compare_path_source(self.name, path)}."
             )
             self.err_logger.error(message)
+            self.PathException = exception
 
             try:
                 yield  # Without yield (yield None) Python throws RuntimeError: generator didn't yield.
                 # I.e., contextmanager always expects a yield?
-            except AttributeError as attribute_err:
+            except (exception := AttributeError) as attribute_err:
                 # However, yielding None leads to attribute calls to None
                 # (e.g., yield None -> file = None -> file.read() -> None.read()!! So we also catch that error.
                 attribute_in_error = str(attribute_err).split()[-1]
                 message = (
-                    f"An attempt to access attribute {attribute_in_error} "
-                    f"of the file object was made, "
+                    f"An attempt to access attribute {attribute_in_error} was made,"
                     f"but there was a problem opening the file {path}."
                 )
                 self.err_logger.warning(message)
+                self.PathException = exception
                 raise attribute_err
             else:
                 raise e
+        except (exception := OSError) as os_err:
+            # When an attempt to create a file or directory inside root (e.g., '/foo')
+            # is made, OS can throw OSError with error no. 30 instead of PermissionError.
+            self.err_logger.error(os_err)
+            self.PathException = exception
+            raise os_err
 
         else:
             try:
@@ -238,14 +285,15 @@ class ProperPath:
                 )
                 self.err_logger.warning(message)
                 raise e
-            except MemoryError as e:
+            except (exception := MemoryError) as e:
                 message = (
                     f"Out of memory while trying to use mode '{mode}' with "
                     f"{self._error_helper_compare_path_source(self.name, path)}."
                 )
                 self.err_logger.critical(message)
+                self.PathException = exception
                 raise e
-            except IOError as io_err:
+            except (exception := IOError) as io_err:
                 # We catch "No disk space left" error which will likely be triggered during a write attempt on the file
                 if io_err.errno == errno.ENOSPC:
                     message = (
@@ -253,7 +301,12 @@ class ProperPath:
                         f"{self._error_helper_compare_path_source(self.name, path)}."
                     )
                     self.err_logger.critical(message)
+                    self.PathException = exception
                 raise io_err
+            except (exception := OSError) as os_err:
+                self.err_logger.error(os_err)
+                self.PathException = exception
+                raise os_err
         finally:
             if file:
                 try:
@@ -264,7 +317,7 @@ class ProperPath:
                 # f = open("/dev/full", mode="w");f.write("hello" * 10_000); <- Opening f again.
                 # The above will trigger ENOSPC error, and will be captured by previous ENOSPC IOError exception.
                 # Because of *, we again need to catch the error during close().
-                except IOError as io_err:
+                except (exception := IOError) as io_err:
                     if io_err.errno == errno.ENOSPC:
                         message = (
                             f"An 'ENOSPC' error (not enough disk space left) is received while trying to"
@@ -272,4 +325,5 @@ class ProperPath:
                             f"{self._error_helper_compare_path_source(self.name, path)}."
                         )
                         self.err_logger.critical(message)
+                    self.PathException = exception
                     raise io_err

elapi/plugins/bill_teams/_doc.py

@@ -1,3 +1,30 @@
+from ...configuration import DEFAULT_EXPORT_DATA_FORMAT
+
+_UNIQUE_SUPPORTED_FORMATS = ["json", "yaml", "txt"]
+supported_format_values = ", ".join(
+    f"**{_.upper()}**" for _ in _UNIQUE_SUPPORTED_FORMATS
+)
+
 __PARAMETERS__doc__ = {
     "invoice_export": "Export output to a location. Invoices are **always exported** by default.\n",
+    "root_directory": "The root of the directory where store-info will create the billing directory structure, "
+    "and save teams and owners information in `JSON`. store-info also sorts the JSON keys "
+    "before saving.",
+    "owners_data_path": "Source path for owners information `CSV` file. Internally referred to as the "
+    "`'billing metadata'. --meta-source` is not required when `--teams-info-only` is passed, "
+    "otherwise it is required.",
+    "target_date": "ISO 8604 'YYYY-MM' for which 'YYYY/MM' directory to store.",
+    "teams_info_only": "If passed, then only `teams-info` will be stored."
+    "Both _--teams-info-only_ and _--owners-info-only_ cannot be passed.",
+    "owners_info_only": "If passed, then only `owners-info` will be stored. "
+    "Both _--teams-info-only_ and _--owners-info-only_ cannot be passed.",
+    "data_format": f"Format style for the output. Supported values are: {supported_format_values}. "
+                   f"CSV is **not** a supported format for this command as the "
+                   f"output data structure is too complex for naive CSV. "
+                   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 "
+                   f"format falls back to `{DEFAULT_EXPORT_DATA_FORMAT.upper()}`.",
 }