feat(porting): add state porting when replacing loggers

- Add port_state parameter to getLogger/getLoggerOfType
- Implement handler and level porting functionality
- Add registry support for porting operations
- Add comprehensive tests for porting scenarios
- Update API documentation

Author: InertSloth

ROADMAP.md

@@ -23,12 +23,14 @@ Some of these we just want to consider, and may not want to implement.
 
 ## 🔌 API
 - Evaluate `_applyPropagateSetting()` and its relationship with `__init__`: Currently, `Logger.__init__()` sets `_propagate_set = False` when `propagate=None`, indicating that `_applyPropagateSetting()` will set it later. This creates a two-phase initialization where propagate can be set either in `__init__` or later via `_applyPropagateSetting()`. Evaluate whether this split responsibility is clear and maintainable, or if propagate should always be set in `__init__` with the registry/default value passed directly. Consider the complexity of tracking `_propagate_set` flag and whether there are edge cases where the propagate value might be inconsistent or set at unexpected times.
-- **Root logger replacement: porting handlers and level:** When `extendLoggingModule()` replaces the root logger with an apathetic logger, we currently preserve the old root logger's level, handlers, propagate, and disabled state. Evaluate whether this behavior should be configurable:
-  - Should we port handlers by default, or should the new apathetic root logger start fresh with its own handlers (via `manageHandlers()`)?
-  - Should we port the level by default, or should the new root logger use a default level (NOTSET/INHERIT)?
-  - If we make this configurable, do we need keyword arguments to `extendLoggingModule()`, registry settings, or constants for these scenarios?
-  - Should users be able to specify they want handlers/level ported, or does porting them not make good sense at all (e.g., because apathetic loggers should manage their own handlers)?
-  - Consider edge cases: What if the old root logger has incompatible handlers? What if the level was set to a custom value that doesn't exist in apathetic logging?
+- **Root logger replacement: edge cases with custom logger classes:** Review and test situations where we replace the root logger, especially when the default logger class (set via `logging.setLoggerClass()`) is:
+  - Not a stdlib `logging.Logger` (e.g., a completely different class)
+  - A different subclass of `logging.Logger` (e.g., a third-party logger class)
+  - A subclass of our apathetic logger (e.g., `class MyLogger(apathetic_logging.Logger): pass`)
+  - Verify that our `isinstance(root_logger, cls)` check in `extendLoggingModule()` correctly identifies when replacement is needed
+  - Ensure state porting works correctly when replacing loggers of different types
+  - Test behavior when `replace_root=False` is set but the root logger is a different type
+  - Consider whether we should warn or error when replacing a logger that's a subclass of our apathetic logger (might indicate user wants to use their subclass)
 
 
 ## 📚 Documentation

docs/api.md

@@ -121,6 +121,8 @@
 registerLogLevelEnvVars = apathetic_logging.registerLogLevelEnvVars
 registerLogger = apathetic_logging.registerLogger
 registerCompatibilityMode = apathetic_logging.registerCompatibilityMode
+registerPortHandlers = apathetic_logging.registerPortHandlers
+registerPortLevel = apathetic_logging.registerPortLevel
 registerPropagate = apathetic_logging.registerPropagate
 registerReplaceRootLogger = apathetic_logging.registerReplaceRootLogger
 registerTargetPythonVersion = apathetic_logging.registerTargetPythonVersion
@@ -187,6 +189,8 @@
     "registerDefaultLogLevel",
     "registerLogLevelEnvVars",
     "registerLogger",
+    "registerPortHandlers",
+    "registerPortLevel",
     "registerPropagate",
     "registerReplaceRootLogger",
     "registerTargetPythonVersion",

src/apathetic_logging/__init__.py

