yapl-kit 0.1.0__tar.gz

yapl_kit-0.1.0/PKG-INFO

@@ -0,0 +1,345 @@
+Metadata-Version: 2.3
+Name: yapl-kit
+Version: 0.1.0
+Summary: YetAnotherPythonLogger - a minimal, extensible logging toolkit built on top of Python's standard logging module.
+Author: SirKaiMartin
+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: webhook
+Description-Content-Type: text/markdown
+
+<p align="center">
+  <img src="../docs/assets/yapl_banner.png" alt="YAPL banner">
+</p>
+
+# YAPL
+
+### Yet Another Python Logger
+
+> A modern, minimal, and extensible logging library built on top of Python's standard `logging` module.
+
+YAPL keeps the stdlib logging ecosystem intact while splitting the project into a small core and opt-in modules.
+
+- core setup stays dependency-free
+- additional behavior is imported from `yapl.stack` and `yapl.extensions.*`
+- buffering, queueing, formatting, coloring, and webhook delivery stay off the application hot path
+
+YAPL does not replace Python logging. It uses stdlib handlers, formatters, filters, and propagation exactly as they are.
+
+## Design principles
+
+- Configuration is explicit: setup arguments override a `YaplConfig` for one call
+  without mutating it.
+- Structured fields are built once at the logger boundary, then remain ordinary
+  `LogRecord` attributes for every handler and formatter.
+- The default queue path performs only a bounded, non-blocking enqueue on the
+  application thread. Formatting, file output, webhooks, and file-overflow
+  fallback run on workers. Choose `overflow_policy="block"` only when deliberate
+  backpressure is more important than application latency.
+- `shutdown_logging()` flushes and closes root handlers configured by YAPL; it
+  does not invoke the stdlib's process-wide `logging.shutdown()`.
+
+## Guarantees and non-guarantees
+
+In the default queued configuration, remote and sink I/O never runs on the
+caller thread, and queue insertion does not intentionally wait. This is an
+operational guarantee for YAPL's queue and built-in webhook path, not an
+absolute claim that logging can never block under every configuration.
+
+Guaranteed by default:
+
+- Queue-backed delivery has a bounded number of records. Queue insertion uses
+  non-blocking insertion under the default overflow policy.
+- Formatting, file/console delivery, webhook payload work, HTTP, DNS, and retry
+  waits happen on background workers.
+- Webhook retry attempts and retry delays are bounded. A handler reuses one
+  lazily created HTTP client while it is active.
+- Shutdown waiting is bounded by `shutdown_timeout_seconds`. When that deadline
+  expires, queued records may be discarded so the caller can continue.
+
+Not guaranteed:
+
+- Delivery of every record during overload, remote failure, or shutdown.
+- A fixed byte-level memory limit. Queue sizes bound record count, while queued
+  records retain message arguments, `extra`, exceptions, tracebacks, and any
+  object graphs they reference.
+- Termination of arbitrary custom handlers already blocked forever. Python
+  cannot safely kill user handler code. During forced reconfiguration YAPL emits
+  one `RuntimeWarning` if it observes an old queue worker still alive after its
+  bounded close wait; the new configuration uses new workers.
+
+Explicit opt-outs:
+
+- `overflow_policy="block"` deliberately enables application-level backpressure.
+  It may block the caller, indefinitely when `enqueue_timeout_seconds=None`.
+- `queue_enabled=False` runs normal stdlib handlers directly, so file, console,
+  or custom sink work can occur on the caller thread.
+
+Custom handlers are different from built-in transports: YAPL keeps their calls
+behind its queue by default, but cannot bound how long their own code takes once
+a worker enters it. Keep custom handlers non-blocking or give them their own
+timeouts.
+
+---
+
+# Architecture
+
+## Core
+
+Import the base package when you only need standard logging setup:
+
+```python
+import yapl
+
+log = yapl.setup_logging(level="INFO", outputs=("stdout",), format="text")
+
+log.info("hello world")
+log.warning("something happened")
+```
+
+Core imports stay small:
+
+- `yapl.setup_logging`
+- `yapl.shutdown_logging`
+- `yapl.get_logger`
+- `yapl.config`
+- `yapl.levels`
+- `yapl.logger`
+- `yapl.types`
+
+## Optional modules
+
+Import concrete modules when you want extra behavior:
+
+```python
+from yapl.stack import FunctionCallTracer, get_callsite
+from yapl.extensions.buffering import BufferedLogs, BufferingConfig
+from yapl.extensions.formatting import JSONFormatter, StructuredFormatterConfig
+from yapl.extensions.coloring import install_color_structured_console
+from yapl.extensions.queueing import QueueingConfig
+from yapl.extensions.webhook import WebhookConfig
+```
+
+The `yapl.extensions` package is only a namespace. The concrete features live in submodules.
+
+---
+
+# Quick Start
+
+```python
+import yapl
+
+yapl.setup_logging(level="INFO", outputs=("stdout",), format="text")
+log = yapl.get_logger(__name__)
+
+log.info("Hello world")
+log.warning("Something happened")
+```
+
+Structured calls work too:
+
+```python
+log.info("user_login", user_id=123, ip="1.2.3.4")
+log.error("payment_failed", order_id="A-17", exc_info=True)
+```
+
+For typed configuration and a webhook-enabled application, the common imports
+are available directly from `yapl`:
+
+```python
+from yapl import WebhookConfig, YaplConfig, get_logger, setup_logging
+
+config = YaplConfig(
+    queue_max_size=2_000,
+    webhook=WebhookConfig("https://example.com/webhook", min_level="ERROR"),
+)
+setup_logging(config, outputs=("stdout", "webhook"))
+
+logger = get_logger(__name__)
+logger.info("Application started")
+```
+
+Call `shutdown_logging()` during an orderly application shutdown when you want
+to give queued work its configured bounded drain window. It is safe to call
+more than once; records remaining at its deadline may be discarded.
+
+---
+
+# Buffering
+
+Buffering captures log records during a block and replays or discards them on exit:
+
+```python
+from yapl.extensions.buffering import BufferedLogs, BufferingConfig, install_buffering
+
+install_buffering()
+
+with BufferedLogs(BufferingConfig(flush_mode="ordered")):
+    log.info("preflight", phase="warmup")
+    log.warning("preflight_warning", stage=1)
+```
+
+The default behavior flushes buffered records on success and on error. Use the config to
+discard instead when a block should stay silent.
+
+---
+
+# Extended Levels
+
+YAPL can register extra development levels:
+
+```python
+yapl.setup_logging(level_mode="extended")
+
+log.trace("trace message")
+log.dev("dev message")
+```
+
+The built-in extended levels are:
+
+| Level | Value |
+| ----- | ----- |
+| TRACE | 5     |
+| DEV   | 15    |
+
+---
+
+# Stack Helpers
+
+Callsite and tracing live in `yapl.stack`:
+
+```python
+from yapl.stack import FunctionCallTracer, get_callsite
+
+callsite = get_callsite()
+
+with FunctionCallTracer():
+    run_complex_operation()
+```
+
+---
+
+# Formatting
+
+Structured, text, JSON Lines, and logfmt output live in `yapl.extensions.formatting`:
+
+```python
+from yapl.extensions.formatting import JSONFormatter, LogfmtFormatter, TextFormatter
+
+formatter = JSONFormatter()
+```
+
+Use sink profiles when one process needs both a human terminal and a machine stream:
+
+```python
+import yapl
+from yapl import OutputConfig, YaplConfig
+
+config = YaplConfig(
+    sinks=(
+        OutputConfig("stdout", format="text", color="auto", theme_name="dark"),
+        OutputConfig("file", format="jsonl", file_path="service.jsonl"),
+    ),
+    resource={
+        "service.name": "billing",
+        "deployment.environment": "production",
+    },
+)
+
+log = yapl.setup_logging(config)
+log.info("payment_processed", request_id="req-42")
+```
+
+`color="auto"` emits ANSI only to a TTY and respects `NO_COLOR`. Color is
+restricted to `text` and `plain` stdout/stderr sinks; `json`, `jsonl`, `logfmt`,
+files, and webhooks remain machine-readable.
+
+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. This keeps JSON streams portable while
+allowing Grafana Alloy, OpenTelemetry Collector, or another shipper to choose
+safe index labels.
+
+[`examples/grafana_alloy.river`](examples/grafana_alloy.river) shows a file-based
+Alloy pipeline. It keeps the source label static and stores request/trace
+identifiers as structured metadata. See
+[`examples/grafana_alloy_events.md`](examples/grafana_alloy_events.md) for
+representative JSONL events, field definitions, and the corresponding Alloy
+extraction. [`examples/log_output_examples.md`](examples/log_output_examples.md)
+is a comprehensive output reference covering terminal text and color, JSONL,
+logfmt, traces, stacks, redaction, queues, and webhooks.
+
+---
+
+# Queueing
+
+Queue-backed handlers keep application threads fast:
+
+```python
+from yapl.extensions.queueing import QueueingConfig, QueueingHandler
+```
+
+Use the queue when you want formatting, file writes, or webhook delivery to happen behind a worker. The queue capacity limits records, not bytes; avoid placing unbounded object graphs in log arguments or structured fields when memory limits matter.
+
+---
+
+# Webhooks
+
+Webhook delivery lives in `yapl.extensions.webhook`:
+
+```python
+from yapl.extensions.webhook import WebhookConfig
+
+webhook = WebhookConfig(url="https://example.com/webhook", min_level="ERROR")
+log = yapl.setup_logging(webhook=webhook)
+```
+
+Webhook work runs in the background so application threads do not intentionally
+wait for network I/O. HTTP clients are reused per active webhook handler, and
+timeouts/retries are bounded.
+
+---
+
+# Tests
+
+The functional suite is in `tests/` and is the default target for `pytest`.
+The original feedback-oriented coverage is preserved in `user_tests/` and can
+be run explicitly when checking the historical user-facing scenarios:
+
+```bash
+uv run pytest
+uv run pytest user_tests
+```
+
+---
+
+# Installation
+
+Core:
+
+```bash
+pip install yapl
+```
+
+With extensions:
+
+```bash
+pip install yapl[formatting,coloring,buffering,queueing,webhook]
+```
+
+---
+
+# Examples
+
+See:
+
+- `examples/basic_demo.py`
+- `examples/buffering_demo.py`
+- `examples/extended_demo.py`
+- `examples/benchmark_demo.py`
+
+The demos are configured from a small block at the top so you can turn features on and off quickly.

