[core] added logging options to root command

Author: MrClock8163

src/instrumentman/__init__.py

@@ -1,10 +1,21 @@
+from pathlib import Path
+from logging import getLogger
+
 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
@@ -20,10 +31,37 @@
 
 @extra_group("iman", params=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(
+    debug: bool = False,
+    info: bool = False,
+    warning: bool = False,
+    error: 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(
+        debug,
+        info,
+        warning,
+        error,
+        file,
+        stderr,
+        stdout,
+        format,
+        dateformat,
+        rotate
+    )
 
 
 @cli.group("measure")  # type: ignore[misc]

src/instrumentman/utils.py

@@ -1,7 +1,20 @@
-from logging import DEBUG, ERROR, INFO, WARNING, Logger
+from logging import (
+    DEBUG,
+    ERROR,
+    INFO,
+    WARNING,
+    NOTSET,
+    Logger,
+    StreamHandler,
+    basicConfig,
+    Handler
+)
+from sys import stdout, stderr
+from logging.handlers import RotatingFileHandler
 import os
 from typing import Any, Callable, cast, TypeVar
 from re import compile
+from pathlib import Path
 
 from click_extra import (
     Color,
@@ -12,11 +25,20 @@
     argument,
     Choice,
     IntRange,
+    file_path,
     ParamType,
     Context,
     Parameter
 )
-from cloup.constraints import mutually_exclusive
+from cloup.constraints import (
+    ErrorFmt,
+    constraint,
+    mutually_exclusive,
+    require_one,
+    require_all,
+    If,
+    AnySet
+)
 
 
 F = TypeVar('F', bound=Callable[..., Any])
@@ -126,7 +148,78 @@ def logging_option_group() -> Callable[[F], F]:
             "--error",
             is_flag=True
         ),
-        constraint=mutually_exclusive
+        option(
+            "--file",
+            help="log to file",
+            type=file_path(readable=False)
+        ),
+        option(
+            "--stdout",
+            help="log to standard output",
+            is_flag=True
+        ),
+        option(
+            "--stderr",
+            help="log to standard error",
+            is_flag=True
+        ),
+        option(
+            "--format",
+            help=(
+                "logging format string (as accepted by the `logging` package "
+                "in '{' style)"
+            ),
+            type=str,
+            default="{asctime} <{name}> [{levelname}] {message}"
+        ),
+        option(
+            "--dateformat",
+            help="date-time format spec (as accepted by `strftime`)",
+            type=str,
+            default="%Y-%m-%d %H:%M:%S"
+        ),
+        option(
+            "--rotate",
+            help=(
+                "number of backup log files to rotate, and maximum size "
+                "(in bytes) of a log file before rotation"
+            ),
+            type=(IntRange(1), IntRange(1))
+        )
+    )
+
+
+def logging_levels_constraint() -> Callable[[F], F]:
+    return constraint(
+        mutually_exclusive,
+        ["debug", "info", "warning", "error"]
+    )
+
+
+def logging_output_constraint() -> Callable[[F], F]:
+    return constraint(
+        If(AnySet("file", "stdout", "stderr"), require_one),
+        ["debug", "info", "warning", "error"]
+    )
+
+
+def logging_target_constraint() -> Callable[[F], F]:
+    return constraint(
+        If(AnySet("debug", "info", "warning", "error"), require_one),
+        ["file", "stdout", "stderr"]
+    )
+
+
+def logging_rotation_constraint() -> Callable[[F], F]:
+    return constraint(
+        If("rotate", require_all).rephrased(
+            help="required if --rotate is set",
+            error=(
+                "when --rotate is set, the following parameter must also be "
+                f"set:\n{ErrorFmt.param_list}"
+            )
+        ),
+        ["file"]
     )
 
 
@@ -200,6 +293,62 @@ def make_directory(filepath: str) -> None:
     os.makedirs(dirname, exist_ok=True)
 
 
+def configure_logging(
+    debug: bool = False,
+    info: bool = False,
+    warning: bool = False,
+    error: bool = False,
+    to_path: Path | None = None,
+    to_stdout: bool = False,
+    to_stderr: bool = False,
+    format: str = "{message}",
+    dateformat: str = "%Y-%m-%d %H:%M:%S",
+    rotate: tuple[int, int] | None = None
+) -> None:
+    if not any((debug, info, warning, error)):
+        return
+
+    level = NOTSET
+    if debug:
+        level = DEBUG
+    elif info:
+        level = INFO
+    elif warning:
+        level = WARNING
+    elif error:
+        level = ERROR
+
+    handlers: list[Handler] = []
+    if to_path is not None:
+        max_size = 0
+        backups = 0
+        if rotate is not None:
+            backups, max_size = rotate
+
+        handlers.append(
+            RotatingFileHandler(
+                to_path,
+                encoding="utf8",
+                maxBytes=max_size,
+                backupCount=backups
+            )
+        )
+
+    if to_stdout:
+        handlers.append(StreamHandler(stdout))
+
+    if to_stderr:
+        handlers.append(StreamHandler(stderr))
+
+    basicConfig(
+        format=format,
+        datefmt=dateformat,
+        style="{",
+        level=level,
+        handlers=handlers
+    )
+
+
 def make_logger(
     name: str,
     debug: bool = False,