Refactor Pipeline into private submodule and improve documentation

docs/api/pipeline.rst

@@ -42,3 +42,12 @@ Standard Pipelines
 
     ~lenskit.pipeline.RecPipelineBuilder
     ~lenskit.pipeline.topn_pipeline
+
+Serialized Configurations
+-------------------------
+
+.. autosummary::
+    :toctree: .
+    :nosignatures:
+
+    ~lenskit.pipeline.PipelineConfig

lenskit/lenskit/diagnostics.py

@@ -23,3 +23,29 @@ class ConfigWarning(UserWarning):
     """
 
     pass
+
+
+class PipelineError(Exception):
+    """
+    Pipeline configuration errors.
+
+    .. note::
+
+        This exception is only to note problems with the pipeline configuration
+        and structure (e.g. circular dependencies).  Errors *running* the
+        pipeline are raised as-is.
+    """
+
+
+class PipelineWarning(Warning):
+    """
+    Pipeline configuration and setup warnings.  We also emit warnings to the
+    logger in many cases, but this allows critical ones to be visible even if
+    the client code has not enabled logging.
+
+    .. note::
+
+        This warning is only to note problems with the pipeline configuration
+        and structure (e.g. circular dependencies).  Errors *running* the
+        pipeline are raised as-is.
+    """

lenskit/lenskit/logging/_proxy.py

@@ -1,4 +1,5 @@
 import logging
+import re
 from typing import Any
 
 import structlog
@@ -7,13 +8,30 @@
 _fallback_wrapper = structlog.make_filtering_bound_logger(logging.WARNING)
 
 
-def get_logger(name: str) -> structlog.stdlib.BoundLogger:
+def get_logger(name: str, *, remove_private: bool = True) -> structlog.stdlib.BoundLogger:
     """
     Get a logger.  This works like :func:`structlog.stdlib.get_logger`, except
     the returned proxy logger is quiet (only WARN and higher messages) if
     structlog has not been configured. LensKit code should use this instead of
     obtaining loggers from Structlog directly.
+
+    It also suppresses private module name components of the logger name, so
+    e.g. ``lenskit.pipeline._impl`` becomes ``lenskit.pipeline`.
+
+    Params:
+        name:
+            The logger name.
+        remove_private:
+            Set to ``False`` to keep private module components of the logger
+            name instead of removing them.
+    Returns:
+        A lazy proxy logger.  The returned logger is type-compatible with
+        :class:`structlib.stdlib.BoundLogger`, but is actually an instance of an
+        internal proxy that provies more sensible defaults and handles LensKit's
+        TRACE-level logging support.
     """
+    if remove_private:
+        name = re.sub(r"\._.*", "", name)
     return LenskitProxyLogger(None, logger_factory_args=[name])  # type: ignore