@@ -152,3 +152,21 @@ class ANSIColors:
     When False, the root logger will not be replaced, allowing applications
     to use their own custom logger class for the root logger.
     """
+
+    DEFAULT_PORT_HANDLERS: bool = True
+    """Default value for whether to port handlers when replacing a logger.
+
+    When True (default), handlers from the old logger are ported to the new logger,
+    preserving existing configuration. When False, the new apathetic logger manages
+    its own handlers via manageHandlers() (may conflict with ported handlers).
+    """
+
+    DEFAULT_PORT_LEVEL: bool = True
+    """Default value for whether to port level when replacing a logger.
+
+    When True (default), the log level is ported from the old logger to the new
+    logger, preserving existing configuration. When False, the new logger uses
+    apathetic defaults (determineLogLevel() for root logger, INHERIT_LEVEL for
+    leaf loggers). Note: User-provided level parameters in getLogger/getLoggerOfType
+    take precedence over ported level.
+    """

src/apathetic_logging/constants.py

@@ -114,9 +114,21 @@ def _getOrCreateLoggerOfType(
             # Save the parent that was assigned
             old_parent = logger.parent
 
-            # Reconnect child loggers if we replaced an existing logger
+            # Port state from old logger if we replaced an existing logger
+            # (also reconnects child loggers internally)
             if old_logger is not None:
-                _logging_utils.reconnectChildLoggers(old_logger, logger)
+                # Port state from old logger, but user-provided kwargs take precedence
+                # Check if level is explicitly provided in kwargs - if so, don't port
+                # level (user's level will be applied later in getLoggerOfType)
+                user_provided_level = kwargs.get("level")
+                # Only port if user didn't provide level
+                port_level = user_provided_level is None
+                _logging_utils.portLoggerState(
+                    old_logger,
+                    logger,
+                    port_handlers=None,  # Use default (True) - port handlers
+                    port_level=port_level,  # Port level only if user didn't provide one
+                )
 
             # Fix parent if it points to old root logger
             # Only fix if this is not the root logger itself

src/apathetic_logging/get_logger.py

@@ -656,6 +656,8 @@ def extendLoggingModule(
         cls,
         *,
         replace_root: bool | None = None,
+        port_handlers: bool | None = None,
+        port_level: bool | None = None,
     ) -> bool:
         """The return value tells you if we ran or not.
         If it is False and you're calling it via super(),
