logdruid 0.1.0.dev2__tar.gz → 0.1.0.dev3__tar.gz

{logdruid-0.1.0.dev2 → logdruid-0.1.0.dev3}/LICENSE

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2026 Frank Herbrand
+Copyright (c) 2026 github.com/fherb2
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

{logdruid-0.1.0.dev2 → logdruid-0.1.0.dev3}/PKG-INFO

@@ -1,19 +1,22 @@
 Metadata-Version: 2.4
 Name: logdruid
-Version: 0.1.0.dev2
+Version: 0.1.0.dev3
 Summary: A drop-in logging setup layer for multi-process applications, built on loguru.
 License-Expression: MIT
 License-File: LICENSE
-Author: Frank Herbrand
-Author-email: f.herbrand@hzdr.de
+Author: github.com/fherb2
 Requires-Python: >=3.11,<4.0
+Classifier: Development Status :: 3 - Alpha
+Classifier: Operating System :: POSIX :: Linux
 Classifier: Programming Language :: Python :: 3
 Classifier: Programming Language :: Python :: 3.11
 Classifier: Programming Language :: Python :: 3.12
 Classifier: Programming Language :: Python :: 3.13
-Classifier: Programming Language :: Python :: 3.14
-Classifier: Programming Language :: Python :: 3.15
 Requires-Dist: loguru (>=0.7.3)
+Project-URL: Changelog, https://fherb2.github.io/logdruid/changelog/
+Project-URL: Documentation, https://fherb2.github.io/logdruid/
+Project-URL: Issues, https://github.com/fherb2/logdruid/issues
+Project-URL: Repository, https://github.com/fherb2/logdruid
 Description-Content-Type: text/markdown
 
 # logdruid
