yapl-kit 0.2.0__tar.gz → 0.3.0__tar.gz

{yapl_kit-0.2.0 → yapl_kit-0.3.0}/PKG-INFO

@@ -1,14 +1,12 @@
 Metadata-Version: 2.3
 Name: yapl-kit
-Version: 0.2.0
+Version: 0.3.0
 Summary: YetAnotherPythonLogger - a minimal, extensible logging toolkit built on top of Python's standard logging module.
 Author: SirKaiMartin
+Requires-Dist: opentelemetry-api>=1.0 ; extra == 'opentelemetry'
 Requires-Dist: httpx>=0.28.1 ; extra == 'webhook'
 Requires-Python: >=3.13
-Provides-Extra: buffering
-Provides-Extra: coloring
-Provides-Extra: formatting
-Provides-Extra: queueing
+Provides-Extra: opentelemetry
 Provides-Extra: webhook
 Description-Content-Type: text/markdown
 
@@ -18,9 +16,11 @@ Description-Content-Type: text/markdown
 
 > A modern, minimal, and extensible logging toolkit built on top of Python's standard `logging` module.
 
-YAPL keeps the stdlib logging ecosystem intact while adding structured logging, queue-backed delivery, formatting, coloring, buffering, stack helpers, and optional webhook support.
+YAPL keeps the stdlib logging ecosystem intact while adding structured logging, queue-backed delivery, formatting, coloring, buffering, stack helpers, and webhook support.
 
-The core stays dependency-free. Optional integrations are installed only when you need them.
+All YAPL feature families ship in the single `yapl-kit` distribution. The base
+install uses only the standard library; optional integrations install their
+runtime dependencies through extras.
 
 ## Installation
 
@@ -38,17 +38,15 @@ With `pip`:
 pip install yapl-kit
 ```
 
-Install all optional features:
+Install webhook or OpenTelemetry integrations only when needed:
 
 ```bash
-uv add "yapl-kit[formatting,coloring,buffering,queueing,webhook]"
+pip install 'yapl-kit[webhook]'
+pip install 'yapl-kit[opentelemetry]'
 ```
 
-or:
-
-```bash
-pip install "yapl-kit[formatting,coloring,buffering,queueing,webhook]"
-```
+With `uv`, use `uv add 'yapl-kit[webhook]'` or
+`uv add 'yapl-kit[opentelemetry]'`.
 
 The canonical import namespace is `yapl`:
 
@@ -119,7 +117,7 @@ YAPL does not replace Python logging. It builds on stdlib handlers, formatters,
 
 The main design goals are:
 
-- keep the core small and dependency-free
+- keep the distribution small and focused
 - preserve compatibility with Python's logging ecosystem
 - keep expensive formatting and I/O off the application hot path
 - make queueing, retries, and shutdown behavior bounded
@@ -129,6 +127,7 @@ The main design goals are:
 ## Configuration
 
 YAPL supports direct setup arguments as well as typed configuration.
+Install `yapl-kit[webhook]` before configuring a webhook sink.
 
 ```python
 from yapl import WebhookConfig, YaplConfig, get_logger, setup_logging
@@ -152,6 +151,54 @@ log.info("Application started")
 
 Setup arguments override the supplied `YaplConfig` for that call without mutating the configuration object.
 
+### Filtering and custom levels
+
+Use suppression rules to drop matching records from every configured sink. All
+conditions in one rule must match; a record is dropped when any rule matches.
+Use an `OutputConfig` filter when a condition should apply to just that sink.
+Sink filters can be standard `logging.Filter` objects or callables that accept a
+`LogRecord` and return whether to keep it.
+
+```python
+import logging
+
+import yapl
+from yapl import OutputConfig, SuppressionRules, YaplConfig
+
+NOTICE_LEVEL = 25
+yapl.register_level("NOTICE", NOTICE_LEVEL)
+yapl.register_level_method("NOTICE")
+
+config = YaplConfig(
+    level=logging.DEBUG,
+    queue_enabled=False,
+    sinks=(
+        OutputConfig(
+            "stdout",
+            filters=(lambda record: record.levelno >= NOTICE_LEVEL,),
+        ),
+    ),
+    suppression=SuppressionRules().drop(
+        logger="myapp.noisy",
+        logger_prefix=True,
+    ),
+)
+
+try:
+    log = yapl.setup_logging(config)
+    log.notice("operator_notice")
+finally:
+    yapl.shutdown_logging()
+```
+
+Register a custom level before using it in configuration or logging calls. The
+optional `register_level_method` call adds a convenience method such as
+`log.notice`; without it, use the standard `log.log(NOTICE_LEVEL, ...)` method.
+The root logging level and each sink's filter are separate gates: this example
+keeps DEBUG enabled globally, then applies the NOTICE threshold only to the
+console sink. See [`development/demos/filters_and_levels.py`](development/demos/filters_and_levels.py)
+for a runnable example with both suppression rules and sink filtering.
+
 ## Output Profiles
 
 A single process can use different output profiles for different sinks.
