Add better docstrings

Author: emmuhamm

src/daqpytools/logging/filters.py

@@ -267,7 +267,23 @@ def _build_throttle_filter(
     time_limit: int = 30,
     **extras: object,
 ) -> logging.Filter:
-    """Build a throttle filter from extras."""
+    """Build a throttle filter.
+
+    Args:
+        fallback_handlers: Handler types used as fallback routing context.
+        initial_treshold: Number of first occurrences to emit before applying
+            suppression logic.
+        time_limit: Throttle time window in seconds.
+        **extras: Additional forwarded keyword arguments. Ignored by this
+            factory.
+
+    Returns:
+        A configured ``ThrottleFilter`` instance.
+
+    Notes:
+        The keyword name is currently ``initial_treshold`` to match the
+        existing function signature.
+    """
     del extras
     return ThrottleFilter(
         fallback_handlers=fallback_handlers,
@@ -287,7 +303,15 @@ def _build_throttle_filter(
 }
 
 def get_filter_spec(handler_types: HandlerType) -> FilterSpec | None:
-    """Return the filter specification for a handler type."""
+    """Return the filter specification for a handler type.
+
+    Args:
+        handler_types: Filter-capable ``HandlerType`` alias.
+
+    Returns:
+        The matching ``FilterSpec`` if present in ``FILTER_SPEC_REGISTRY``;
+        otherwise ``None``.
+    """
     return FILTER_SPEC_REGISTRY.get(handler_types)
 
 def add_filter(
@@ -296,7 +320,20 @@ def add_filter(
     fallback_handlers : set[HandlerType]| None,
     **extras: object,
 ) -> None:
-    """Add a logger filter according to the spec."""
+    """Add a logger filter resolved from ``FILTER_SPEC_REGISTRY``.
+
+    Args:
+        log: Logger receiving the filter instance.
+        handler_type: Filter-capable ``HandlerType`` to resolve.
+        fallback_handlers: Explicit fallback handler set passed to the filter
+            factory. If ``None``, the filter spec ``fallback_types`` are used.
+        **extras: Additional keyword arguments forwarded to the resolved filter
+            factory. These values typically come from
+            ``get_daq_logger(..., **extras)``.
+
+    Returns:
+        None.
+    """
     spec = get_filter_spec(handler_type)
 
     effective_fallback_handlers = (
@@ -315,7 +352,19 @@ def add_throttle_filter(
     log: logging.Logger,
     fallback_handlers: set[HandlerType] | None = None,
 ) -> None:
-    """Add the Throttle filter to the logger."""
+    """Add the throttle filter to a logger.
+
+    This is a convenience wrapper over ``add_filter`` for
+    ``HandlerType.Throttle``.
+
+    Args:
+        log: Logger receiving the throttle filter.
+        fallback_handlers: Optional fallback handler set used by throttle
+            routing. If omitted, registry defaults are used.
+
+    Returns:
+        None.
+    """
     add_filter(
         log,
         HandlerType.Throttle,

src/daqpytools/logging/handlers.py

@@ -148,7 +148,19 @@ def logger_or_ancestors_have_handler(
 #### Handlers #### 
 
 def _build_rich_handler(width: int | None = None, **_: object) -> logging.Handler:
-    """Building the rich handler with any extras."""
+    """Build the rich console handler.
+
+    This factory is invoked from handler resolution in ``get_daq_logger`` and
+    receives forwarded ``**extras``.
+
+    Args:
+        width: Optional console width used by ``FormattedRichHandler``.
+            If ``None``, terminal width is auto-detected via ``get_width``.
+        **_: Additional forwarded keyword arguments. Ignored by this factory.
+
+    Returns:
+        The configured rich logging handler.
+    """
     real_width = width if width is not None else get_width()
     return FormattedRichHandler(width=real_width)
 
@@ -160,6 +172,14 @@ def _build_rich_handler(width: int | None = None, **_: object) -> logging.Handle
 )
 
 def _build_stdout_handler(**_: object) -> logging.Handler:
+    """Build a stdout stream handler.
+
+    Args:
+        **_: Additional forwarded keyword arguments. Ignored by this factory.
+
+    Returns:
+        A ``logging.StreamHandler`` writing to ``sys.stdout``.
+    """
     handler = logging.StreamHandler(sys.stdout)
     handler.setFormatter(LoggingFormatter())
     return handler
@@ -173,6 +193,15 @@ def _build_stdout_handler(**_: object) -> logging.Handler:
 )
 
 def _build_stderr_handler(**_: object) -> logging.Handler:
+    """Build a stderr stream handler.
+
+    Args:
+        **_: Additional forwarded keyword arguments. Ignored by this factory.
+
+    Returns:
+        A ``logging.StreamHandler`` writing to ``sys.stderr`` with
+        ``ERROR`` level.
+    """
     handler = logging.StreamHandler(sys.stderr)
     handler.setFormatter(LoggingFormatter())
     handler.setLevel(logging.ERROR)
@@ -187,6 +216,19 @@ def _build_stderr_handler(**_: object) -> logging.Handler:
 )
 
 def _build_file_handler(path: str | None = None, **_: object) -> logging.Handler:
+    """Build a file handler.
+
+    Args:
+        path: Path to the output log file. This is typically forwarded from
+            ``get_daq_logger(..., file_handler_path=...)`` as ``path``.
+        **_: Additional forwarded keyword arguments. Ignored by this factory.
+
+    Returns:
+        A configured ``logging.FileHandler``.
+
+    Raises:
+        ValueError: If ``path`` is not provided.
+    """
     if not path:
         err_msg = "path is required for file handler"
         raise ValueError(err_msg)
@@ -208,6 +250,21 @@ def _build_erskafka_handler(
         address : str = "monkafka.cern.ch:30092",
         ers_app_name : str | None = None,
     **_: object) -> logging.Handler: 
+    """Build an ERS Kafka handler.
+
+    Args:
+        session_name: ERS session name used by the Kafka handler.
+        topic: Kafka topic for ERS log messages.
+        address: Kafka broker address in ``host:port`` format.
+        ers_app_name: Optional ERS application name associated with messages.
+        **_: Additional forwarded keyword arguments. Ignored by this factory.
+
+    Returns:
+        A configured ``ERSKafkaLogHandler`` instance.
+
+    Raises:
+        ERSInitError: If the handler cannot be initialized.
+    """
 
     try:
         return ERSKafkaLogHandler(

src/daqpytools/logging/logger.py

@@ -71,28 +71,44 @@ def get_daq_logger(
     throttle: bool = False,
     **extras: object
 ) -> logging.Logger:
-    """C'tor for the default logging instances.
+    """Create or reuse a configured DAQ logger.
+
+    Handler/filter installation is driven by selected flags and resolved through
+    the handler/filter registries. Additional keyword arguments are forwarded to
+    the underlying factory functions.
 
     Args:
-        logger_name (str): Name of the logger.
-        log_level (int | str): Log level for the logger.
-        use_parent_handlers (bool): Whether to use parent handlers.
-        rich_handler (bool): Whether to add a rich handler.
-        file_handler_path (str | None): Path to the file handler log file. If None, no
-            file handler is added.
-        stream_handlers (bool): Whether to add both stdout and stderr stream handlers.
-        ers_kafka_session (str | None): ERS session name used to add an ERS
-            protobuf handler. If None, no ERS protobuf handler is added.
-        throttle (bool): Whether to add the throttle filter or not. Note, does not mean
-            outputs are filtered by default! See ThrottleFilter for details.
-        **extras (object): Extra keyword arguments forwarded to handler builders.
+        logger_name: Name of the logger to create or retrieve.
+        log_level: Logging level for the logger and its non-stderr handlers.
+        use_parent_handlers: If ``True``, logger propagation remains enabled.
+        rich_handler: Enable ``HandlerType.Rich``.
+        file_handler_path: Optional file path enabling ``HandlerType.File``.
+        stream_handlers: Enable ``HandlerType.Stream`` (stdout + stderr specs).
+        ers_kafka_session: Optional ERS session enabling
+            ``HandlerType.Protobufstream``.
+        throttle: Enable ``HandlerType.Throttle`` filter installation.
+        **extras: Additional keyword arguments forwarded to handler/filter
+            factories via ``add_handlers_from_types(..., **extras)``.
+
+            Common forwarded kwargs include:
+            - ``width`` -> ``_build_rich_handler``
+            - ``path`` -> ``_build_file_handler`` (internally mapped from
+              ``file_handler_path``)
+            - ``session_name`` -> ``_build_erskafka_handler`` (internally mapped
+              from ``ers_kafka_session``)
+            - ``topic``, ``address``, ``ers_app_name`` ->
+              ``_build_erskafka_handler``
+            - ``initial_treshold``, ``time_limit`` ->
+              ``_build_throttle_filter``
+
+            Unsupported kwargs may be ignored by factories that accept ``**_``.
 
     Returns:
-        logging.Logger: Configured logger instance.
+        Configured ``logging.Logger`` instance.
 
     Raises:
-        LoggerSetupError: If the configuration is invalid.
-
+        LoggerSetupError: If a logger with the same name already exists but
+            with a conflicting handler configuration.
     """
     rich_traceback_install(show_locals=True, width=get_width())