Rename stuff in specs, add a bit of docs

Author: emmuhamm

src/daqpytools/logging/filters.py

@@ -272,9 +272,10 @@ def _build_throttle_filter(
     )
 
 THROTTLE_FILTER_SPEC = FilterSpec(
-    representative_type = HandlerType.Throttle,
-    filter_type = ThrottleFilter,
-    factory=_build_throttle_filter
+    alias = HandlerType.Throttle,
+    filter_class = ThrottleFilter,
+    factory=_build_throttle_filter,
+    fallback_types=(HandlerType.Throttle,),
 )
 
 FILTER_SPEC_REGISTRY: dict[HandlerType, FilterSpec] = {
@@ -294,7 +295,7 @@ def add_filter(
     spec = get_filter_spec(handler_type)
 
     logger_filter = spec.factory(
-        fallback_handlers if fallback_handlers is not None else spec.filter_handler_ids,
+        fallback_handlers if fallback_handlers is not None else set(spec.fallback_types),
         **extras
     )
     log.addFilter(logger_filter)

src/daqpytools/logging/handlers.py

@@ -7,10 +7,7 @@
 
 from erskafka.ERSKafkaLogHandler import ERSKafkaLogHandler
 
-from daqpytools.logging.exceptions import (
-    LoggerHandlerError,
-    ERSInitError
-)
+from daqpytools.logging.exceptions import ERSInitError, LoggerHandlerError
 from daqpytools.logging.filters import (
     HandleIDFilter,
     add_filter,
@@ -156,10 +153,10 @@ def _build_rich_handler(width: int | None = None, **_: Any) -> logging.Handler:
     return FormattedRichHandler(width=real_width)
 
 RICH_HANDLER_SPEC = HandlerSpec(
-    representative_type = HandlerType.Rich,
-    handler_type = FormattedRichHandler,
+    alias = HandlerType.Rich,
+    handler_class = FormattedRichHandler,
     factory=_build_rich_handler,
-    filter_handler_ids = (HandlerType.Rich,), # For HandleIDFilter
+    fallback_types = (HandlerType.Rich,), # For HandleIDFilter
 )
 
 def _build_stdout_handler(**_: Any) -> logging.Handler:
@@ -168,11 +165,11 @@ def _build_stdout_handler(**_: Any) -> logging.Handler:
     return handler
 
 STDOUT_HANDLER_SPEC = HandlerSpec(
-    representative_type = HandlerType.Lstdout,
-    handler_type = logging.StreamHandler,
+    alias = HandlerType.Lstdout,
+    handler_class = logging.StreamHandler,
     target_stream=cast(io.IOBase, sys.stdout),
     factory=_build_stdout_handler,
-    filter_handler_ids = (HandlerType.Stream, HandlerType.Lstdout),
+    fallback_types = (HandlerType.Stream, HandlerType.Lstdout),
 )
 
 def _build_stderr_handler(**_: Any) -> logging.Handler:
@@ -182,11 +179,11 @@ def _build_stderr_handler(**_: Any) -> logging.Handler:
     return handler
 
 STDERR_HANDLER_SPEC = HandlerSpec(
-    representative_type = HandlerType.Lstderr,
-    handler_type = logging.StreamHandler,
+    alias = HandlerType.Lstderr,
+    handler_class = logging.StreamHandler,
     target_stream=cast(io.IOBase, sys.stderr),
     factory=_build_stderr_handler,
-    filter_handler_ids = (HandlerType.Stream, HandlerType.Lstderr),
+    fallback_types = (HandlerType.Stream, HandlerType.Lstderr),
 )
 
 def _build_file_handler(path: str | None = None, **_: Any) -> logging.Handler:
@@ -199,10 +196,10 @@ def _build_file_handler(path: str | None = None, **_: Any) -> logging.Handler:
     return handler
 
 FILE_HANDLER_SPEC = HandlerSpec(
-    representative_type=HandlerType.File,
-    handler_type = logging.FileHandler,
+    alias=HandlerType.File,
+    handler_class = logging.FileHandler,
     factory = _build_file_handler,
-    filter_handler_ids=(HandlerType.File,)
+    fallback_types=(HandlerType.File,)
 )
 
 def _build_erskafka_handler(
@@ -224,10 +221,10 @@ def _build_erskafka_handler(
 
 
 ERSKAFKA_HANDLER_SPEC = HandlerSpec(
-    representative_type=HandlerType.Protobufstream,
-    handler_type = ERSKafkaLogHandler,
+    alias=HandlerType.Protobufstream,
+    handler_class = ERSKafkaLogHandler,
     factory = _build_erskafka_handler,
-    filter_handler_ids=[HandlerType.Protobufstream],
+    fallback_types=(HandlerType.Protobufstream,),
 )
 
 
@@ -260,7 +257,7 @@ def add_handler(
         if logger_or_ancestors_have_handler(
             log,
             use_parent_handlers,
-            spec.handler_type,
+            spec.handler_class,
             target_stream=spec.target_stream,
         ):
             continue
@@ -269,18 +266,18 @@ def add_handler(
         check_parent_handlers(
             log,
             use_parent_handlers,
-            spec.handler_type,
+            spec.handler_class,
             target_stream = spec.target_stream
         )
 
         handler = spec.factory(**extras)
-        effective_default_case = fallback_handler if fallback_handler is not None else spec.filter_handler_ids
+        effective_default_case = fallback_handler if fallback_handler is not None else spec.fallback_types
 
         handler_ids: HandlerType | list[HandlerType]
-        if len(spec.filter_handler_ids) == 1:
-            handler_ids = cast(HandlerType, spec.filter_handler_ids[0])
+        if len(spec.fallback_types) == 1:
+            handler_ids = cast(HandlerType, spec.fallback_types[0])
         else: 
-            handler_ids = [cast(HandlerType, handler_id) for handler_id in spec.filter_handler_ids] 
+            handler_ids = [cast(HandlerType, handler_id) for handler_id in spec.fallback_types] 
 
         handler.addFilter(
             HandleIDFilter(
@@ -323,5 +320,5 @@ def add_handlers_from_types(
             continue
 
         filter_spec = get_filter_spec(handler_type)
-        if filter_spec and not logger_has_filter(log, filter_spec.filter_type):
+        if filter_spec and not logger_has_filter(log, filter_spec.filter_class):
             add_filter(log, handler_type, fallback_handlers, **extras)

src/daqpytools/logging/specs.py

@@ -1,25 +1,51 @@
+"""Declarative specifications used to construct logging handlers and filters.
+
+This module defines immutable spec objects that describe:
+- how a handler or filter is built (`factory`),
+- how it is identified at runtime (`handler_class` / `filter_class`), and
+- which handler types should be used for fallback routing (`fallback_types`).
+"""
+
 import io
 import logging
 from collections.abc import Callable, Mapping
 from dataclasses import dataclass
 from typing import Any
 
-"""
- Declarative specification for building and identifying objects
-"""
-
 
 @dataclass(frozen=True)
 class HandlerSpec:
-    representative_type: Any
-    handler_type: type[logging.Handler]
+    """Specification for creating and identifying a logging handler.
+
+    Attributes:
+        alias: Canonical identifier for the spec (typically a `HandlerType`).
+        handler_class: Runtime logging class used to detect existing handlers.
+        factory: Callable that builds the handler instance from configuration extras.
+        fallback_types: Handler types this handler maps to for fallback behavior.
+        target_stream: Optional stream discriminator for stream-based handlers
+            (for example, stdout vs stderr).
+    """
+
+    alias: Any
+    handler_class: type[logging.Handler]
     factory: Callable[..., logging.Handler]
-    filter_handler_ids: tuple[Any, ...] # For HandleIDFilter
-    target_stream: io.IOBase| None = None
+    fallback_types: tuple[Any, ...]
+    target_stream: io.IOBase | None = None
 
 
 @dataclass(frozen=True)
 class FilterSpec:
-    representative_type: Any
-    filter_type: type[logging.Filter]
-    factory: Callable[[set[Any], Mapping[str, Any]], logging.Filter]
+    """Specification for creating and identifying a logging filter.
+
+    Attributes:
+        alias: Canonical identifier for the spec (typically a `HandlerType`).
+        filter_class: Runtime logging filter class used to detect existing filters.
+        factory: Callable that builds the filter from fallback handlers and extras.
+        fallback_types: Default handler types passed to the filter factory when
+            no explicit fallback set is provided by the caller.
+    """
+
+    alias: Any
+    filter_class: type[logging.Filter]
+    factory: Callable[[set[Any], Mapping[str, Any]], logging.Filter]
+    fallback_types: tuple[Any, ...] = tuple()