logdruid 0.1.0.dev1__tar.gz → 0.1.0.dev3__tar.gz

{logdruid-0.1.0.dev1 → 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.dev3/PKG-INFO

@@ -0,0 +1,78 @@
+Metadata-Version: 2.4
+Name: logdruid
+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: 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
+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
+
+[![PyPI version](https://img.shields.io/pypi/v/logdruid.svg)](https://pypi.org/project/logdruid/)
+[![Tests](https://github.com/fherb2/logdruid/actions/workflows/tests.yml/badge.svg)](https://github.com/fherb2/logdruid/actions/workflows/tests.yml)
+
+A drop-in logging setup layer for multi-process applications, built on
+[loguru](https://loguru.readthedocs.io/).
+
+**[Documentation](https://fherb2.github.io/logdruid/)** – installation, usage, configuration and API.
+
+## What it is for
+
+loguru is a logging library for Python with exactly one global logger. In an
+application with several processes, loguru alone reaches its limits: each
+process started with `spawn` has its own logger with its own outputs; a
+shared output across processes goes through a queue whose lock spans all
+processes, so a process killed hard while holding it can block logging
+everywhere; and messages from libraries that report through the standard
+`logging` module do not appear in loguru's outputs.
+
+logdruid is a setup layer around loguru for exactly this case: applications
+– not libraries – with several processes. It does not build a logging API of
+its own: you keep reporting with loguru's logger, unchanged. logdruid only
+sets it up and adds what loguru does not offer: one shared output for all
+processes, ordered by time, without a lock across process boundaries; taking
+over the messages from `logging`; and a configuration in a file of its own.
+
+For an application with a single process, loguru alone is enough, as it is
+when each process may write to its own file and the order across processes
+does not matter. Libraries should use neither loguru nor logdruid but report
+through `logging`.
+
+## Features
+
+| Feature | loguru alone | with logdruid |
+| --- | --- | --- |
+| Reporting with `logger.info(...)` etc., levels `TRACE` to `CRITICAL` including `SUCCESS` | yes | yes, the same logger and the same API |
+| Console and file, rotation and retention of the file, format, colours | yes | yes, set in the configuration file |
+| Exceptions with extended tracebacks, optionally with variable values | yes | yes |
+| All processes write into one shared output | yes, through a shared queue with a lock across all processes | yes, through a pipe of its own per child process, without a shared lock |
+| A process killed hard does not hold up the others | not guaranteed | yes |
+| Messages of all processes ordered by time | no, order of arrival | yes, with an adjustable time window |
+| Minimum level per name of a message (module, logger) | yes, through a filter | yes |
+| Minimum level per process | no | yes |
+| Taking over messages from `logging` | only as a code example in loguru's documentation | yes, with the logger's name and with level translation per logger |
+| 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 |
+
+## Documentation
+
+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).
+

logdruid-0.1.0.dev3/README.md

@@ -0,0 +1,56 @@
+# logdruid
+
+[![PyPI version](https://img.shields.io/pypi/v/logdruid.svg)](https://pypi.org/project/logdruid/)
+[![Tests](https://github.com/fherb2/logdruid/actions/workflows/tests.yml/badge.svg)](https://github.com/fherb2/logdruid/actions/workflows/tests.yml)
+
+A drop-in logging setup layer for multi-process applications, built on
+[loguru](https://loguru.readthedocs.io/).
+
+**[Documentation](https://fherb2.github.io/logdruid/)** – installation, usage, configuration and API.
+
+## What it is for
+
+loguru is a logging library for Python with exactly one global logger. In an
+application with several processes, loguru alone reaches its limits: each
+process started with `spawn` has its own logger with its own outputs; a
+shared output across processes goes through a queue whose lock spans all
+processes, so a process killed hard while holding it can block logging
+everywhere; and messages from libraries that report through the standard
+`logging` module do not appear in loguru's outputs.
+
+logdruid is a setup layer around loguru for exactly this case: applications
+– not libraries – with several processes. It does not build a logging API of
+its own: you keep reporting with loguru's logger, unchanged. logdruid only
+sets it up and adds what loguru does not offer: one shared output for all
+processes, ordered by time, without a lock across process boundaries; taking
+over the messages from `logging`; and a configuration in a file of its own.
+
+For an application with a single process, loguru alone is enough, as it is
+when each process may write to its own file and the order across processes
+does not matter. Libraries should use neither loguru nor logdruid but report
+through `logging`.
+
+## Features
+
+| Feature | loguru alone | with logdruid |
+| --- | --- | --- |
+| Reporting with `logger.info(...)` etc., levels `TRACE` to `CRITICAL` including `SUCCESS` | yes | yes, the same logger and the same API |
+| Console and file, rotation and retention of the file, format, colours | yes | yes, set in the configuration file |
+| Exceptions with extended tracebacks, optionally with variable values | yes | yes |
+| All processes write into one shared output | yes, through a shared queue with a lock across all processes | yes, through a pipe of its own per child process, without a shared lock |
+| A process killed hard does not hold up the others | not guaranteed | yes |
+| Messages of all processes ordered by time | no, order of arrival | yes, with an adjustable time window |
+| Minimum level per name of a message (module, logger) | yes, through a filter | yes |
+| Minimum level per process | no | yes |
+| Taking over messages from `logging` | only as a code example in loguru's documentation | yes, with the logger's name and with level translation per logger |
+| 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 |
+
+## Documentation
+
+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).

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

@@ -4,19 +4,33 @@ build-backend = "poetry.core.masonry.api"
 
 [project]
 name = "logdruid"
-version = "0.1.0.dev1"
+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.dev1 → 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.dev1/PKG-INFO

@@ -1,97 +0,0 @@
-Metadata-Version: 2.4
-Name: logdruid
-Version: 0.1.0.dev1
-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
-Requires-Python: >=3.11,<4.0
-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)
-Description-Content-Type: text/markdown
-
-# logdruid
-
-[![PyPI version](https://img.shields.io/pypi/v/logdruid.svg)](https://pypi.org/project/logdruid/)
-[![Tests](https://github.com/fherb2/logdruid/actions/workflows/tests.yml/badge.svg)](https://github.com/fherb2/logdruid/actions/workflows/tests.yml)
-
-A drop-in logging setup layer for multi-process applications, built on
-[loguru](https://loguru.readthedocs.io/).
-
-logdruid does not replace loguru's API — it uses it unchanged — and adds
-what a multi-process application needs on top: a single, time-ordered
-output across process boundaries, without a lock shared between
-processes, and the ability to take over messages from libraries that
-report through the standard `logging` module.
-
-## Installation
-
-```bash
-pip install logdruid
-```
-
-Requires Python 3.11 or later.
-
-## Usage
-
-Main process, once, before any child process is created:
-
-```python
-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:
-
-```python
-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`):
-
-```python
-logdruid.attach(link)
-```
-
-At the end of the main process, after the children have ended:
-
-```python
-logdruid.shutdown()
-```
-
-Application modules report through `from logdruid import logger` — loguru's
-own global logger, unchanged. Libraries that report through the standard
-`logging` module need no changes of their own; logdruid takes over their
-messages and applies the level translations configured for them.
-
-## Configuration
-
-Everything logdruid-specific lives in a `logdruid.toml` file next to the
-application's entry point. A fully commented example, including how to
-assign levels per process and per logger and how to translate a library's
-levels into the application's own scheme, is in
-[`examples/logdruid.toml`](examples/logdruid.toml).
-
-## Documentation
-
-The full set of project-wide rules and design rationale is in
-[`running_implementation_doc/implementierungsdoku.md`](running_implementation_doc/implementierungsdoku.md)
-(in German).
-
-## License
-
-MIT, see [`LICENSE`](LICENSE).
-

logdruid-0.1.0.dev1/README.md

@@ -1,78 +0,0 @@
-# logdruid
-
-[![PyPI version](https://img.shields.io/pypi/v/logdruid.svg)](https://pypi.org/project/logdruid/)
-[![Tests](https://github.com/fherb2/logdruid/actions/workflows/tests.yml/badge.svg)](https://github.com/fherb2/logdruid/actions/workflows/tests.yml)
-
-A drop-in logging setup layer for multi-process applications, built on
-[loguru](https://loguru.readthedocs.io/).
-
-logdruid does not replace loguru's API — it uses it unchanged — and adds
-what a multi-process application needs on top: a single, time-ordered
-output across process boundaries, without a lock shared between
-processes, and the ability to take over messages from libraries that
-report through the standard `logging` module.
-
-## Installation
-
-```bash
-pip install logdruid
-```
-
-Requires Python 3.11 or later.
-
-## Usage
-
-Main process, once, before any child process is created:
-
-```python
-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:
-
-```python
-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`):
-
-```python
-logdruid.attach(link)
-```
-
-At the end of the main process, after the children have ended:
-
-```python
-logdruid.shutdown()
-```
-
-Application modules report through `from logdruid import logger` — loguru's
-own global logger, unchanged. Libraries that report through the standard
-`logging` module need no changes of their own; logdruid takes over their
-messages and applies the level translations configured for them.
-
-## Configuration
-
-Everything logdruid-specific lives in a `logdruid.toml` file next to the
-application's entry point. A fully commented example, including how to
-assign levels per process and per logger and how to translate a library's
-levels into the application's own scheme, is in
-[`examples/logdruid.toml`](examples/logdruid.toml).
-
-## Documentation
-
-The full set of project-wide rules and design rationale is in
-[`running_implementation_doc/implementierungsdoku.md`](running_implementation_doc/implementierungsdoku.md)
-(in German).
-
-## License
-
-MIT, see [`LICENSE`](LICENSE).

logdruid-0.1.0.dev1/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"]