Add a function to get a public logger for a module

.github/keylabeler.yml

@@ -16,6 +16,7 @@ labelMappings:
   "part:collections": "part:collections"
   "part:datetime": "part:datetime"
   "part:docs": "part:docs"
+  "part:logging": "part:logging"
   "part:math": "part:math"
   "part:tests": "part:tests"
   "part:tooling": "part:tooling"

.github/labeler.yml

@@ -63,6 +63,14 @@
       - "examples/**"
       - LICENSE
 
+"part:logging":
+  - changed-files:
+    - any-glob-to-any-file:
+      - "src/frequenz/core/logging.py"
+      - "src/frequenz/core/logging/**"
+      - "tests/test_logging.py"
+      - "tests/logging/**"
+
 "part:math":
   - changed-files:
     - any-glob-to-any-file:

src/frequenz/core/logging.py

@@ -0,0 +1,38 @@
+# License: MIT
+# Copyright © 2023 Frequenz Energy-as-a-Service GmbH
+
+"""Logging tools."""
+
+import logging
+
+
+def get_public_logger(module_name: str) -> logging.Logger:
+    """Get a logger for the public module containing the given module name.
+
+    * Modules are considered private if they start with `_`.
+    * All modules inside a private module are also considered private, even if they
+      don't start with `_`.
+    * If there is no leading public part, the root logger is returned.
+
+    Example:
+        Here are a few examples of how this function will resolve module names:
+
+        * `some.pub` -> `some.pub`
+        * `some.pub._some._priv` -> `some.pub`
+        * `some.pub._some._priv.public` -> `some.pub`
+        * `some.pub._some._priv.public._private` -> `some.pub`
+        * `_priv` -> `root`
+
+    Args:
+        module_name: The fully qualified name of the module to get the logger for
+            (normally the `__name__` built-in variable).
+
+    Returns:
+        The logger for the public module containing the given module name.
+    """
+    public_parts: list[str] = []
+    for part in module_name.split("."):
+        if part.startswith("_"):
+            break
+        public_parts.append(part)
+    return logging.getLogger(".".join(public_parts))

tests/test_logging.py

@@ -0,0 +1,29 @@
+# License: MIT
+# Copyright © 2024 Frequenz Energy-as-a-Service GmbH
+
+"""Tests for the log module."""
+
+
+import pytest
+
+from frequenz.core.logging import get_public_logger
+
+
+@pytest.mark.parametrize(
+    "module_name, expected_logger_name",
+    [
+        ("some.pub", "some.pub"),
+        ("some.pub._some._priv", "some.pub"),
+        ("some.pub._some._priv.public", "some.pub"),
+        ("some.pub._some._priv.public._private", "some.pub"),
+        ("some._priv.pub", "some"),
+        ("_priv.some.pub", "root"),
+        ("some", "some"),
+        ("some._priv", "some"),
+        ("_priv", "root"),
+    ],
+)
+def test_get_public_logger(module_name: str, expected_logger_name: str) -> None:
+    """Test that the logger name is as expected."""
+    logger = get_public_logger(module_name)
+    assert logger.name == expected_logger_name