@@ -186,6 +233,86 @@ log.info("payment_processed", request_id="req-42")
 
 Use `resource` for stable source metadata such as service, environment, region, or cluster. Keep request IDs, user IDs, trace IDs, and other high-cardinality values as normal structured fields. File output profiles also support bounded rotation with `file_max_bytes` and `file_backup_count`; those options are valid only for file sinks.
 
+### Trace correlation
+
+When an application uses OpenTelemetry, YAPL can copy the active span's IDs
+onto each record so structured outputs include `trace_id` and `span_id`:
+
+```python
+from yapl import YaplConfig, setup_logging, shutdown_logging
+
+setup_logging(YaplConfig(capture_trace_context=True))
+# Call this during application shutdown to drain queued output.
+shutdown_logging()
+```
+
+Install the `opentelemetry` extra, which supplies `opentelemetry-api`, and
+configure an OpenTelemetry SDK or instrumentation package to create active
+spans. YAPL reads the IDs while the log call runs, so they are retained when sink
+work is queued. Existing `trace_id` or `span_id` record fields take precedence.
+
+### Per-sink processing
+
+Each `OutputConfig` can add processing that applies only to that sink:
+
+```python
+import logging
+
+from yapl import OutputConfig, YaplConfig
+from yapl.extensions.formatting import AddServiceName, RedactSecrets
+
+
+class OnlyErrors(logging.Filter):
+    def filter(self, record: logging.LogRecord) -> bool:
+        return record.levelno >= logging.ERROR
+
+
+config = YaplConfig(
+    sinks=(
+        OutputConfig(
+            "stdout",
+            format="text",
+            processors=(AddServiceName("checkout-console"),),
+            enrichment={"audience": "operator"},
+            filters=(OnlyErrors(),),
+        ),
+        OutputConfig(
+            "file",
+            format="jsonl",
+            file_path="checkout.jsonl",
+            processors=(RedactSecrets(("password", "token")),),
+            fields=("timestamp", "level", "message", "context"),
+        ),
+    ),
+)
+```
+
+`filters` are standard record filters and `enrichment` adds context fields on
+an isolated copy of the record. `processors` transform the normalized event.
+`redact_secret_fields` and `redaction_replacement` provide a concise redaction
+policy, `schema` maps output names to dotted event paths, and `fields` retains
+top-level event fields. A sink with a stricter redaction policy cannot leak its
+unredacted record through another sink: each sink receives an isolated record
+and event copy.
+
+The deterministic order is: record filters, context enrichment, global
+processors, sink processors, redaction, schema projection, field selection,
+then formatting or webhook payload construction. Existing per-sink levels and
+formatters still run at their normal handler boundaries. Queue workers apply
+the same policy before each target handler, and webhook processing remains on
+the webhook worker.
+
+`RedactSecrets` remains available for custom processor pipelines. When using
+`redact_secret_fields`, set it to an empty tuple to explicitly disable the
+webhook's default redaction for that sink; omit it to retain the webhook
+configuration's default policy.
+
+For a standard-library custom formatter, set `OutputConfig.formatter`. YAPL
+applies that sink's processors and event policy to an isolated record before
+delegating to the formatter. The transformed normalized event is also
+available as `record.yapl_event`; without sink policies, the original formatter
+instance is used unchanged.
+
 ## Formatting
 
 Structured, text, JSON Lines, and logfmt output are available through the formatting extension.
@@ -225,12 +352,10 @@ Queue capacity limits the number of retained records, not their total byte size.
 
 ## Webhooks
 
-Webhook delivery is optional and uses `httpx`.
-
-Install it with:
+Webhook delivery requires the optional `webhook` extra, which installs `httpx`:
 
 ```bash
-uv add "yapl-kit[webhook]"
+pip install 'yapl-kit[webhook]'
 ```
 
 Configure a webhook:
@@ -339,9 +464,9 @@ Python cannot safely terminate arbitrary user handler code. Keep custom handlers
 
 `queue_enabled=False` runs normal stdlib handlers directly, so file, console, or custom sink work may occur on the caller thread.
 
-## Optional Modules
+## Extension Modules
 
