Merge pull request #22 from MrClock8163/feature/logging-improvements

Logging improvements

Author: MrClock8163

docs/about.rst

@@ -1,6 +1,14 @@
 Information
 ===========
 
+Documentation
+-------------
+
+The different commands are documented in their application groups to give
+a better overview of the processes. Every page shows the actual command to
+invoke the program, some additional context and optional examples, and an
+automatically generated view of the ``--help`` page of the command.
+
 Command Structure
 -----------------
 
@@ -21,10 +29,19 @@ commands:
     iman validate sets -h
     iman calc sets -h
 
-Documentation
--------------
+Logging
+-------
 
-The different commands are documented in their application groups to give
-a better overview of the processes. Every page shows the actual command to
-invoke the program, some additional context and optional examples, and an
-automatically generated view of the ``--help`` page of the command.
+Various commands (primarily the measurement programs) support logging. The
+logging can be set up through the logging options of the root command ``iman``.
+These have to be set before specifying the command groups.
+
+.. code-block:: shell
+
+    iman --info --file iman.log measure ...
+
+Usage
+-----
+
+.. click:: instrumentman:cli
+    :prog: iman

docs/commands/sets/measure.rst

@@ -50,11 +50,6 @@ controlling computer (e.g. Task Scheduler on Windows, crontab on Linux).
 Examples
 --------
 
-.. code-block:: shell
-    :caption: Logging to file
-
-    iman measure sets --debug COM3 targets.json results >> tps.log 2>&1
-
 .. code-block:: shell
     :caption: Enabling connection retries and timeout recovery attempts (might be useful with bluetooth connections)
 

src/instrumentman/__init__.py

@@ -1,10 +1,20 @@
+from pathlib import Path
+
 from click_extra import extra_group, version_option
 
 try:
     from ._version import __version__ as __version__
 except Exception:
     __version__ = "0.0.0"  # Placeholder value for source installs
 
+from .utils import (
+    logging_option_group,
+    logging_levels_constraint,
+    logging_output_constraint,
+    logging_target_constraint,
+    logging_rotation_constraint,
+    configure_logging
+)
 from . import morse
 from . import terminal
 from . import setup
@@ -18,12 +28,47 @@
 from . import settings
 
 
-@extra_group("iman", params=None)  # type: ignore[misc]
+@extra_group(
+    "iman",
+    params=None,
+    context_settings={"auto_envvar_prefix": None}
+)  # type: ignore[misc]
 @version_option()
-def cli() -> None:
+@logging_option_group()
+@logging_levels_constraint()
+@logging_output_constraint()
+@logging_target_constraint()
+@logging_rotation_constraint()
+def cli(
+    protocol: bool = False,
+    debug: bool = False,
+    info: bool = False,
+    warning: bool = False,
+    error: bool = False,
+    critical: bool = False,
+    file: Path | None = None,
+    stdout: bool = False,
+    stderr: bool = False,
+    format: str = "{message}",
+    dateformat: str = "%Y-%m-%d %H:%M:%S",
+    rotate: tuple[int, int] | None = None
+) -> None:
     """Automated measurement programs and related utilities for surveying
     instruments."""
-    pass
+    configure_logging(
+        protocol,
+        debug,
+        info,
+        warning,
+        error,
+        critical,
+        file,
+        stderr,
+        stdout,
+        format,
+        dateformat,
+        rotate
+    )
 
 
 @cli.group("measure")  # type: ignore[misc]

src/instrumentman/datatransfer/__init__.py

@@ -41,7 +41,7 @@
     default=True
 )
 @option(
-    "--inclide-eof/--no-include-eof",
+    "--include-eof/--no-include-eof",
     help=(
         "wether the EOF marker is part of the output format "
         "(or just sent by the instrument regardless of the format in question)"

src/instrumentman/datatransfer/app.py

@@ -1,4 +1,5 @@
 from io import BufferedWriter, TextIOWrapper
+from logging import getLogger
 
 from serial import SerialTimeoutException
 from rich.progress import Progress, TextColumn
@@ -18,39 +19,50 @@ def main_download(
     include_eof: bool = False
 ) -> None:
     eof_bytes = eof.encode("ascii")
+    logger = getLogger("iman.data.download")
     with open_serial(
         port,
         speed=baud,
-        timeout=timeout
+        timeout=timeout,
+        logger=logger.getChild("com")
     ) as com:
         eol_bytes = com.eombytes
         started = False
+        logger.info("Starting data download")
+        logger.debug("Waiting for first line...")
         while True:
             try:
                 data = com.receive_binary()
-                started = True
+                if not started:
+                    started = True
+                    logger.debug("Received first line...")
 
                 if data == eof_bytes and autoclose and not include_eof:
                     echo_green("Download finished (end-of-file)")
-                    return
+                    logger.info("Download finished (end-of-file)")
+                    break
 
                 echo(data.decode("ascii", "replace"))
                 if output is not None:
                     output.write(data + eol_bytes)
 
                 if data == eof_bytes and autoclose:
                     echo_green("Download finished (end-of-file)")
-                    return
+                    logger.info("Download finished (end-of-file)")
+                    break
             except SerialTimeoutException:
                 if started and autoclose:
                     echo_green("Download finished (timeout)")
-                    return
+                    logger.info("Download finished (timeout)")
+                    break
             except KeyboardInterrupt:
                 echo_yellow("Download stopped manually")
-                return
+                logger.info("Download stopped manually")
+                break
             except Exception as e:
                 echo_red(f"Download interrupted by error ({e})")
-                return
+                logger.exception("Download interrupted by error")
+                break
 
 
 def main_upload(
@@ -60,12 +72,16 @@ def main_upload(
     timeout: int = 15,
     skip: int = 0
 ) -> None:
+    logger = getLogger("iman.data.upload")
     with open_serial(
         port,
         speed=baud,
-        timeout=timeout
+        timeout=timeout,
+        logger=logger.getChild("com")
     ) as com:
         try:
+            logger.info("Starting data upload")
+            logger.debug(f"Skipping {skip} line(s)")
             for _ in range(skip):
                 next(file)
 
@@ -76,8 +92,12 @@ def main_upload(
                 for line in progress.track(file, description="Uploading..."):
                     com.send(line)
 
+        except KeyboardInterrupt:
+            echo_yellow("Upload cancelled")
+            logger.info("Upload cancelled by user")
         except Exception as e:
             echo_red(f"Upload interrupted by error ({e})")
-            return
-
-        echo_green("Upload finished")
+            logger.exception("Upload interrupted by error")
+        else:
+            echo_green("Upload finished")
+            logger.info("Upload finished")