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

yapl_kit-0.2.1/PUBLIC.md → yapl_kit-0.3.0/PKG-INFO

@@ -1,3 +1,15 @@
+Metadata-Version: 2.3
+Name: yapl-kit
+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: opentelemetry
+Provides-Extra: webhook
+Description-Content-Type: text/markdown
+
 # YAPL Kit
 
 ### Yet Another Python Logger
@@ -6,8 +18,9 @@
 
 YAPL keeps the stdlib logging ecosystem intact while adding structured logging, queue-backed delivery, formatting, coloring, buffering, stack helpers, and webhook support.
 
-All YAPL feature families ship in the single `yapl-kit` distribution. Webhook
-support uses `httpx`, which is installed automatically.
+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
 
@@ -25,6 +38,16 @@ With `pip`:
 pip install yapl-kit
 ```
 
+Install webhook or OpenTelemetry integrations only when needed:
+
+```bash
+pip install 'yapl-kit[webhook]'
+pip install 'yapl-kit[opentelemetry]'
+```
+
+With `uv`, use `uv add 'yapl-kit[webhook]'` or
+`uv add 'yapl-kit[opentelemetry]'`.
+
 The canonical import namespace is `yapl`:
 
 ```python
@@ -104,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
@@ -127,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.
@@ -161,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.
@@ -200,7 +352,11 @@ Queue capacity limits the number of retained records, not their total byte size.
 
 ## Webhooks
 
-Webhook delivery uses `httpx`, included automatically with `yapl-kit`.
+Webhook delivery requires the optional `webhook` extra, which installs `httpx`:
+
+```bash
+pip install 'yapl-kit[webhook]'
+```
 
 Configure a webhook:
 

yapl_kit-0.2.1/PKG-INFO → yapl_kit-0.3.0/PUBLIC.md

@@ -1,12 +1,3 @@
-Metadata-Version: 2.3
-Name: yapl-kit
-Version: 0.2.1
-Summary: YetAnotherPythonLogger - a minimal, extensible logging toolkit built on top of Python's standard logging module.
-Author: SirKaiMartin
-Requires-Dist: httpx>=0.28.1
-Requires-Python: >=3.13
-Description-Content-Type: text/markdown
-
 # YAPL Kit
 
 ### Yet Another Python Logger
@@ -15,8 +6,9 @@ Description-Content-Type: text/markdown
 
 YAPL keeps the stdlib logging ecosystem intact while adding structured logging, queue-backed delivery, formatting, coloring, buffering, stack helpers, and webhook support.
 
-All YAPL feature families ship in the single `yapl-kit` distribution. Webhook
-support uses `httpx`, which is installed automatically.
+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
 
@@ -34,6 +26,16 @@ With `pip`:
 pip install yapl-kit
 ```
 
+Install webhook or OpenTelemetry integrations only when needed:
+
+```bash
+pip install 'yapl-kit[webhook]'
+pip install 'yapl-kit[opentelemetry]'
+```
+
+With `uv`, use `uv add 'yapl-kit[webhook]'` or
+`uv add 'yapl-kit[opentelemetry]'`.
+
 The canonical import namespace is `yapl`:
 
 ```python
@@ -113,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
@@ -136,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.
@@ -170,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.
@@ -209,7 +340,11 @@ Queue capacity limits the number of retained records, not their total byte size.
 
 ## Webhooks
 
-Webhook delivery uses `httpx`, included automatically with `yapl-kit`.
+Webhook delivery requires the optional `webhook` extra, which installs `httpx`:
+
+```bash
+pip install 'yapl-kit[webhook]'
+```
 
 Configure a webhook:
 

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

@@ -1,14 +1,17 @@
 [project]
 name = "yapl-kit"
-version = "0.2.1"
+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 = ["httpx>=0.28.1"]
 
 [[project.authors]]
 name = "SirKaiMartin"
 
+[project.optional-dependencies]
+webhook = ["httpx>=0.28.1"]
+opentelemetry = ["opentelemetry-api>=1.0"]
+
 [build-system]
 requires = ["uv_build>=0.12.16,<0.13.0"]
 build-backend = "uv_build"

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

@@ -1,15 +1,16 @@
 [project]
 name = "yapl-kit"
-version = "0.2.1"
+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 = [
-    "httpx>=0.28.1",
-]
+
+[project.optional-dependencies]
+webhook = ["httpx>=0.28.1"]
+opentelemetry = ["opentelemetry-api>=1.0"]
 
 [build-system]
 requires = ["uv_build>=0.12.16,<0.13.0"]

{yapl_kit-0.2.1 → 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)