-YAPL keeps concrete optional features under explicit modules:
+YAPL keeps feature families under explicit modules within the main distribution:
 
 ```python
 from yapl.stack import FunctionCallTracer, get_callsite
@@ -352,7 +477,7 @@ from yapl.extensions.queueing import QueueingConfig
 from yapl.extensions.webhook import WebhookConfig
 ```
 
-The `yapl.extensions` package is a namespace; concrete features live in its submodules.
+The `yapl.extensions` package contains the concrete feature implementations.
 
 ## Package Philosophy
 

{yapl_kit-0.2.0 → yapl_kit-0.3.0}/PUBLIC.md

@@ -4,9 +4,11 @@
 
 > A modern, minimal, and extensible logging toolkit built on top of Python's standard `logging` module.
 
-YAPL keeps the stdlib logging ecosystem intact while adding structured logging, queue-backed delivery, formatting, coloring, buffering, stack helpers, and optional webhook support.
+YAPL keeps the stdlib logging ecosystem intact while adding structured logging, queue-backed delivery, formatting, coloring, buffering, stack helpers, and webhook support.
 
-The core stays dependency-free. Optional integrations are installed only when you need them.
+All YAPL feature families ship in the single `yapl-kit` distribution. The base
+install uses only the standard library; optional integrations install their
+runtime dependencies through extras.
 
 ## Installation
 
@@ -24,17 +26,15 @@ With `pip`:
 pip install yapl-kit
 ```
 
-Install all optional features:
+Install webhook or OpenTelemetry integrations only when needed:
 
 ```bash
-uv add "yapl-kit[formatting,coloring,buffering,queueing,webhook]"
+pip install 'yapl-kit[webhook]'
+pip install 'yapl-kit[opentelemetry]'
 ```
 
-or:
-
-```bash
-pip install "yapl-kit[formatting,coloring,buffering,queueing,webhook]"
-```
+With `uv`, use `uv add 'yapl-kit[webhook]'` or
+`uv add 'yapl-kit[opentelemetry]'`.
 
 The canonical import namespace is `yapl`:
 
@@ -105,7 +105,7 @@ YAPL does not replace Python logging. It builds on stdlib handlers, formatters,
 
 The main design goals are:
 
-- keep the core small and dependency-free
+- keep the distribution small and focused
 - preserve compatibility with Python's logging ecosystem
 - keep expensive formatting and I/O off the application hot path
 - make queueing, retries, and shutdown behavior bounded
@@ -115,6 +115,7 @@ The main design goals are:
 ## Configuration
 
 YAPL supports direct setup arguments as well as typed configuration.
+Install `yapl-kit[webhook]` before configuring a webhook sink.
 
 ```python
 from yapl import WebhookConfig, YaplConfig, get_logger, setup_logging
@@ -138,6 +139,54 @@ log.info("Application started")
 
 Setup arguments override the supplied `YaplConfig` for that call without mutating the configuration object.
 
+### Filtering and custom levels
+
+Use suppression rules to drop matching records from every configured sink. All
+conditions in one rule must match; a record is dropped when any rule matches.
+Use an `OutputConfig` filter when a condition should apply to just that sink.
+Sink filters can be standard `logging.Filter` objects or callables that accept a
+`LogRecord` and return whether to keep it.
+
+```python
+import logging
+
+import yapl
+from yapl import OutputConfig, SuppressionRules, YaplConfig
+
+NOTICE_LEVEL = 25
+yapl.register_level("NOTICE", NOTICE_LEVEL)
+yapl.register_level_method("NOTICE")
+
+config = YaplConfig(
+    level=logging.DEBUG,
+    queue_enabled=False,
+    sinks=(
+        OutputConfig(
+            "stdout",
+            filters=(lambda record: record.levelno >= NOTICE_LEVEL,),
+        ),
+    ),
+    suppression=SuppressionRules().drop(
+        logger="myapp.noisy",
+        logger_prefix=True,
+    ),
+)
+
+try:
+    log = yapl.setup_logging(config)
+    log.notice("operator_notice")
+finally:
+    yapl.shutdown_logging()
+```
+
+Register a custom level before using it in configuration or logging calls. The
+optional `register_level_method` call adds a convenience method such as
+`log.notice`; without it, use the standard `log.log(NOTICE_LEVEL, ...)` method.
+The root logging level and each sink's filter are separate gates: this example
+keeps DEBUG enabled globally, then applies the NOTICE threshold only to the
+console sink. See [`development/demos/filters_and_levels.py`](development/demos/filters_and_levels.py)
+for a runnable example with both suppression rules and sink filtering.
+
 ## Output Profiles
 
 A single process can use different output profiles for different sinks.
