reconplogger 5.0.0.dev1__tar.gz → 5.0.0.dev2__tar.gz

{reconplogger-5.0.0.dev1/reconplogger.egg-info → reconplogger-5.0.0.dev2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: reconplogger
-Version: 5.0.0.dev1
+Version: 5.0.0.dev2
 Summary: omni:us python logging package
 Author-email: Mauricio Villegas <mauricio@omnius.com>
 License-Expression: MIT
@@ -75,7 +75,8 @@ The package contains essentially the following things:
 - A default logging configuration.
 - A function for loading logging configuration for regular python code.
 - A function for loading logging configuration for flask-based microservices.
-- Root logger configuration via ``LOGGER_ROOT_HANDLER`` so third-party library logs are also captured.
+- Root logger configuration via ``LOGGER_ROOT_HANDLER`` with independent ``LOGGER_ROOT_LEVEL`` control.
+- Singleton logger setup (``logger_setup``); call ``reset_configs`` before reconfiguring.
 - Automatic correlation ID management in Flask services via ``flask_app_logger_setup``.
 - An inheritable class to add a logger property.
 - A context manager to set and get the correlation id.

{reconplogger-5.0.0.dev1 → reconplogger-5.0.0.dev2}/README.rst

@@ -22,7 +22,8 @@ The package contains essentially the following things:
 - A default logging configuration.
 - A function for loading logging configuration for regular python code.
 - A function for loading logging configuration for flask-based microservices.
-- Root logger configuration via ``LOGGER_ROOT_HANDLER`` so third-party library logs are also captured.
+- Root logger configuration via ``LOGGER_ROOT_HANDLER`` with independent ``LOGGER_ROOT_LEVEL`` control.
+- Singleton logger setup (``logger_setup``); call ``reset_configs`` before reconfiguring.
 - Automatic correlation ID management in Flask services via ``flask_app_logger_setup``.
 - An inheritable class to add a logger property.
 - A context manager to set and get the correlation id.

{reconplogger-5.0.0.dev1 → reconplogger-5.0.0.dev2/reconplogger.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: reconplogger
-Version: 5.0.0.dev1
+Version: 5.0.0.dev2
 Summary: omni:us python logging package
 Author-email: Mauricio Villegas <mauricio@omnius.com>
 License-Expression: MIT
@@ -75,7 +75,8 @@ The package contains essentially the following things:
 - A default logging configuration.
 - A function for loading logging configuration for regular python code.
 - A function for loading logging configuration for flask-based microservices.
-- Root logger configuration via ``LOGGER_ROOT_HANDLER`` so third-party library logs are also captured.
+- Root logger configuration via ``LOGGER_ROOT_HANDLER`` with independent ``LOGGER_ROOT_LEVEL`` control.
+- Singleton logger setup (``logger_setup``); call ``reset_configs`` before reconfiguring.
 - Automatic correlation ID management in Flask services via ``flask_app_logger_setup``.
 - An inheritable class to add a logger property.
 - A context manager to set and get the correlation id.

{reconplogger-5.0.0.dev1 → reconplogger-5.0.0.dev2}/reconplogger.py

@@ -11,7 +11,7 @@ from typing import Optional, Union
 import pythonjsonlogger
 import yaml
 
-__version__ = "5.0.0.dev1"
+__version__ = "5.0.0.dev2"
 
 __all__ = [
     "RLoggerProperty",
@@ -118,6 +118,12 @@ configs_loaded = set()
 # Internal state for singleton primary logger
 _primary_logger: Optional[logging.Logger] = None
 
+ENV_CFG = "LOGGER_CFG"
+ENV_NAME = "LOGGER_NAME"
+ENV_LEVEL = "LOGGER_LEVEL"
+ENV_ROOT_HANDLER = "LOGGER_ROOT_HANDLER"
+ENV_ROOT_LEVEL = "LOGGER_ROOT_LEVEL"
+
 
 def reset_configs():
     """Resets reconplogger's internal configuration state.
@@ -130,7 +136,7 @@ def reset_configs():
     _primary_logger = None
 
 
-def load_config(cfg: Optional[Union[str, dict]] = None, reload: bool = False):
+def load_config(cfg: Optional[Union[str, dict]] = None):
     """Loads a logging configuration from path or environment variable or dictionary object.
 
     Args:
@@ -140,14 +146,14 @@ def load_config(cfg: Optional[Union[str, dict]] = None, reload: bool = False):
     Returns:
         The logging package object.
     """
-    if (
-        cfg is None
-        or cfg in {"", "reconplogger_default_cfg"}
-        or (cfg in os.environ and os.environ[cfg] == "reconplogger_default_cfg")
-    ):
+    if cfg is None:
         cfg_dict = reconplogger_default_cfg
     elif isinstance(cfg, dict):
         cfg_dict = cfg
+    elif cfg in {"", "reconplogger_default_cfg"} or (
+        cfg in os.environ and os.environ[cfg] == "reconplogger_default_cfg"
+    ):
+        cfg_dict = reconplogger_default_cfg
     elif isinstance(cfg, str):
         try:
             if os.path.isfile(cfg):
@@ -172,7 +178,7 @@ def load_config(cfg: Optional[Union[str, dict]] = None, reload: bool = False):
     cfg_dict["disable_existing_loggers"] = False
 
     cfg_hash = yaml.safe_dump(cfg_dict).__hash__()
-    if reload or cfg_hash not in configs_loaded:
+    if cfg_hash not in configs_loaded:
         logging.config.dictConfig(cfg_dict)
         configs_loaded.add(cfg_hash)
 
@@ -234,13 +240,6 @@ def add_file_handler(
     return file_handler
 
 
-def test_logger(logger: logging.Logger):
-    """Logs one message to each debug, info and warning levels intended for testing."""
-    logger.debug("reconplogger test debug message.")
-    logger.info("reconplogger test info message.")
-    logger.warning("reconplogger test warning message.")
-
-
 def get_logger(logger_name: str) -> logging.Logger:
     """Returns an already existing logger.
 
@@ -254,7 +253,7 @@ def get_logger(logger_name: str) -> logging.Logger:
         ValueError: If the logger does not exist.
     """
     if logger_name not in logging.Logger.manager.loggerDict and logger_name not in logging.root.manager.loggerDict:
-        raise ValueError('Logger "' + str(logger_name) + '" not defined.')
+        raise ValueError(f'Logger "{logger_name}" not defined.')
     return logging.getLogger(logger_name)
 
 
@@ -262,103 +261,82 @@ def logger_setup(
     logger_name: str = "plain_logger",
     config: Optional[str] = None,
     level: Optional[str] = None,
-    env_prefix: str = "LOGGER",
-    reload: bool = False,
-    init_messages: bool = False,
 ) -> logging.Logger:
     """Sets up logging configuration and returns the logger.
 
-    If the environment variable ``{env_prefix}_HANDLER`` is set to the name of a handler
+    If the environment variable ``LOGGER_ROOT_HANDLER`` is set to the name of a handler
     defined in the logging config, that handler is installed on the root logger so that
     all third-party loggers (which propagate to the root by default) are also captured.
+    The primary logger level remains controlled by ``level`` / ``LOGGER_LEVEL``, while the
+    root logger level can be controlled independently through ``LOGGER_ROOT_LEVEL``.
     On subsequent calls the same primary logger is returned without reconfiguring the root.
+    To force a fresh configuration pass, call :func:`reset_configs` first.
 
     Args:
         logger_name:  Name of the logger that needs to be used.
         config: Configuration string or path to configuration file or configuration file via environment variable.
         level: Optional logging level that overrides one in config.
-        env_prefix: Environment variable names prefix for overriding logger configuration.
-        reload: Whether to reload logging configuration overriding any previous settings.
-        init_messages: Whether to log init and test messages.
 
     Returns:
         The logger object.
     """
     global _primary_logger
 
-    if not isinstance(env_prefix, str) or not env_prefix:
-        raise ValueError("env_prefix is required to be a non-empty string.")
-    env_cfg = env_prefix + "_CFG"
-    env_name = env_prefix + "_NAME"
-    env_level = env_prefix + "_LEVEL"
-    env_root_handler = env_prefix + "_ROOT_HANDLER"
-
     # Return primary logger on subsequent calls (singleton behaviour)
-    if _primary_logger is not None and not reload:
-        name = os.getenv(env_name, logger_name)
-        if name != _primary_logger.name or config or level or init_messages:
+    if _primary_logger is not None:
+        name = os.getenv(ENV_NAME, logger_name)
+        if name != _primary_logger.name or config or level:
             _primary_logger.debug(
                 "logger_setup called again with different arguments; returning existing primary logger."
             )
         return _primary_logger
 
     # Configure logging
-    load_config(os.getenv(env_cfg, config), reload=reload)
+    load_config(os.getenv(ENV_CFG, config))
 
     # Get logger
-    name = os.getenv(env_name, logger_name)
+    name = os.getenv(ENV_NAME, logger_name)
     logger = get_logger(name)
 
-    # Resolve the effective log level
+    # Resolve the effective log level for the primary logger
     effective_level: Optional[int] = None
-    if env_level in os.environ:
-        level = os.getenv(env_level)
+    if ENV_LEVEL in os.environ:
+        level = os.getenv(ENV_LEVEL)
     if level:
-        if isinstance(level, str):
-            if level not in logging_levels:
-                raise ValueError('Invalid logging level: "' + str(level) + '".')
-            effective_level = logging_levels[level]
-        else:
-            raise ValueError("Expected level argument to be a string.")
-
-    # Configure root logger when LOGGER_ROOT_HANDLER env var is set
-    root_handler_name = os.getenv(env_root_handler)
-    if root_handler_name:
-        # _configure_root_logger installs the root handler and clears all named
-        # loggers' handlers so records flow through the single root handler.
-        _configure_root_logger(root_handler_name, effective_level)
-    else:
-        # Apply log level overrides to the named logger's handlers
-        if effective_level is not None:
-            for handler in logger.handlers:
-                if not isinstance(handler, logging.FileHandler):
-                    handler.setLevel(effective_level)
+        if level not in logging_levels:
+            raise ValueError('Invalid logging level: "' + str(level) + '".')
+        effective_level = logging_levels[level]
+
+    _configure_root_logger()
+
+    # Apply log level overrides to the named logger's handlers
+    if effective_level is not None:
+        for handler in logger.handlers:
+            if not isinstance(handler, logging.FileHandler):
+                handler.setLevel(effective_level)
 
     # Add correlation id filter
     logger.addFilter(_CorrelationIdLoggingFilter())
 
-    # Log configured done and test logger
-    if init_messages:
-        logger.info("reconplogger (v" + __version__ + ") logger configured.")
-        test_logger(logger)
-
     logger._reconplogger_setup = True
     _primary_logger = logger
     return logger
 
 
-def _configure_root_logger(handler_name: str, level: Optional[int]) -> None:
-    """Installs a named handler on the root logger and clears all named loggers.
+def _configure_root_logger() -> None:
+    """Installs a named handler on the root logger and removes stream handlers from named loggers.
 
     After this call every log record in the process flows through the single
     root handler, regardless of which named logger emitted it.  All named
-    loggers (except ``null_logger``) have their handlers removed and
-    ``propagate`` set to ``True`` so records bubble up to the root.
-
-    Args:
-        handler_name: Name of the handler as defined in the logging config (e.g. ``json_handler``).
-        level: Optional numeric log level; falls back to the handler's own level.
+    loggers (except those with only ``NullHandler`` instances) have their
+    ``StreamHandler`` instances removed and ``propagate`` set to ``True`` so
+    records bubble up to the root while keeping non-stream handlers such as
+    file handlers attached.
     """
+    handler_name = os.getenv(ENV_ROOT_HANDLER)
+    if not handler_name:
+        return
+
     # Retrieve the already-configured handler by name
     assert logging.root.manager.loggerDict  # just to verify config is loaded
     handler_obj = logging._handlers.get(handler_name)  # type: ignore[attr-defined]
@@ -370,15 +348,28 @@ def _configure_root_logger(handler_name: str, level: Optional[int]) -> None:
 
     root = logging.getLogger()
     root.handlers = [handler_obj]
-    effective_level = level if level is not None else handler_obj.level
-    root.setLevel(effective_level)
+    root_level_name = os.getenv(ENV_ROOT_LEVEL)
+    level = handler_obj.level
+    if root_level_name:
+        if root_level_name not in logging_levels:
+            raise ValueError('Invalid logging level: "' + str(root_level_name) + '".')
+        level = logging_levels[root_level_name]
+    handler_obj.setLevel(level)
+    root.setLevel(level)
 
     logging.captureWarnings(True)
 
-    # Clear handlers from all named loggers so nothing duplicates the root output.
+    # Remove stream handlers from named loggers so their remaining handlers, such
+    # as FileHandler, keep working without duplicating root stream output.
     for lg_obj in logging.Logger.manager.loggerDict.values():
-        if isinstance(lg_obj, logging.Logger) and lg_obj.name != "null_logger":
-            lg_obj.handlers = []
+        if isinstance(lg_obj, logging.Logger):
+            if any(isinstance(h, logging.NullHandler) for h in lg_obj.handlers):
+                continue
+            lg_obj.handlers = [
+                handler
+                for handler in lg_obj.handlers
+                if not isinstance(handler, logging.StreamHandler) or isinstance(handler, logging.FileHandler)
+            ]
             lg_obj.propagate = True
 
 
@@ -390,7 +381,6 @@ def flask_app_logger_setup(
     logger_name: str = "plain_logger",
     config: Optional[str] = None,
     level: Optional[str] = None,
-    env_prefix: str = "LOGGER",
 ) -> logging.Logger:
     """Sets up logging configuration, configures flask to use it, and returns the logger.
 
@@ -399,7 +389,6 @@ def flask_app_logger_setup(
         logger_name:  Name of the logger that needs to be used.
         config: Configuration string or path to configuration file or configuration file via environment variable.
         level: Optional logging level that overrides one in config.
-        env_prefix: Environment variable names prefix for overriding logger configuration.
 
     Returns:
         The logger object.
@@ -409,7 +398,6 @@ def flask_app_logger_setup(
         logger_name=logger_name,
         config=config,
         level=level,
-        env_prefix=env_prefix,
     )
 
     # Apply WSGI middleware to manage correlation ID at the transport layer

{reconplogger-5.0.0.dev1 → reconplogger-5.0.0.dev2}/reconplogger_tests.py

@@ -63,14 +63,14 @@ class TestReconplogger(unittest.TestCase):
 
     def test_log_level(self):
         """Test load config with the default config and plain logger changing the log level."""
-        logger = reconplogger.logger_setup(level="INFO", reload=True)
+        logger = reconplogger.logger_setup(level="INFO")
         self.assertEqual(logger.handlers[0].level, logging.INFO)
         reconplogger.reset_configs()
-        logger = reconplogger.logger_setup(level="ERROR", reload=True)
+        logger = reconplogger.logger_setup(level="ERROR")
         self.assertEqual(logger.handlers[0].level, logging.ERROR)
         reconplogger.reset_configs()
         with patch.dict(os.environ, {"LOGGER_LEVEL": "WARNING"}):
-            logger = reconplogger.logger_setup(level="INFO", env_prefix="LOGGER", reload=True)
+            logger = reconplogger.logger_setup(level="INFO")
             self.assertEqual(logger.handlers[0].level, logging.WARNING)
 
     def test_default_logger_with_exception(self):
@@ -125,18 +125,20 @@ class TestReconplogger(unittest.TestCase):
         self.assertRaises(ValueError, lambda: reconplogger.replace_logger_handlers(logger, False))
         self.assertRaises(ValueError, lambda: reconplogger.replace_logger_handlers(False, False))
 
-    def test_init_messages(self):
+    def test_logger_writes_messages(self):
         logger = reconplogger.logger_setup()
         with capture_logs(logger) as captured:
-            reconplogger.test_logger(logger)
+            logger.debug("reconplogger test debug message.")
+            logger.info("reconplogger test info message.")
+            logger.warning("reconplogger test warning message.")
         self.assertIn("WARNING", captured.getvalue())
         self.assertIn("reconplogger test warning message", captured.getvalue())
 
     @patch.dict(
         os.environ,
         {
-            "RECONPLOGGER_NAME": "example_logger",
-            "RECONPLOGGER_CFG": """{
+            "LOGGER_NAME": "example_logger",
+            "LOGGER_CFG": """{
             "version": 1,
             "formatters": {
                 "verbose": {
@@ -159,28 +161,25 @@ class TestReconplogger(unittest.TestCase):
         }""",
         },
     )
-    def test_logger_setup_env_prefix(self):
-        logger = reconplogger.logger_setup(env_prefix="RECONPLOGGER")
+    def test_logger_setup_env_vars(self):
+        logger = reconplogger.logger_setup()
         info_msg = "info message env logger"
         with LogCapture(names="example_logger") as log:
             logger.info(info_msg)
             log.check(("example_logger", "INFO", info_msg))
 
-    def test_logger_setup_env_prefix_invalid(self):
-        for env_prefix in [None, ""]:
-            with self.subTest(env_prefix):
-                with self.assertRaises(ValueError):
-                    reconplogger.logger_setup(env_prefix=env_prefix)
-
     def test_undefined_logger(self):
         """Test setting up a logger not already defined."""
         self.assertRaises(ValueError, lambda: reconplogger.logger_setup("undefined_logger"))
 
     def test_logger_setup_invalid_level(self):
         with self.assertRaises(ValueError):
-            reconplogger.logger_setup(level="INVALID", reload=True)
+            reconplogger.logger_setup(level="INVALID")
         with self.assertRaises(ValueError):
-            reconplogger.logger_setup(level=True, reload=True)
+            reconplogger.logger_setup(level=True)
+        with patch.dict(os.environ, {"LOGGER_ROOT_HANDLER": "json_handler", "LOGGER_ROOT_LEVEL": "INVALID"}):
+            with self.assertRaises(ValueError):
+                reconplogger.logger_setup()
 
     @patch.dict(os.environ, {"LOGGER_NAME": "json_logger"})
     def test_correlation_id_context(self):
@@ -203,13 +202,13 @@ class TestReconplogger(unittest.TestCase):
     @patch.dict(
         os.environ,
         {
-            "RECONPLOGGER_CFG": "reconplogger_default_cfg",
-            "RECONPLOGGER_NAME": "json_logger",
+            "LOGGER_CFG": "reconplogger_default_cfg",
+            "LOGGER_NAME": "json_logger",
         },
     )
     def test_flask_app_logger_setup(self):
         app = Flask(__name__)
-        reconplogger.flask_app_logger_setup(env_prefix="RECONPLOGGER", flask_app=app)
+        reconplogger.flask_app_logger_setup(flask_app=app)
         assert app.logger.filters  # pylint: disable=no-member
         assert app.before_request_funcs
         assert app.after_request_funcs
@@ -227,8 +226,8 @@ class TestReconplogger(unittest.TestCase):
     @patch.dict(
         os.environ,
         {
-            "RECONPLOGGER_CFG": "reconplogger_default_cfg",
-            "RECONPLOGGER_NAME": "json_logger",
+            "LOGGER_CFG": "reconplogger_default_cfg",
+            "LOGGER_NAME": "json_logger",
         },
     )
     def test_flask_app_correlation_id(self):
@@ -251,7 +250,7 @@ class TestReconplogger(unittest.TestCase):
             logs.check((app.logger.name, "ERROR"))
         self.assertEqual(response.status_code, 500)
 
-        reconplogger.flask_app_logger_setup(env_prefix="RECONPLOGGER", flask_app=app)
+        reconplogger.flask_app_logger_setup(flask_app=app)
         client = app.test_client()
 
         self.assertRaises(RuntimeError, lambda: reconplogger.get_correlation_id())
@@ -372,7 +371,8 @@ class TestReconplogger(unittest.TestCase):
         self.assertTrue(any([debug_msg in line for line in open(log_file).readlines()]))
 
         log_file = os.path.join(tmpdir, "file2.log")
-        logger = reconplogger.logger_setup(logger_name="plain_logger", level="DEBUG", reload=True)
+        reconplogger.reset_configs()
+        logger = reconplogger.logger_setup(logger_name="plain_logger", level="DEBUG")
         reconplogger.add_file_handler(logger, file_path=log_file, level="ERROR")
         self.assertEqual(logger.handlers[0].level, logging.DEBUG)
         self.assertEqual(logger.handlers[1].level, logging.ERROR)
@@ -435,17 +435,89 @@ class TestReconplogger(unittest.TestCase):
     )
     def test_root_logger_handler(self):
         """When LOGGER_ROOT_HANDLER is set, the root logger receives the handler and
-        named loggers propagate to it without handlers of their own."""
+        LOGGER_LEVEL no longer changes the root logger level."""
         logger = reconplogger.logger_setup()
         root = logging.getLogger()
         # Root logger should have the json_handler installed
         handler_names = [h.__class__.__name__ for h in root.handlers]
         self.assertIn("StreamHandler", handler_names)
-        self.assertEqual(root.level, logging.INFO)
-        # Named logger should have no own handlers; records bubble up to root
+        self.assertEqual(root.level, logging.WARNING)
+        self.assertEqual(root.handlers[0].level, logging.WARNING)
+        # Named logger should have no own stream handlers; records bubble up to root
         self.assertEqual(logger.handlers, [])
         self.assertTrue(logger.propagate)
 
+    @patch.dict(
+        os.environ,
+        {
+            "LOGGER_ROOT_HANDLER": "json_handler",
+            "LOGGER_ROOT_LEVEL": "DEBUG",
+        },
+    )
+    def test_root_logger_level_emits_debug_logs(self):
+        """LOGGER_ROOT_LEVEL controls the root logger and root handler thresholds."""
+        logger = reconplogger.logger_setup()
+        root = logging.getLogger()
+        self.assertEqual(root.level, logging.DEBUG)
+        self.assertEqual(root.handlers[0].level, logging.DEBUG)
+
+        captured = StringIO()
+        with patch.object(root.handlers[0], "stream", captured):
+            logger.debug("debug message via root handler")
+
+        self.assertIn("debug message via root handler", captured.getvalue())
+
+    def test_root_logger_keeps_file_handlers(self):
+        """Root logger setup removes stream handlers from named loggers but keeps file handlers."""
+        tmpdir = tempfile.mkdtemp(prefix="_reconplogger_root_test_")
+        log_file = os.path.join(tmpdir, "root.log")
+        config = {
+            "version": 1,
+            "formatters": {
+                "plain": {
+                    "format": "%(levelname)s %(message)s",
+                }
+            },
+            "handlers": {
+                "plain_handler": {
+                    "class": "logging.StreamHandler",
+                    "formatter": "plain",
+                    "level": "WARNING",
+                },
+                "file_handler": {
+                    "class": "logging.FileHandler",
+                    "formatter": "plain",
+                    "filename": log_file,
+                    "level": "ERROR",
+                },
+            },
+            "loggers": {
+                "plain_logger": {
+                    "level": "DEBUG",
+                    "handlers": ["plain_handler", "file_handler"],
+                }
+            },
+        }
+
+        try:
+            with patch.dict(os.environ, {"LOGGER_ROOT_HANDLER": "plain_handler"}, clear=False):
+                logger = reconplogger.logger_setup(config=config)
+
+            self.assertEqual(len(logger.handlers), 1)
+            self.assertIsInstance(logger.handlers[0], logging.FileHandler)
+            self.assertTrue(logger.propagate)
+
+            captured = StringIO()
+            root = logging.getLogger()
+            with patch.object(root.handlers[0], "stream", captured):
+                logger.error("root logger keeps file handlers")
+
+            logger.handlers[0].close()
+            self.assertIn("root logger keeps file handlers", captured.getvalue())
+            self.assertTrue(any("root logger keeps file handlers" in line for line in open(log_file).readlines()))
+        finally:
+            shutil.rmtree(tmpdir)
+
     @patch.dict(
         os.environ,
         {"LOGGER_ROOT_HANDLER": "nonexistent_handler"},