yapl_kit-0.1.0/README.md

@@ -0,0 +1,331 @@
+<p align="center">
+  <img src="../docs/assets/yapl_banner.png" alt="YAPL banner">
+</p>
+
+# YAPL
+
+### Yet Another Python Logger
+
+> A modern, minimal, and extensible logging library built on top of Python's standard `logging` module.
+
+YAPL keeps the stdlib logging ecosystem intact while splitting the project into a small core and opt-in modules.
+
+- core setup stays dependency-free
+- additional behavior is imported from `yapl.stack` and `yapl.extensions.*`
+- buffering, queueing, formatting, coloring, and webhook delivery stay off the application hot path
+
+YAPL does not replace Python logging. It uses stdlib handlers, formatters, filters, and propagation exactly as they are.
+
+## Design principles
+
+- Configuration is explicit: setup arguments override a `YaplConfig` for one call
+  without mutating it.
+- Structured fields are built once at the logger boundary, then remain ordinary
+  `LogRecord` attributes for every handler and formatter.
+- The default queue path performs only a bounded, non-blocking enqueue on the
+  application thread. Formatting, file output, webhooks, and file-overflow
+  fallback run on workers. Choose `overflow_policy="block"` only when deliberate
+  backpressure is more important than application latency.
+- `shutdown_logging()` flushes and closes root handlers configured by YAPL; it
+  does not invoke the stdlib's process-wide `logging.shutdown()`.
+
+## Guarantees and non-guarantees
+
+In the default queued configuration, remote and sink I/O never runs on the
+caller thread, and queue insertion does not intentionally wait. This is an
+operational guarantee for YAPL's queue and built-in webhook path, not an
+absolute claim that logging can never block under every configuration.
+
+Guaranteed by default:
+
+- Queue-backed delivery has a bounded number of records. Queue insertion uses
+  non-blocking insertion under the default overflow policy.
+- Formatting, file/console delivery, webhook payload work, HTTP, DNS, and retry
+  waits happen on background workers.
+- Webhook retry attempts and retry delays are bounded. A handler reuses one
+  lazily created HTTP client while it is active.
+- Shutdown waiting is bounded by `shutdown_timeout_seconds`. When that deadline
+  expires, queued records may be discarded so the caller can continue.
+
+Not guaranteed:
+
+- Delivery of every record during overload, remote failure, or shutdown.
+- A fixed byte-level memory limit. Queue sizes bound record count, while queued
+  records retain message arguments, `extra`, exceptions, tracebacks, and any
+  object graphs they reference.
+- Termination of arbitrary custom handlers already blocked forever. Python
+  cannot safely kill user handler code. During forced reconfiguration YAPL emits
+  one `RuntimeWarning` if it observes an old queue worker still alive after its
+  bounded close wait; the new configuration uses new workers.
+
+Explicit opt-outs:
+
+- `overflow_policy="block"` deliberately enables application-level backpressure.
+  It may block the caller, indefinitely when `enqueue_timeout_seconds=None`.
+- `queue_enabled=False` runs normal stdlib handlers directly, so file, console,
+  or custom sink work can occur on the caller thread.
+
+Custom handlers are different from built-in transports: YAPL keeps their calls
+behind its queue by default, but cannot bound how long their own code takes once
+a worker enters it. Keep custom handlers non-blocking or give them their own
+timeouts.
+
+---
+
+# Architecture
+
+## Core
+
+Import the base package when you only need standard logging setup:
+
+```python
+import yapl
+
+log = yapl.setup_logging(level="INFO", outputs=("stdout",), format="text")
+
+log.info("hello world")
+log.warning("something happened")
+```
+
+Core imports stay small:
+
+- `yapl.setup_logging`
+- `yapl.shutdown_logging`
+- `yapl.get_logger`
+- `yapl.config`
+- `yapl.levels`
+- `yapl.logger`
+- `yapl.types`
+
+## Optional modules
+
+Import concrete modules when you want extra behavior:
+
+```python
+from yapl.stack import FunctionCallTracer, get_callsite
+from yapl.extensions.buffering import BufferedLogs, BufferingConfig
+from yapl.extensions.formatting import JSONFormatter, StructuredFormatterConfig
+from yapl.extensions.coloring import install_color_structured_console
+from yapl.extensions.queueing import QueueingConfig
+from yapl.extensions.webhook import WebhookConfig
+```
+
+The `yapl.extensions` package is only a namespace. The concrete features live in submodules.
+
+---
+
+# Quick Start
+
+```python
+import yapl
+
+yapl.setup_logging(level="INFO", outputs=("stdout",), format="text")
+log = yapl.get_logger(__name__)
+
+log.info("Hello world")
+log.warning("Something happened")
+```
+
+Structured calls work too:
+
+```python
+log.info("user_login", user_id=123, ip="1.2.3.4")
+log.error("payment_failed", order_id="A-17", exc_info=True)
+```
+
+For typed configuration and a webhook-enabled application, the common imports
+are available directly from `yapl`:
+
+```python
+from yapl import WebhookConfig, YaplConfig, get_logger, setup_logging
+
+config = YaplConfig(
+    queue_max_size=2_000,
+    webhook=WebhookConfig("https://example.com/webhook", min_level="ERROR"),
+)
+setup_logging(config, outputs=("stdout", "webhook"))
+
+logger = get_logger(__name__)
+logger.info("Application started")
+```
+
+Call `shutdown_logging()` during an orderly application shutdown when you want
+to give queued work its configured bounded drain window. It is safe to call
+more than once; records remaining at its deadline may be discarded.
+
+---
+
+# Buffering
+
+Buffering captures log records during a block and replays or discards them on exit:
+
+```python
+from yapl.extensions.buffering import BufferedLogs, BufferingConfig, install_buffering
+
+install_buffering()
+
+with BufferedLogs(BufferingConfig(flush_mode="ordered")):
+    log.info("preflight", phase="warmup")
+    log.warning("preflight_warning", stage=1)
+```
+
+The default behavior flushes buffered records on success and on error. Use the config to
+discard instead when a block should stay silent.
+
+---
+
+# Extended Levels
+
+YAPL can register extra development levels:
+
+```python
+yapl.setup_logging(level_mode="extended")
+
+log.trace("trace message")
+log.dev("dev message")
+```
+
+The built-in extended levels are:
+
+| Level | Value |
+| ----- | ----- |
+| TRACE | 5     |
+| DEV   | 15    |
+
+---
+
+# Stack Helpers
+
+Callsite and tracing live in `yapl.stack`:
+
+```python
+from yapl.stack import FunctionCallTracer, get_callsite
+
+callsite = get_callsite()
+
+with FunctionCallTracer():
+    run_complex_operation()
+```
+
+---
+
+# Formatting
+
+Structured, text, JSON Lines, and logfmt output live in `yapl.extensions.formatting`:
+
+```python
+from yapl.extensions.formatting import JSONFormatter, LogfmtFormatter, TextFormatter
+
+formatter = JSONFormatter()
+```
+
+Use sink profiles when one process needs both a human terminal and a machine stream:
+
+```python
+import yapl
+from yapl import OutputConfig, YaplConfig
+
+config = YaplConfig(
+    sinks=(
+        OutputConfig("stdout", format="text", color="auto", theme_name="dark"),
+        OutputConfig("file", format="jsonl", file_path="service.jsonl"),
+    ),
+    resource={
+        "service.name": "billing",
+        "deployment.environment": "production",
+    },
+)
+
+log = yapl.setup_logging(config)
+log.info("payment_processed", request_id="req-42")
+```
+
+`color="auto"` emits ANSI only to a TTY and respects `NO_COLOR`. Color is
+restricted to `text` and `plain` stdout/stderr sinks; `json`, `jsonl`, `logfmt`,
+files, and webhooks remain machine-readable.
+
+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. This keeps JSON streams portable while
+allowing Grafana Alloy, OpenTelemetry Collector, or another shipper to choose
+safe index labels.
+
+[`examples/grafana_alloy.river`](examples/grafana_alloy.river) shows a file-based
+Alloy pipeline. It keeps the source label static and stores request/trace
+identifiers as structured metadata. See
+[`examples/grafana_alloy_events.md`](examples/grafana_alloy_events.md) for
+representative JSONL events, field definitions, and the corresponding Alloy
+extraction. [`examples/log_output_examples.md`](examples/log_output_examples.md)
+is a comprehensive output reference covering terminal text and color, JSONL,
+logfmt, traces, stacks, redaction, queues, and webhooks.
+
+---
+
+# Queueing
+
+Queue-backed handlers keep application threads fast:
+
+```python
+from yapl.extensions.queueing import QueueingConfig, QueueingHandler
+```
+
+Use the queue when you want formatting, file writes, or webhook delivery to happen behind a worker. The queue capacity limits records, not bytes; avoid placing unbounded object graphs in log arguments or structured fields when memory limits matter.
+
+---
+
+# Webhooks
+
+Webhook delivery lives in `yapl.extensions.webhook`:
+
+```python
+from yapl.extensions.webhook import WebhookConfig
+
+webhook = WebhookConfig(url="https://example.com/webhook", min_level="ERROR")
+log = yapl.setup_logging(webhook=webhook)
+```
+
+Webhook work runs in the background so application threads do not intentionally
+wait for network I/O. HTTP clients are reused per active webhook handler, and
+timeouts/retries are bounded.
+
+---
+
+# Tests
+
+The functional suite is in `tests/` and is the default target for `pytest`.
+The original feedback-oriented coverage is preserved in `user_tests/` and can
+be run explicitly when checking the historical user-facing scenarios:
+
+```bash
+uv run pytest
+uv run pytest user_tests
+```
+
+---
+
+# Installation
+
+Core:
+
+```bash
+pip install yapl
+```
+
+With extensions:
+
+```bash
+pip install yapl[formatting,coloring,buffering,queueing,webhook]
+```
+
+---
+
+# Examples
+
+See:
+
+- `examples/basic_demo.py`
+- `examples/buffering_demo.py`
+- `examples/extended_demo.py`
+- `examples/benchmark_demo.py`
+
+The demos are configured from a small block at the top so you can turn features on and off quickly.

yapl_kit-0.1.0/pyproject.toml

@@ -0,0 +1,37 @@
+[project]
+name = "yapl-kit"
+version = "0.1.0"
+description = "YetAnotherPythonLogger - a minimal, extensible logging toolkit built on top of Python's standard logging module."
+readme = "README.md"
+requires-python = ">=3.13"
+dependencies = []
+
+[[project.authors]]
+name = "SirKaiMartin"
+
+[project.optional-dependencies]
+formatting = []
+coloring = []
+buffering = []
+queueing = []
+webhook = ["httpx>=0.28.1"]
+
+[build-system]
+requires = ["uv_build>=0.12.16,<0.13.0"]
+build-backend = "uv_build"
+
+[tool.uv.build-backend]
+module-name = [
+    "yapl",
+    "yapl_kit",
+]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+
+[dependency-groups]
+dev = [
+    "pytest>=9.1.1",
+    "ruff>=0.16.8",
+    "ty>=0.0.82",
+]