@@ -172,6 +221,86 @@ log.info("payment_processed", request_id="req-42")
 
 Use `resource` for stable source metadata such as service, environment, region, or cluster. Keep request IDs, user IDs, trace IDs, and other high-cardinality values as normal structured fields. File output profiles also support bounded rotation with `file_max_bytes` and `file_backup_count`; those options are valid only for file sinks.
 
+### Trace correlation
+
+When an application uses OpenTelemetry, YAPL can copy the active span's IDs
+onto each record so structured outputs include `trace_id` and `span_id`:
+
+```python
+from yapl import YaplConfig, setup_logging, shutdown_logging
+
+setup_logging(YaplConfig(capture_trace_context=True))
+# Call this during application shutdown to drain queued output.
+shutdown_logging()
+```
+
+Install the `opentelemetry` extra, which supplies `opentelemetry-api`, and
+configure an OpenTelemetry SDK or instrumentation package to create active
+spans. YAPL reads the IDs while the log call runs, so they are retained when sink
+work is queued. Existing `trace_id` or `span_id` record fields take precedence.
+
+### Per-sink processing
+
+Each `OutputConfig` can add processing that applies only to that sink:
+
+```python
+import logging
+
+from yapl import OutputConfig, YaplConfig
+from yapl.extensions.formatting import AddServiceName, RedactSecrets
+
+
+class OnlyErrors(logging.Filter):
+    def filter(self, record: logging.LogRecord) -> bool:
+        return record.levelno >= logging.ERROR
+
+
+config = YaplConfig(
+    sinks=(
+        OutputConfig(
+            "stdout",
+            format="text",
+            processors=(AddServiceName("checkout-console"),),
+            enrichment={"audience": "operator"},
+            filters=(OnlyErrors(),),
+        ),
+        OutputConfig(
+            "file",
+            format="jsonl",
+            file_path="checkout.jsonl",
+            processors=(RedactSecrets(("password", "token")),),
+            fields=("timestamp", "level", "message", "context"),
+        ),
+    ),
+)
+```
+
+`filters` are standard record filters and `enrichment` adds context fields on
+an isolated copy of the record. `processors` transform the normalized event.
+`redact_secret_fields` and `redaction_replacement` provide a concise redaction
+policy, `schema` maps output names to dotted event paths, and `fields` retains
+top-level event fields. A sink with a stricter redaction policy cannot leak its
+unredacted record through another sink: each sink receives an isolated record
+and event copy.
+
+The deterministic order is: record filters, context enrichment, global
+processors, sink processors, redaction, schema projection, field selection,
+then formatting or webhook payload construction. Existing per-sink levels and
+formatters still run at their normal handler boundaries. Queue workers apply
+the same policy before each target handler, and webhook processing remains on
+the webhook worker.
+
+`RedactSecrets` remains available for custom processor pipelines. When using
+`redact_secret_fields`, set it to an empty tuple to explicitly disable the
+webhook's default redaction for that sink; omit it to retain the webhook
+configuration's default policy.
+
+For a standard-library custom formatter, set `OutputConfig.formatter`. YAPL
+applies that sink's processors and event policy to an isolated record before
+delegating to the formatter. The transformed normalized event is also
+available as `record.yapl_event`; without sink policies, the original formatter
+instance is used unchanged.
+
 ## Formatting
 
 Structured, text, JSON Lines, and logfmt output are available through the formatting extension.
@@ -211,12 +340,10 @@ Queue capacity limits the number of retained records, not their total byte size.
 
 ## Webhooks
 
-Webhook delivery is optional and uses `httpx`.
-
-Install it with:
+Webhook delivery requires the optional `webhook` extra, which installs `httpx`:
 
 ```bash
-uv add "yapl-kit[webhook]"
+pip install 'yapl-kit[webhook]'
 ```
 
 Configure a webhook:
@@ -325,9 +452,9 @@ Python cannot safely terminate arbitrary user handler code. Keep custom handlers
 
 `queue_enabled=False` runs normal stdlib handlers directly, so file, console, or custom sink work may occur on the caller thread.
 
-## Optional Modules
+## Extension Modules
 
-YAPL keeps concrete optional features under explicit modules:
+YAPL keeps feature families under explicit modules within the main distribution:
 
 ```python
 from yapl.stack import FunctionCallTracer, get_callsite
@@ -338,7 +465,7 @@ from yapl.extensions.queueing import QueueingConfig
 from yapl.extensions.webhook import WebhookConfig
 ```
 
-The `yapl.extensions` package is a namespace; concrete features live in its submodules.
+The `yapl.extensions` package contains the concrete feature implementations.
 
 ## Package Philosophy
 