@@ -668,6 +670,17 @@ def extendLoggingModule(
                 for backward compatibility. When False, the root logger will not be
                 replaced, allowing applications to use their own custom logger class
                 for the root logger.
+            port_handlers: Whether to port handlers from the old root logger to the
+                new logger. If None (default), checks the registry setting (set via
+                registerPortHandlers()). If not set in registry, defaults to True
+                (DEFAULT_PORT_HANDLERS from constants.py). When False, the new
+                logger manages its own handlers via manageHandlers().
+            port_level: Whether to port level from the old root logger to the new
+                logger. If None (default), checks the registry setting (set via
+                registerPortLevel()). If not set in registry, defaults to True
+                (DEFAULT_PORT_LEVEL from constants.py). When False, the new root
+                logger uses determineLogLevel() to get a sensible default. When
+                True, the old level is preserved.
 
         Note for tests:
             When testing isinstance checks on logger instances, use
@@ -727,12 +740,6 @@ def extendLoggingModule(
         # becomes wrong type later (e.g., in tests that create standard root logger)
         if replace_root and (not already_extended or not isinstance(root_logger, cls)):
             # Root logger is wrong type - need to replace it
-            # Save state from old root logger
-            old_level = root_logger.level
-            old_handlers = list(root_logger.handlers)  # Copy list
-            old_propagate = root_logger.propagate
-            old_disabled = root_logger.disabled
-
             # Remove old root logger from registry
             from .logging_utils import (  # noqa: PLC0415
                 ApatheticLogging_Internal_LoggingUtils,
@@ -776,17 +783,14 @@ def extendLoggingModule(
             if hasattr(logging, "root"):
                 logging.root = new_root_logger  # type: ignore[assignment]
 
-            # Restore state from old root logger
-            new_root_logger.setLevel(old_level)
-            new_root_logger.propagate = old_propagate
-            new_root_logger.disabled = old_disabled
-            # Restore handlers (they were attached to old logger, so we need to
-            # re-add them)
-            for handler in old_handlers:
-                new_root_logger.addHandler(handler)
-
-            # Reconnect child loggers to the new root logger
-            _logging_utils.reconnectChildLoggers(root_logger, new_root_logger)
+            # Port state from old root logger to new root logger
+            # (also reconnects child loggers internally)
+            _logging_utils.portLoggerState(
+                root_logger,
+                new_root_logger,
+                port_handlers=port_handlers,
+                port_level=port_level,
+            )
 
         # If already extended, skip the rest (level registration, etc.)
         if already_extended:

src/apathetic_logging/logger.py

@@ -325,6 +325,187 @@ def reconnectChildLoggers(
             if is_child and logger.parent is old_logger:
                 logger.parent = new_logger
 
+    @staticmethod
+    def _portPropagateAndDisabled(
+        old_logger: logging.Logger,
+        new_logger: logging.Logger,
+    ) -> None:
+        """Port propagate and disabled state from old logger to new logger."""
+        # Use setPropagate() if available to set the _propagate_set flag
+        # (prevents _applyPropagateSetting() from overriding ported value)
+        if hasattr(new_logger, "setPropagate"):
+            new_logger.setPropagate(old_logger.propagate)  # pyright: ignore[reportAttributeAccessIssue, reportUnknownMemberType]
+        else:
+            new_logger.propagate = old_logger.propagate
+        new_logger.disabled = old_logger.disabled
+
+    @staticmethod
+    def _portHandlers(
+        old_logger: logging.Logger,
+        new_logger: logging.Logger,
+    ) -> None:
+        """Port handlers from old logger to new logger."""
+        old_handlers = list(old_logger.handlers)  # Copy list
+        for handler in old_handlers:
+            new_logger.addHandler(handler)
+
+    @staticmethod
+    def _portLevel(
+        old_logger: logging.Logger,
+        new_logger: logging.Logger,
+        *,
+        constants: Any,
+    ) -> None:
+        """Port level from old logger to new logger."""
+        old_level = old_logger.level
+        # Validate level if it's an apathetic logger (has validateLevel)
+        if hasattr(new_logger, "validateLevel"):
+            try:
+                new_logger.validateLevel(old_level, allow_inherit=True)  # pyright: ignore[reportAttributeAccessIssue, reportUnknownMemberType]
+            except ValueError:
+                # Invalid level - fall back to apathetic default
+                return
+
+        # Use allow_inherit=True if level is INHERIT_LEVEL
+        if old_level == constants.INHERIT_LEVEL:
+            if hasattr(new_logger, "setLevel"):
+                sig = inspect.signature(new_logger.setLevel)
+                if "allow_inherit" in sig.parameters:
+                    new_logger.setLevel(old_level, allow_inherit=True)  # type: ignore[call-arg]
+                else:
+                    new_logger.setLevel(old_level)
+            else:
+                new_logger.level = old_level
+        else:
+            new_logger.setLevel(old_level)
+
+    @staticmethod
+    def _setApatheticDefaults(
+        new_logger: logging.Logger,
+        *,
+        constants: Any,
+    ) -> None:
+        """Set apathetic defaults for logger level."""
+        root_names = {constants.ROOT_LOGGER_KEY, constants.ROOT_LOGGER_NAME}
+        is_root = new_logger.name in root_names
+        if is_root:
+            # Root logger: use determineLogLevel() if available
+            if hasattr(new_logger, "determineLogLevel"):
+                level_name = new_logger.determineLogLevel()  # pyright: ignore[reportAttributeAccessIssue, reportUnknownMemberType, reportUnknownVariableType]
+                new_logger.setLevel(level_name)  # pyright: ignore[reportUnknownArgumentType]
+            else:
+                # Fallback: use INHERIT_LEVEL (though root has no parent)
+                new_logger.setLevel(constants.INHERIT_LEVEL, allow_inherit=True)  # type: ignore[call-arg]
+        # Leaf logger: use INHERIT_LEVEL to inherit from parent
+        elif hasattr(new_logger, "setLevel"):
+            sig = inspect.signature(new_logger.setLevel)
+            if "allow_inherit" in sig.parameters:
+                new_logger.setLevel(
+                    constants.INHERIT_LEVEL,
+                    allow_inherit=True,  # type: ignore[call-arg]
+                )
+            else:
+                new_logger.setLevel(constants.INHERIT_LEVEL)
+        else:
+            new_logger.level = constants.INHERIT_LEVEL
+
+    @staticmethod
+    def portLoggerState(
+        old_logger: logging.Logger,
+        new_logger: logging.Logger,
+        *,
+        port_handlers: bool | None = None,
+        port_level: bool | None = None,
+    ) -> None:
+        """Port state from old logger to new logger.
+
+        Ports propagate and disabled state always. Optionally ports handlers
+        and level based on parameters. When not porting level, uses apathetic
+        defaults: determineLogLevel() for root logger, INHERIT_LEVEL for leaf loggers.
+
+        After porting (or not porting) handlers, calls manageHandlers() if the new
+        logger supports it, to ensure apathetic handlers are set up appropriately
+        based on propagate setting. This ensures root logger always has a handler,
+        and child loggers with propagate=False get handlers as needed. manageHandlers()
+        only manages DualStreamHandler instances, so it won't interfere with ported
+        user handlers.
+
+        Finally, reconnects child loggers from the old logger to the new logger,
+        ensuring child loggers point to the new logger instance after replacement.
+
+        Args:
+            old_logger: The logger being replaced.
+            new_logger: The new logger to port state to.
+            port_handlers: Whether to port handlers. If None, checks registry setting
+                or defaults to True. When True, handlers from old logger are ported.
+                When False, new logger manages its own handlers via manageHandlers().
+                In both cases, manageHandlers() is called to ensure apathetic handlers
+                are set up if needed.
+            port_level: Whether to port level. If None, checks registry setting or
+                defaults to True. When True, level from old logger is ported.
+                When False, uses apathetic defaults (determineLogLevel() for root,
+                INHERIT_LEVEL for leaf loggers). Note: User-provided level parameters
+                in getLogger/getLoggerOfType take precedence over ported level.
+        """
+        from .constants import (  # noqa: PLC0415
+            ApatheticLogging_Internal_Constants,
+        )
+        from .registry_data import (  # noqa: PLC0415
+            ApatheticLogging_Internal_RegistryData,
+        )
+
+        _constants = ApatheticLogging_Internal_Constants
+        _registry_data = ApatheticLogging_Internal_RegistryData
+
+        # Always port propagate and disabled
+        ApatheticLogging_Internal_LoggingUtils._portPropagateAndDisabled(
+            old_logger, new_logger
+        )
+
+        # Resolve port_handlers parameter
+        if port_handlers is None:
+            port_handlers = (
+                _registry_data.registered_internal_port_handlers
+                if _registry_data.registered_internal_port_handlers is not None
+                else _constants.DEFAULT_PORT_HANDLERS
+            )
+
+        # Port handlers if requested
+        if port_handlers:
+            ApatheticLogging_Internal_LoggingUtils._portHandlers(old_logger, new_logger)
+
+        # After porting (or not porting) handlers, ensure apathetic handlers are set up
+        # if the logger supports manageHandlers(). This ensures root logger always has
+        # a handler, and child loggers with propagate=False get handlers as needed.
+        # manageHandlers() only manages DualStreamHandler instances, so it won't
+        # interfere with ported user handlers.
+        if hasattr(new_logger, "manageHandlers"):
+            new_logger.manageHandlers()  # pyright: ignore[reportAttributeAccessIssue, reportUnknownMemberType]
+
+        # Resolve port_level parameter
+        if port_level is None:
+            port_level = (
+                _registry_data.registered_internal_port_level
+                if _registry_data.registered_internal_port_level is not None
+                else _constants.DEFAULT_PORT_LEVEL
+            )
+
+        # Port level if requested, otherwise use apathetic defaults
+        if port_level:
+            ApatheticLogging_Internal_LoggingUtils._portLevel(
+                old_logger, new_logger, constants=_constants
+            )
+        else:
+            ApatheticLogging_Internal_LoggingUtils._setApatheticDefaults(
+                new_logger, constants=_constants
+            )
+
+        # Reconnect child loggers from old logger to new logger
+        # This ensures child loggers point to the new logger instance after replacement
+        ApatheticLogging_Internal_LoggingUtils.reconnectChildLoggers(
+            old_logger, new_logger
+        )
+
     @staticmethod
     def removeLogger(logger_name: str) -> None:
         """Remove a logger from the logging manager's registry.