@@ -24,8 +27,7 @@ Description-Content-Type: text/markdown
 A drop-in logging setup layer for multi-process applications, built on
 [loguru](https://loguru.readthedocs.io/).
 
-**Installation, usage, configuration and API:
-<https://fherb2.github.io/logdruid/>**
+**[Documentation](https://fherb2.github.io/logdruid/)** – installation, usage, configuration and API.
 
 ## What it is for
 
@@ -65,13 +67,12 @@ through `logging`.
 | Configuration from a file, precedence defaults < application < file < command line | no, only environment variables | yes |
 | Mistakes in the configuration do not stop the application | no | yes, they only produce a warning |
 
-## For contributors
+## Documentation
 
-Design rules and rationale are in
-[`running_implementation_doc/`](https://github.com/fherb2/logdruid/tree/main/running_implementation_doc)
-(in German).
+Installation, usage, configuration, the API reference and the changelog:
+<https://fherb2.github.io/logdruid/>
 
 ## License
 
-MIT, see [`LICENSE`](https://github.com/fherb2/logdruid/blob/main/LICENSE).
+MIT, see [LICENSE](https://github.com/fherb2/logdruid/blob/main/LICENSE).
 

{logdruid-0.1.0.dev2 → logdruid-0.1.0.dev3}/README.md

@@ -6,8 +6,7 @@
 A drop-in logging setup layer for multi-process applications, built on
 [loguru](https://loguru.readthedocs.io/).
 
-**Installation, usage, configuration and API:
-<https://fherb2.github.io/logdruid/>**
+**[Documentation](https://fherb2.github.io/logdruid/)** – installation, usage, configuration and API.
 
 ## What it is for
 
@@ -47,12 +46,11 @@ through `logging`.
 | Configuration from a file, precedence defaults < application < file < command line | no, only environment variables | yes |
 | Mistakes in the configuration do not stop the application | no | yes, they only produce a warning |
 
-## For contributors
+## Documentation
 
-Design rules and rationale are in
-[`running_implementation_doc/`](https://github.com/fherb2/logdruid/tree/main/running_implementation_doc)
-(in German).
+Installation, usage, configuration, the API reference and the changelog:
+<https://fherb2.github.io/logdruid/>
 
 ## License
 
-MIT, see [`LICENSE`](https://github.com/fherb2/logdruid/blob/main/LICENSE).
+MIT, see [LICENSE](https://github.com/fherb2/logdruid/blob/main/LICENSE).

{logdruid-0.1.0.dev2 → logdruid-0.1.0.dev3}/pyproject.toml

@@ -4,19 +4,33 @@ build-backend = "poetry.core.masonry.api"
 
 [project]
 name = "logdruid"
-version = "0.1.0.dev2"
+version = "0.1.0.dev3"
 description = "A drop-in logging setup layer for multi-process applications, built on loguru."
 readme = "README.md"
 requires-python = ">=3.11,<4.0"
 license = "MIT"
 license-files = ["LICENSE"]
 authors = [
-    { name = "Frank Herbrand", email = "f.herbrand@hzdr.de" },
+    { name = "github.com/fherb2" },
+]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Operating System :: POSIX :: Linux",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
 ]
 dependencies = [
     "loguru>=0.7.3",
 ]
 
+[project.urls]
+Documentation = "https://fherb2.github.io/logdruid/"
+Repository = "https://github.com/fherb2/logdruid"
+Issues = "https://github.com/fherb2/logdruid/issues"
+Changelog = "https://fherb2.github.io/logdruid/changelog/"
+
 [tool.poetry]
 packages = [{ include = "logdruid", from = "src" }]
 

logdruid-0.1.0.dev3/src/logdruid/__init__.py

@@ -0,0 +1,22 @@
+"""A logging setup layer for multi-process applications, built on loguru.
+
+Reporting uses loguru's own logger unchanged. logdruid sets it up and adds
+one time-ordered output for all processes, the takeover of the standard
+``logging`` module, and a configuration file of its own.
+
+Documentation: https://fherb2.github.io/logdruid/
+"""
+
+from .logdruid import (
+    CONFIG_FILE_NAME,
+    LogLink,
+    attach,
+    check_config,
+    link,
+    logger,
+    setup,
+    shutdown,
+)
+
+__all__ = ["logger", "setup", "check_config", "link", "attach", "shutdown",
+           "LogLink", "CONFIG_FILE_NAME"]

{logdruid-0.1.0.dev2 → logdruid-0.1.0.dev3}/src/logdruid/logdruid.py

@@ -24,8 +24,12 @@ from loguru import logger
 
 # --- Module parameters ------------------------------------------------
 
-# Name of the configuration file looked for next to the entry point.
 CONFIG_FILE_NAME = "logdruid.toml"
+"""Name of the configuration file setup() looks for next to the entry point."""
+
+# Name under which logdruid writes its own warnings. They bypass the
+# minimum levels: a level set too high must not hide a configuration error.
+OWN_NAME = "logdruid"
 
 # Lowest layer: what applies when neither API, file nor command line
 # say anything. No translation, one level for everything.
@@ -112,16 +116,8 @@ class LogLink:
     """What a child process needs to log into the main process.
 
     Created by link() in the main process and handed to the child as an
-    argument; the child passes it to attach().
-
-    Attributes
-    ----------
-    process_name : str
-        Name the child process carries in every message.
-    conn : multiprocessing.connection.Connection
-        Write end of the child's own pipe.
-    settings : Settings
-        Resolved configuration of the main process.
+    argument; the child passes it to attach(). Its fields are internal;
+    only release() is part of the public interface.
     """
 
     process_name: str
@@ -171,15 +167,8 @@ def setup(config_path: Optional[Path] = None, *,
 
     mp.current_process().name = process_name
     warnings: List[str] = []
-    file_layer = _read_config_file(config_path, warnings)
-    cli_layer: Dict[str, Any] = {}
-    if cli_level is not None:
-        cli_layer["std_level"] = cli_level
-    if cli_log_file is not None:
-        cli_layer["output"] = {"file": {"path": cli_log_file}}
-
-    raw_layers = [cli_layer, file_layer, defaults or {}, MODULE_DEFAULTS]
-    _settings = _resolve(raw_layers, warnings)
+    _settings = _load_settings(config_path, defaults, cli_level, cli_log_file,
+                               warnings)
     _threshold_cache.clear()
 
     logger.remove()
@@ -195,7 +184,33 @@ def setup(config_path: Optional[Path] = None, *,
     atexit.register(shutdown)
 
     for text in warnings:
-        logger.warning(text)
+        _output.patch(_own_name).warning(text)
+
+
+def check_config(config_path: Optional[Path] = None, *,
+                 defaults: Optional[Dict[str, Any]] = None,
+                 cli_level: Optional[str] = None,
+                 cli_log_file: Optional[str] = None) -> List[str]:
+    """Check a configuration without setting anything up.
+
+    Resolves the same layers as setup() and returns the warnings setup()
+    would report about them. Whether an output can actually be created,
+    for example whether the path of the log file is writable, only setup()
+    finds out.
+
+    Parameters
+    ----------
+    config_path, defaults, cli_level, cli_log_file
+        As for setup().
+
+    Returns
+    -------
+    list of str
+        The warnings; empty if the configuration is sound.
+    """
+    warnings: List[str] = []
+    _load_settings(config_path, defaults, cli_level, cli_log_file, warnings)
+    return warnings
 
 
 def link(process_name: str) -> LogLink:
@@ -258,6 +273,22 @@ def shutdown() -> None:
 
 # --- Configuration ----------------------------------------------------
 
+def _load_settings(config_path: Optional[Path],
+                   defaults: Optional[Dict[str, Any]],
+                   cli_level: Optional[str],
+                   cli_log_file: Optional[str],
+                   warnings: List[str]) -> Settings:
+    """Resolve the four layers into Settings, collecting the warnings."""
+    file_layer = _read_config_file(config_path, warnings)
+    cli_layer: Dict[str, Any] = {}
+    if cli_level is not None:
+        cli_layer["std_level"] = cli_level
+    if cli_log_file is not None:
+        cli_layer["output"] = {"file": {"path": cli_log_file}}
+    raw_layers = [cli_layer, file_layer, defaults or {}, MODULE_DEFAULTS]
+    return _resolve(raw_layers, warnings)
+
+
 def _read_config_file(config_path: Optional[Path],
                       warnings: List[str]) -> Dict[str, Any]:
     """Return the file layer, or an empty one with a warning."""
@@ -528,6 +559,11 @@ def _take_over_std_logging(process: str) -> None:
 
 # --- Transport between the processes ------------------------------------
 
+def _own_name(record: Dict[str, Any]) -> None:
+    """loguru patcher: mark a message as logdruid's own warning."""
+    record.update(name=OWN_NAME)
+
+
 def _to_item(message) -> Dict[str, Any]:
     """What travels for one message: its data, not loguru's objects."""
     record = message.record
@@ -595,7 +631,7 @@ class _Collector(threading.Thread):
         self._stopping = True
         self.join(timeout_s)
         if self.is_alive():
-            self._output.warning(
+            self._output.patch(_own_name).warning(
                 f"Logging pipes of {sorted(self._pipes.values())} did not "
                 f"end within {timeout_s} s; their remaining messages are lost")
         with self._lock:
@@ -648,9 +684,9 @@ class _Collector(threading.Thread):
             name = self._pipes.pop(conn, "?")
         conn.close()
         if exc is not None:
-            self._output.warning(f"Logging pipe of {name} broke off "
-                                 f"({type(exc).__name__}); later messages "
-                                 f"of that process are lost")
+            self._output.patch(_own_name).warning(
+                f"Logging pipe of {name} broke off ({type(exc).__name__}); "
+                f"later messages of that process are lost")
 
     def _push(self, item: Dict[str, Any]) -> None:
         """Queue a message by its time stamp."""

logdruid-0.1.0.dev2/src/logdruid/__init__.py

@@ -1,86 +0,0 @@
-"""Logging setup for multi-process applications: a setup layer around loguru.
-
-Reporting uses loguru unchanged: `logger` is loguru's global logger.
-This module only sets it up, and adds what loguru does not offer:
-
-- One output in the main process. Console and file are created there
-  only; every child process sends its messages through a pipe of its
-  own. Unlike loguru's ``enqueue=True`` no lock is shared between
-  processes, so a child that is killed hard blocks nobody but itself.
-- Ordering by time. The main process holds messages back for a short
-  window and writes them sorted by their time stamp, its own included.
-- Taking over the standard ``logging`` module, with the logger name as
-  the name of the message and with levels translated per logger.
-- Levels per process and per name, configured in ``logdruid.toml`` in
-  four layers: module defaults < API < file < command line.
-
-Usage
------
-Main process, once, before any child process is created:
-
->>> import logdruid
->>> from logdruid import logger
->>> logdruid.setup(config_path, cli_level=args.log_level)
->>> logger.success("Logging active")
-
-Per child process, in the main process:
-
->>> link = logdruid.link("raw_writer")
->>> process = ctx.Process(target=raw_writer_prc, args=(link, ...),
-...                       name="raw_writer")
->>> process.start()
->>> link.release()
-
-First thing in the child process (after ignoring SIGINT):
-
->>> logdruid.attach(link)
-
-At the end of the main process, after the children have ended:
-
->>> logdruid.shutdown()
-
-Configuration file (all keys optional)::
-
-    std_level = "INFO"            # level of everything without its own
-    sort_window_ms = 100          # 0 switches the ordering off
-
-    [output.console]              # parameters of loguru's add(),
-    enabled = true                # passed through; 'enabled' and
-    format = "..."                # 'path' are logdruid's own
-    diagnose = false
-
-    [output.file]
-    enabled = false
-    path = "app.log"
-    rotation = "10 MB"
-    retention = 5
-
-    [processes.raw_writer]
-    level = "DEBUG"
-
-    [loggers.ognbligg]            # applies to ognbligg.* as well
-    level = "INFO"
-    translate = { DEBUG = "TRACE", INFO = false }   # false drops
-
-Notes on further development
-----------------------------
-- An application started through a packaged entry point has no
-  ``logdruid.toml`` next to ``__main__``; it passes the path instead.
-- Exceptions travel through the pipe as text formatted in the child;
-  ``backtrace`` and ``diagnose`` therefore act where a message arises.
-"""
-
-
-from .logdruid import (
-    CONFIG_FILE_NAME,
-    LogLink,
-    Settings,
-    attach,
-    link,
-    logger,
-    setup,
-    shutdown,
-)
-
-__all__ = ["logger", "setup", "link", "attach", "shutdown", "LogLink",
-           "Settings", "CONFIG_FILE_NAME"]