{yapl_kit-0.2.0 → yapl_kit-0.3.0}/pyproject.toml

@@ -1,20 +1,16 @@
 [project]
 name = "yapl-kit"
-version = "0.2.0"
+version = "0.3.0"
 description = "YetAnotherPythonLogger - a minimal, extensible logging toolkit built on top of Python's standard logging module."
 readme = "PUBLIC.md"
 requires-python = ">=3.13"
-dependencies = []
 
 [[project.authors]]
 name = "SirKaiMartin"
 
 [project.optional-dependencies]
-formatting = []
-coloring = []
-buffering = []
-queueing = []
 webhook = ["httpx>=0.28.1"]
+opentelemetry = ["opentelemetry-api>=1.0"]
 
 [build-system]
 requires = ["uv_build>=0.12.16,<0.13.0"]
@@ -71,6 +67,9 @@ section-order = [
     "local-folder",
 ]
 
+[tool.ty.src]
+include = ["src"]
+
 [dependency-groups]
 dev = [
     "pytest>=9.1.1",

{yapl_kit-0.2.0 → yapl_kit-0.3.0}/pyproject.toml.orig

@@ -1,13 +1,16 @@
 [project]
 name = "yapl-kit"
-version = "0.2.0"
+version = "0.3.0"
 description = "YetAnotherPythonLogger - a minimal, extensible logging toolkit built on top of Python's standard logging module."
 readme = "PUBLIC.md"
 authors = [
     { name = "SirKaiMartin" }
 ]
 requires-python = ">=3.13"
-dependencies = []
+
+[project.optional-dependencies]
+webhook = ["httpx>=0.28.1"]
+opentelemetry = ["opentelemetry-api>=1.0"]
 
 [build-system]
 requires = ["uv_build>=0.12.16,<0.13.0"]
@@ -30,15 +33,6 @@ markers = [
     "performance: caller-latency, throughput, and backpressure regression coverage",
 ]
 
-[project.optional-dependencies]
-formatting = []
-coloring = []
-buffering = []
-queueing = []
-webhook = [
-    "httpx>=0.28.1",
-]
-
 [tool.ruff]
 target-version = "py313"
 line-length = 100
@@ -78,3 +72,6 @@ section-order = [
     "first-party",
     "local-folder",
 ]
+
+[tool.ty.src]
+include = ["src"]

{yapl_kit-0.2.0 → yapl_kit-0.3.0}/src/yapl/__init__.py

@@ -4,7 +4,6 @@ from .config import (
     ConsoleConfig,
     LoggerOverrides,
     OutputConfig,
-    StackConfig,
     SuppressionRule,
     SuppressionRules,
     YaplConfig,
@@ -52,7 +51,6 @@ from .types import (
     OutputDestination,
     OutputFormat,
     QueueOverflowPolicy,
-    StackMode,
 )
 
 
@@ -72,8 +70,6 @@ __all__ = [
     "QueueOverflowPolicy",
     "QueueingConfig",
     "RecordFlagPolicy",
-    "StackConfig",
-    "StackMode",
     "SuppressionRule",
     "SuppressionRules",
     "WebhookAuthConfig",

yapl_kit-0.3.0/src/yapl/_optional.py

@@ -0,0 +1,20 @@
+from __future__ import annotations
+
+from importlib import import_module
+from typing import Any
+
+
+def require_optional_dependency(module_name: str, *, extra: str, feature: str) -> Any:
+    """Translate an absent optional module into an actionable package-extra error."""
+    try:
+        return import_module(module_name)
+    except ModuleNotFoundError as exc:
+        missing_module = exc.name
+        if missing_module is None or not (
+            module_name == missing_module or module_name.startswith(f"{missing_module}.")
+        ):
+            raise
+        raise ImportError(
+            f"{feature} requires the '{extra}' extra. "
+            f"Install it with 'pip install yapl-kit[{extra}]'."
+        ) from exc

yapl_kit-0.3.0/src/yapl/_validation.py

@@ -0,0 +1,21 @@
+from __future__ import annotations
+
+from typing import TypeAliasType, get_args
+
+
+def validate_literal(
+    value: object,
+    alias: TypeAliasType,
+    field_name: str,
+    *,
+    error_message: str | None = None,
+) -> None:
+    """Reject values outside a PEP 695 ``Literal`` type alias."""
+    annotation: object = alias
+    while isinstance(annotation, TypeAliasType):
+        annotation = annotation.__value__
+
+    choices = get_args(annotation)
+    if value not in choices:
+        message = error_message or f"{field_name} must be one of {choices!r}; got {value!r}"
+        raise ValueError(message)