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

elapi/VERSION

@@ -1 +1 @@
-1.0.7-dev1
+1.0.7.dev3

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

@@ -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/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.

elapi/configuration/config.py

@@ -1,10 +1,12 @@
+import errno
 import os
 from pathlib import Path
 
 from dynaconf import Dynaconf
 
 from ._config_history import ConfigHistory, InspectConfigHistory
-from .log_file import LOG_FILE_PATH, XDG_DATA_HOME
+from .log_file import LOG_FILE_PATH, _XDG_DATA_HOME
+
 # noinspection PyUnresolvedReferences
 from .._names import (
     APP_NAME,
@@ -25,11 +27,13 @@ from .._names import (
 )
 from ..loggers import Logger
 from ..path import ProperPath
+from ..styles import stdin_console, NoteText
 from ..validators import (
     Validate,
     ValidationError,
     CriticalValidationError,
     PathValidator,
+    PathValidationError,
 )
 
 logger = Logger()
@@ -116,19 +120,24 @@ TOKEN_BEARER: str = "Authorization"
 # Export location
 CONFIG_EXPORT_DIR = ProperPath(
     (_CONFIG_EXPORT_DIR_ORIGINAL := settings.get(KEY_EXPORT_DIR)) or os.devnull,
+    kind=(_CONFIG_EXPORT_DIR_ORIGINAL and "dir") or "file",
     err_logger=logger,
 )  # the default "os.devnull" saves ProperPath from TypeError, ValueError
 # for when settings.get(KEY_EXPORT_DIR) is None/"".
-if _CONFIG_EXPORT_DIR_ORIGINAL and CONFIG_EXPORT_DIR.kind != "dir":
-    logger.warning(
-        f"{KEY_EXPORT_DIR}: {_CONFIG_EXPORT_DIR_ORIGINAL} is not a directory!"
-    )
-    logger.debug("If you want to export to a file use '--export <path-to-file>'.")
-    CONFIG_EXPORT_DIR = None
 try:
     EXPORT_DIR = Validate(PathValidator(CONFIG_EXPORT_DIR)).get()
-except ValidationError:
+except PathValidationError as e:
     if _CONFIG_EXPORT_DIR_ORIGINAL:
+        if e.errno == errno.EEXIST:
+            logger.warning(
+                f"{KEY_EXPORT_DIR}: {_CONFIG_EXPORT_DIR_ORIGINAL} from configuration file is not a directory!"
+            )
+            stdin_console.print(
+                NoteText(
+                    "If you want to export to a file use '--export <path-to-file>'.\n",
+                    stem="Note",
+                )
+            )
         logger.warning(
             f"{KEY_EXPORT_DIR}: {_CONFIG_EXPORT_DIR_ORIGINAL} from configuration file couldn't be validated! "
         )
@@ -149,7 +158,7 @@ except ValidationError:
         logger.critical(
             f"{APP_NAME} couldn't validate {FALLBACK_EXPORT_DIR} to store exported data. "
             f"This is a fatal error. To quickly fix this error define an export directory "
-            f"with 'export_dir' in configuration file. {APP_NAME} will not run!"
+            f"with '{KEY_EXPORT_DIR}' in configuration file. {APP_NAME} will not run!"
         )
         raise CriticalValidationError
 # Falls back to ~/Downloads if $XDG_DOWNLOAD_DIR isn't found
@@ -159,7 +168,7 @@ if LOG_FILE_PATH.parent != LOG_DIR_ROOT:
     APP_DATA_DIR = LOG_FILE_PATH.parent
 else:
     validate_app_dir = Validate(
-        PathValidator([XDG_DATA_HOME / APP_NAME, FALLBACK_DIR / APP_NAME])
+        PathValidator([_XDG_DATA_HOME / APP_NAME, FALLBACK_DIR / APP_NAME])
     )
     try:
         APP_DATA_DIR = validate_app_dir.get()

elapi/configuration/log_file.py

@@ -23,7 +23,7 @@ validate_path = Validate(
     PathValidator(
         [
             LOG_DIR_ROOT / LOG_FILE_NAME,
-            (XDG_DATA_HOME := ProperPath(os.getenv(ENV_XDG_DATA_HOME, os.devnull)))
+            (_XDG_DATA_HOME := ProperPath(os.getenv(ENV_XDG_DATA_HOME, os.devnull)))
             / APP_NAME
             / LOG_FILE_NAME,
             FALLBACK_DIR / LOG_FILE_NAME,

elapi/path.py

@@ -5,23 +5,25 @@ import re
 from contextlib import contextmanager
 from pathlib import Path
 from shutil import rmtree
-from typing import Union, TextIO, Generator
+from typing import Union, TextIO, Generator, Optional
 
+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] = "",
+        kind: Optional[str] = None,  # Here, None => Undefined/unknown
         err_logger: logging.Logger = SimpleLogger(),
     ):
         self.name = name
         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:
@@ -83,7 +103,7 @@ class ProperPath:
 
     @kind.setter
     def kind(self, value) -> None:
-        if not value:
+        if value is None:
             self._kind = (
                 "dir"
                 if self.expanded.is_dir()
@@ -119,25 +139,43 @@ class ProperPath:
             else f"PATH={target}"
         )
 
-    def create(self) -> Union[Path, None]:
-        if not (path := self.expanded.resolve(strict=False)).exists():
-            # except FileNotFoundError:
-            message = (
-                f"{self._error_helper_compare_path_source(self.name, path)} could not be found. "
-                f"An attempt to create PATH={path} will be made."
-            )
-            self.err_logger.warning(message)
+    def create(self, verbose: bool = True) -> Union[Path, None]:
+        path = self.expanded.resolve(strict=False)
         try:
             if self.kind == "file":
                 path_parent, path_file = path.parent, path.name
+                if not path_parent.exists() and verbose:
+                    self.err_logger.info(
+                        f"Directory {self._error_helper_compare_path_source(self.name, path_parent)} could not be "
+                        f"found. An attempt to create directory {path_parent} will be made."
+                    )
                 path_parent.mkdir(parents=True, exist_ok=True)
                 (path_parent / path_file).touch(exist_ok=True)
             elif self.kind == "dir":
+                if not path.exists() and verbose:
+                    self.err_logger.info(
+                        f"Directory {self._error_helper_compare_path_source(self.name, path)} could not be found. "
+                        f"An attempt to create directory {path} will be made."
+                    )
                 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 +191,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 +227,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 +289,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 +305,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 +321,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 +329,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,44 @@
+from ... import APP_NAME
+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()}`.",
+    "export_details": f"- If _'--export'_ is passed without any following value, then it acts as a flag, and "
+                      f"`export_dir` value from configuration file is used. "
+                      f"It should be clear that `export_dir` in a configuration file only accepts a directory path.\n"
+                      f"- If a directory path is provided as a value, "
+                      f"i.e., _'--export \<path/to/directory\>'_, then that path is used instead. "
+                      f"When the path is a directory, "
+                      f"the file name is auto-generated using the following scheme: *'DATE_HHMMSS_\<FUNCTION\>.EXT'*.\n"
+                      f"- If a file path is passed, i.e., _'--export <path/to/file.json>'_, "
+                      f"then data is simply exported to that file. This allows custom file name scheme. "
+                      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"
+
 }