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

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (61) hide show
  1. yapl_kit-0.2.0/PKG-INFO +368 -0
  2. yapl_kit-0.2.0/PUBLIC.md +354 -0
  3. yapl_kit-0.2.0/pyproject.toml +79 -0
  4. yapl_kit-0.2.0/pyproject.toml.orig +80 -0
  5. {yapl_kit-0.1.0 → yapl_kit-0.2.0}/src/yapl/__init__.py +19 -9
  6. {yapl_kit-0.1.0 → yapl_kit-0.2.0}/src/yapl/config.py +80 -1
  7. yapl_kit-0.2.0/src/yapl/context.py +64 -0
  8. {yapl_kit-0.1.0 → yapl_kit-0.2.0}/src/yapl/extensions/buffering/__init__.py +0 -2
  9. {yapl_kit-0.1.0 → yapl_kit-0.2.0}/src/yapl/extensions/buffering/capture.py +66 -66
  10. {yapl_kit-0.1.0 → yapl_kit-0.2.0}/src/yapl/extensions/buffering/flush.py +71 -71
  11. {yapl_kit-0.1.0 → yapl_kit-0.2.0}/src/yapl/extensions/buffering/models.py +65 -65
  12. {yapl_kit-0.1.0 → yapl_kit-0.2.0}/src/yapl/extensions/coloring/__init__.py +0 -2
  13. {yapl_kit-0.1.0 → yapl_kit-0.2.0}/src/yapl/extensions/coloring/colors.py +86 -86
  14. {yapl_kit-0.1.0 → yapl_kit-0.2.0}/src/yapl/extensions/coloring/models.py +121 -121
  15. {yapl_kit-0.1.0 → yapl_kit-0.2.0}/src/yapl/extensions/coloring/plain.py +113 -113
  16. {yapl_kit-0.1.0 → yapl_kit-0.2.0}/src/yapl/extensions/coloring/registry.py +119 -119
  17. {yapl_kit-0.1.0 → yapl_kit-0.2.0}/src/yapl/extensions/coloring/structured.py +100 -100
  18. {yapl_kit-0.1.0 → yapl_kit-0.2.0}/src/yapl/extensions/coloring/themes.py +111 -111
  19. {yapl_kit-0.1.0 → yapl_kit-0.2.0}/src/yapl/extensions/formatting/__init__.py +0 -2
  20. {yapl_kit-0.1.0 → yapl_kit-0.2.0}/src/yapl/extensions/formatting/_types.py +21 -21
  21. {yapl_kit-0.1.0 → yapl_kit-0.2.0}/src/yapl/extensions/formatting/plain.py +103 -103
  22. {yapl_kit-0.1.0 → yapl_kit-0.2.0}/src/yapl/extensions/formatting/structured.py +651 -656
  23. {yapl_kit-0.1.0 → yapl_kit-0.2.0}/src/yapl/extensions/queueing/__init__.py +0 -2
  24. {yapl_kit-0.1.0 → yapl_kit-0.2.0}/src/yapl/extensions/queueing/handler.py +92 -28
  25. {yapl_kit-0.1.0 → yapl_kit-0.2.0}/src/yapl/extensions/queueing/models.py +129 -126
  26. {yapl_kit-0.1.0 → yapl_kit-0.2.0}/src/yapl/extensions/queueing/policy.py +0 -6
  27. {yapl_kit-0.1.0 → yapl_kit-0.2.0}/src/yapl/extensions/queueing/worker.py +4 -10
  28. {yapl_kit-0.1.0 → yapl_kit-0.2.0}/src/yapl/extensions/webhook/__init__.py +0 -2
  29. {yapl_kit-0.1.0 → yapl_kit-0.2.0}/src/yapl/extensions/webhook/client.py +22 -4
  30. {yapl_kit-0.1.0 → yapl_kit-0.2.0}/src/yapl/extensions/webhook/handler.py +12 -5
  31. {yapl_kit-0.1.0 → yapl_kit-0.2.0}/src/yapl/extensions/webhook/models.py +217 -210
  32. {yapl_kit-0.1.0 → yapl_kit-0.2.0}/src/yapl/extensions/webhook/payloads.py +67 -15
  33. {yapl_kit-0.1.0 → yapl_kit-0.2.0}/src/yapl/factory.py +248 -41
  34. {yapl_kit-0.1.0 → yapl_kit-0.2.0}/src/yapl/filters/__init__.py +0 -2
  35. {yapl_kit-0.1.0 → yapl_kit-0.2.0}/src/yapl/filters/enrichment.py +116 -116
  36. {yapl_kit-0.1.0 → yapl_kit-0.2.0}/src/yapl/filters/suppression.py +69 -69
  37. {yapl_kit-0.1.0 → yapl_kit-0.2.0}/src/yapl/levels.py +134 -134
  38. {yapl_kit-0.1.0 → yapl_kit-0.2.0}/src/yapl/logger.py +21 -0
  39. {yapl_kit-0.1.0 → yapl_kit-0.2.0}/src/yapl/stack/__init__.py +0 -2
  40. {yapl_kit-0.1.0 → yapl_kit-0.2.0}/src/yapl/stack/callsite.py +75 -75
  41. {yapl_kit-0.1.0 → yapl_kit-0.2.0}/src/yapl/stack/tracer.py +157 -157
  42. yapl_kit-0.2.0/src/yapl/status.py +29 -0
  43. yapl_kit-0.2.0/src/yapl/testing.py +42 -0
  44. {yapl_kit-0.1.0 → yapl_kit-0.2.0}/src/yapl/types.py +0 -6
  45. {yapl_kit-0.1.0 → yapl_kit-0.2.0}/src/yapl_kit/__init__.py +2 -2
  46. yapl_kit-0.1.0/PKG-INFO +0 -345
  47. yapl_kit-0.1.0/README.md +0 -331
  48. yapl_kit-0.1.0/pyproject.toml +0 -37
  49. yapl_kit-0.1.0/pyproject.toml.orig +0 -36
  50. {yapl_kit-0.1.0 → yapl_kit-0.2.0}/src/yapl/extensions/buffering/context.py +0 -0
  51. {yapl_kit-0.1.0 → yapl_kit-0.2.0}/src/yapl/extensions/coloring/policy.py +0 -0
  52. {yapl_kit-0.1.0 → yapl_kit-0.2.0}/src/yapl/extensions/coloring/text.py +0 -0
  53. {yapl_kit-0.1.0 → yapl_kit-0.2.0}/src/yapl/extensions/formatting/_helpers.py +0 -0
  54. {yapl_kit-0.1.0 → yapl_kit-0.2.0}/src/yapl/extensions/formatting/formatters.py +0 -0
  55. {yapl_kit-0.1.0 → yapl_kit-0.2.0}/src/yapl/extensions/formatting/json.py +0 -0
  56. {yapl_kit-0.1.0 → yapl_kit-0.2.0}/src/yapl/extensions/formatting/logfmt.py +0 -0
  57. {yapl_kit-0.1.0 → yapl_kit-0.2.0}/src/yapl/extensions/formatting/processors.py +0 -0
  58. {yapl_kit-0.1.0 → yapl_kit-0.2.0}/src/yapl/extensions/formatting/text.py +0 -0
  59. {yapl_kit-0.1.0 → yapl_kit-0.2.0}/src/yapl/extensions/queueing/queue.py +0 -0
  60. {yapl_kit-0.1.0 → yapl_kit-0.2.0}/src/yapl/py.typed +0 -0
  61. {yapl_kit-0.1.0 → yapl_kit-0.2.0}/src/yapl_kit/py.typed +0 -0
@@ -0,0 +1,368 @@
1
+ Metadata-Version: 2.3
2
+ Name: yapl-kit
3
+ Version: 0.2.0
4
+ Summary: YetAnotherPythonLogger - a minimal, extensible logging toolkit built on top of Python's standard logging module.
5
+ Author: SirKaiMartin
6
+ Requires-Dist: httpx>=0.28.1 ; extra == 'webhook'
7
+ Requires-Python: >=3.13
8
+ Provides-Extra: buffering
9
+ Provides-Extra: coloring
10
+ Provides-Extra: formatting
11
+ Provides-Extra: queueing
12
+ Provides-Extra: webhook
13
+ Description-Content-Type: text/markdown
14
+
15
+ # YAPL Kit
16
+
17
+ ### Yet Another Python Logger
18
+
19
+ > A modern, minimal, and extensible logging toolkit built on top of Python's standard `logging` module.
20
+
21
+ YAPL keeps the stdlib logging ecosystem intact while adding structured logging, queue-backed delivery, formatting, coloring, buffering, stack helpers, and optional webhook support.
22
+
23
+ The core stays dependency-free. Optional integrations are installed only when you need them.
24
+
25
+ ## Installation
26
+
27
+ YAPL Kit requires Python 3.13 or newer.
28
+
29
+ With `uv`:
30
+
31
+ ```bash
32
+ uv add yapl-kit
33
+ ```
34
+
35
+ With `pip`:
36
+
37
+ ```bash
38
+ pip install yapl-kit
39
+ ```
40
+
41
+ Install all optional features:
42
+
43
+ ```bash
44
+ uv add "yapl-kit[formatting,coloring,buffering,queueing,webhook]"
45
+ ```
46
+
47
+ or:
48
+
49
+ ```bash
50
+ pip install "yapl-kit[formatting,coloring,buffering,queueing,webhook]"
51
+ ```
52
+
53
+ The canonical import namespace is `yapl`:
54
+
55
+ ```python
56
+ import yapl
57
+ ```
58
+
59
+ The package also exposes a root-level compatibility namespace:
60
+
61
+ ```python
62
+ import yapl_kit
63
+ ```
64
+
65
+ Documentation examples use `yapl`.
66
+
67
+ ## Quick Start
68
+
69
+ ```python
70
+ import yapl
71
+
72
+ yapl.setup_logging(
73
+ level="INFO",
74
+ outputs=("stdout",),
75
+ format="text",
76
+ )
77
+
78
+ log = yapl.get_logger(__name__)
79
+
80
+ log.info("Hello world")
81
+ log.warning("Something happened")
82
+ ```
83
+
84
+ Structured fields can be attached directly to log calls:
85
+
86
+ ```python
87
+ log.info("user_login", user_id=123, ip="1.2.3.4")
88
+ log.error("payment_failed", order_id="A-17", exc_info=True)
89
+ ```
90
+
91
+ Shared request or job fields can be scoped to a block:
92
+
93
+ ```python
94
+ with yapl.context(request_id="req-42", user_id=123):
95
+ log.info("request_started")
96
+ log.info("request_finished")
97
+ ```
98
+
99
+ For orderly application shutdown, call:
100
+
101
+ ```python
102
+ yapl.shutdown_logging()
103
+ ```
104
+
105
+ This gives queued work its configured bounded drain window. Records still pending when the shutdown deadline expires may be discarded.
106
+
107
+ Use `yapl.flush_logging()` to drain queued work while keeping logging active,
108
+ or use `yapl.logging_session(...)` for scripts that should configure and shut
109
+ down YAPL around one block. `yapl.logging_status()` exposes queue and webhook
110
+ delivery counters for operational checks.
111
+
112
+ `logging_session()` owns the process-wide YAPL configuration for its block and
113
+ does not restore an earlier YAPL setup; use it at an application or script
114
+ boundary rather than nesting it inside another logging session.
115
+
116
+ ## Design
117
+
118
+ YAPL does not replace Python logging. It builds on stdlib handlers, formatters, filters, `LogRecord` objects, and propagation.
119
+
120
+ The main design goals are:
121
+
122
+ - keep the core small and dependency-free
123
+ - preserve compatibility with Python's logging ecosystem
124
+ - keep expensive formatting and I/O off the application hot path
125
+ - make queueing, retries, and shutdown behavior bounded
126
+ - keep optional features isolated and explicit
127
+ - remain easy to understand and maintain
128
+
129
+ ## Configuration
130
+
131
+ YAPL supports direct setup arguments as well as typed configuration.
132
+
133
+ ```python
134
+ from yapl import WebhookConfig, YaplConfig, get_logger, setup_logging
135
+
136
+ config = YaplConfig(
137
+ queue_max_size=2_000,
138
+ webhook=WebhookConfig(
139
+ "https://example.com/webhook",
140
+ min_level="ERROR",
141
+ ),
142
+ )
143
+
144
+ setup_logging(
145
+ config,
146
+ outputs=("stdout", "webhook"),
147
+ )
148
+
149
+ log = get_logger(__name__)
150
+ log.info("Application started")
151
+ ```
152
+
153
+ Setup arguments override the supplied `YaplConfig` for that call without mutating the configuration object.
154
+
155
+ ## Output Profiles
156
+
157
+ A single process can use different output profiles for different sinks.
158
+
159
+ ```python
160
+ import yapl
161
+ from yapl import OutputConfig, YaplConfig
162
+
163
+ config = YaplConfig(
164
+ sinks=(
165
+ OutputConfig(
166
+ "stdout",
167
+ format="text",
168
+ color="auto",
169
+ theme_name="dark",
170
+ ),
171
+ OutputConfig(
172
+ "file",
173
+ format="jsonl",
174
+ file_path="service.jsonl",
175
+ ),
176
+ ),
177
+ resource={
178
+ "service.name": "billing",
179
+ "deployment.environment": "production",
180
+ },
181
+ )
182
+
183
+ log = yapl.setup_logging(config)
184
+ log.info("payment_processed", request_id="req-42")
185
+ ```
186
+
187
+ 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.
188
+
189
+ ## Formatting
190
+
191
+ Structured, text, JSON Lines, and logfmt output are available through the formatting extension.
192
+
193
+ ```python
194
+ from yapl.extensions.formatting import (
195
+ JSONFormatter,
196
+ LogfmtFormatter,
197
+ TextFormatter,
198
+ )
199
+
200
+ formatter = JSONFormatter()
201
+ ```
202
+
203
+ Color output is restricted to human-facing text/plain terminal sinks. JSON, JSONL, logfmt, files, and webhooks remain machine-readable.
204
+
205
+ `color="auto"` emits ANSI only for a compatible terminal and respects `NO_COLOR`.
206
+
207
+ ## Queueing
208
+
209
+ Queue-backed handlers keep sink work away from application threads.
210
+
211
+ ```python
212
+ from yapl.extensions.queueing import QueueingConfig, QueueingHandler
213
+ ```
214
+
215
+ In the default queued configuration:
216
+
217
+ - queue insertion is bounded and non-blocking
218
+ - formatting runs on workers
219
+ - file and console sink work runs on workers
220
+ - webhook payload construction and network I/O run on workers
221
+ - retries and retry delays are bounded
222
+ - shutdown waiting is bounded
223
+
224
+ Queue capacity limits the number of retained records, not their total byte size. Queued records may retain message arguments, `extra` values, exceptions, tracebacks, and object graphs until processed or discarded.
225
+
226
+ ## Webhooks
227
+
228
+ Webhook delivery is optional and uses `httpx`.
229
+
230
+ Install it with:
231
+
232
+ ```bash
233
+ uv add "yapl-kit[webhook]"
234
+ ```
235
+
236
+ Configure a webhook:
237
+
238
+ ```python
239
+ import yapl
240
+ from yapl.extensions.webhook import WebhookConfig
241
+
242
+ webhook = WebhookConfig(
243
+ url="https://example.com/webhook",
244
+ min_level="ERROR",
245
+ )
246
+
247
+ log = yapl.setup_logging(webhook=webhook)
248
+ ```
249
+
250
+ Webhook work runs in the background so application threads do not intentionally wait for network I/O. Active webhook handlers reuse their HTTP client, and timeout/retry behavior is bounded.
251
+
252
+ ## Buffering
253
+
254
+ Buffering captures records during a block and then replays or discards them when the block exits.
255
+
256
+ ```python
257
+ from yapl.extensions.buffering import (
258
+ BufferedLogs,
259
+ BufferingConfig,
260
+ install_buffering,
261
+ )
262
+
263
+ install_buffering()
264
+
265
+ with BufferedLogs(BufferingConfig(flush_mode="ordered")):
266
+ log.info("preflight", phase="warmup")
267
+ log.warning("preflight_warning", stage=1)
268
+ ```
269
+
270
+ The default behavior flushes buffered records on success and on error. Configuration can be used to discard them instead when a block should remain silent.
271
+
272
+ ## Extended Levels
273
+
274
+ YAPL can register extra development levels:
275
+
276
+ ```python
277
+ import yapl
278
+
279
+ yapl.setup_logging(level_mode="extended")
280
+
281
+ log = yapl.get_logger(__name__)
282
+ log.trace("trace message")
283
+ log.dev("dev message")
284
+ ```
285
+
286
+ Built-in extended levels:
287
+
288
+ | Level | Value |
289
+ | --- | ---: |
290
+ | `TRACE` | 5 |
291
+ | `DEV` | 15 |
292
+
293
+ ## Stack Helpers
294
+
295
+ Callsite and tracing helpers live under `yapl.stack`.
296
+
297
+ ```python
298
+ from yapl import get_logger, setup_logging
299
+ from yapl.stack import FunctionCallTracer, get_callsite
300
+
301
+ setup_logging(level_mode="extended")
302
+ callsite = get_callsite()
303
+
304
+ tracer = FunctionCallTracer(get_logger(__name__))
305
+ tracer.enable_current_thread()
306
+ try:
307
+ run_complex_operation()
308
+ finally:
309
+ tracer.disable_current_thread()
310
+ ```
311
+
312
+ ## Guarantees and Non-Guarantees
313
+
314
+ In the default queued configuration, remote and sink I/O never runs on the caller thread, and queue insertion does not intentionally wait.
315
+
316
+ 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 possible configuration.
317
+
318
+ ### Guaranteed by default
319
+
320
+ - Queue-backed delivery has a bounded record count.
321
+ - Queue insertion uses non-blocking insertion under the default overflow policy.
322
+ - Formatting, file/console delivery, webhook payload work, HTTP, DNS, and retry waits happen on background workers.
323
+ - Webhook retry attempts and retry delays are bounded.
324
+ - Active webhook handlers reuse a lazily created HTTP client.
325
+ - Shutdown waiting is bounded by `shutdown_timeout_seconds`.
326
+ - Records may be discarded when the shutdown deadline expires so the caller can continue.
327
+
328
+ ### Not guaranteed
329
+
330
+ - Delivery of every record during overload, remote failure, or shutdown.
331
+ - A fixed byte-level memory limit.
332
+ - Termination of arbitrary custom handlers already blocked forever.
333
+
334
+ Python cannot safely terminate arbitrary user handler code. Keep custom handlers non-blocking or give them their own timeouts.
335
+
336
+ ### Explicit opt-outs
337
+
338
+ `overflow_policy="block"` deliberately enables application-level backpressure and may block the caller. With `enqueue_timeout_seconds=None`, that wait may be indefinite.
339
+
340
+ `queue_enabled=False` runs normal stdlib handlers directly, so file, console, or custom sink work may occur on the caller thread.
341
+
342
+ ## Optional Modules
343
+
344
+ YAPL keeps concrete optional features under explicit modules:
345
+
346
+ ```python
347
+ from yapl.stack import FunctionCallTracer, get_callsite
348
+ from yapl.extensions.buffering import BufferedLogs, BufferingConfig
349
+ from yapl.extensions.coloring import install_color_structured_console
350
+ from yapl.extensions.formatting import JSONFormatter, StructuredFormatterConfig
351
+ from yapl.extensions.queueing import QueueingConfig
352
+ from yapl.extensions.webhook import WebhookConfig
353
+ ```
354
+
355
+ The `yapl.extensions` package is a namespace; concrete features live in its submodules.
356
+
357
+ ## Package Philosophy
358
+
359
+ YAPL is intended to be a small quality-of-life logging toolkit rather than a replacement observability framework.
360
+
361
+ The focus is on:
362
+
363
+ - predictable behavior
364
+ - low caller-side overhead
365
+ - bounded background work
366
+ - readable configuration
367
+ - stdlib compatibility
368
+ - optional features without unnecessary runtime weight
@@ -0,0 +1,354 @@
1
+ # YAPL Kit
2
+
3
+ ### Yet Another Python Logger
4
+
5
+ > A modern, minimal, and extensible logging toolkit built on top of Python's standard `logging` module.
6
+
7
+ YAPL keeps the stdlib logging ecosystem intact while adding structured logging, queue-backed delivery, formatting, coloring, buffering, stack helpers, and optional webhook support.
8
+
9
+ The core stays dependency-free. Optional integrations are installed only when you need them.
10
+
11
+ ## Installation
12
+
13
+ YAPL Kit requires Python 3.13 or newer.
14
+
15
+ With `uv`:
16
+
17
+ ```bash
18
+ uv add yapl-kit
19
+ ```
20
+
21
+ With `pip`:
22
+
23
+ ```bash
24
+ pip install yapl-kit
25
+ ```
26
+
27
+ Install all optional features:
28
+
29
+ ```bash
30
+ uv add "yapl-kit[formatting,coloring,buffering,queueing,webhook]"
31
+ ```
32
+
33
+ or:
34
+
35
+ ```bash
36
+ pip install "yapl-kit[formatting,coloring,buffering,queueing,webhook]"
37
+ ```
38
+
39
+ The canonical import namespace is `yapl`:
40
+
41
+ ```python
42
+ import yapl
43
+ ```
44
+
45
+ The package also exposes a root-level compatibility namespace:
46
+
47
+ ```python
48
+ import yapl_kit
49
+ ```
50
+
51
+ Documentation examples use `yapl`.
52
+
53
+ ## Quick Start
54
+
55
+ ```python
56
+ import yapl
57
+
58
+ yapl.setup_logging(
59
+ level="INFO",
60
+ outputs=("stdout",),
61
+ format="text",
62
+ )
63
+
64
+ log = yapl.get_logger(__name__)
65
+
66
+ log.info("Hello world")
67
+ log.warning("Something happened")
68
+ ```
69
+
70
+ Structured fields can be attached directly to log calls:
71
+
72
+ ```python
73
+ log.info("user_login", user_id=123, ip="1.2.3.4")
74
+ log.error("payment_failed", order_id="A-17", exc_info=True)
75
+ ```
76
+
77
+ Shared request or job fields can be scoped to a block:
78
+
79
+ ```python
80
+ with yapl.context(request_id="req-42", user_id=123):
81
+ log.info("request_started")
82
+ log.info("request_finished")
83
+ ```
84
+
85
+ For orderly application shutdown, call:
86
+
87
+ ```python
88
+ yapl.shutdown_logging()
89
+ ```
90
+
91
+ This gives queued work its configured bounded drain window. Records still pending when the shutdown deadline expires may be discarded.
92
+
93
+ Use `yapl.flush_logging()` to drain queued work while keeping logging active,
94
+ or use `yapl.logging_session(...)` for scripts that should configure and shut
95
+ down YAPL around one block. `yapl.logging_status()` exposes queue and webhook
96
+ delivery counters for operational checks.
97
+
98
+ `logging_session()` owns the process-wide YAPL configuration for its block and
99
+ does not restore an earlier YAPL setup; use it at an application or script
100
+ boundary rather than nesting it inside another logging session.
101
+
102
+ ## Design
103
+
104
+ YAPL does not replace Python logging. It builds on stdlib handlers, formatters, filters, `LogRecord` objects, and propagation.
105
+
106
+ The main design goals are:
107
+
108
+ - keep the core small and dependency-free
109
+ - preserve compatibility with Python's logging ecosystem
110
+ - keep expensive formatting and I/O off the application hot path
111
+ - make queueing, retries, and shutdown behavior bounded
112
+ - keep optional features isolated and explicit
113
+ - remain easy to understand and maintain
114
+
115
+ ## Configuration
116
+
117
+ YAPL supports direct setup arguments as well as typed configuration.
118
+
119
+ ```python
120
+ from yapl import WebhookConfig, YaplConfig, get_logger, setup_logging
121
+
122
+ config = YaplConfig(
123
+ queue_max_size=2_000,
124
+ webhook=WebhookConfig(
125
+ "https://example.com/webhook",
126
+ min_level="ERROR",
127
+ ),
128
+ )
129
+
130
+ setup_logging(
131
+ config,
132
+ outputs=("stdout", "webhook"),
133
+ )
134
+
135
+ log = get_logger(__name__)
136
+ log.info("Application started")
137
+ ```
138
+
139
+ Setup arguments override the supplied `YaplConfig` for that call without mutating the configuration object.
140
+
141
+ ## Output Profiles
142
+
143
+ A single process can use different output profiles for different sinks.
144
+
145
+ ```python
146
+ import yapl
147
+ from yapl import OutputConfig, YaplConfig
148
+
149
+ config = YaplConfig(
150
+ sinks=(
151
+ OutputConfig(
152
+ "stdout",
153
+ format="text",
154
+ color="auto",
155
+ theme_name="dark",
156
+ ),
157
+ OutputConfig(
158
+ "file",
159
+ format="jsonl",
160
+ file_path="service.jsonl",
161
+ ),
162
+ ),
163
+ resource={
164
+ "service.name": "billing",
165
+ "deployment.environment": "production",
166
+ },
167
+ )
168
+
169
+ log = yapl.setup_logging(config)
170
+ log.info("payment_processed", request_id="req-42")
171
+ ```
172
+
173
+ 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.
174
+
175
+ ## Formatting
176
+
177
+ Structured, text, JSON Lines, and logfmt output are available through the formatting extension.
178
+
179
+ ```python
180
+ from yapl.extensions.formatting import (
181
+ JSONFormatter,
182
+ LogfmtFormatter,
183
+ TextFormatter,
184
+ )
185
+
186
+ formatter = JSONFormatter()
187
+ ```
188
+
189
+ Color output is restricted to human-facing text/plain terminal sinks. JSON, JSONL, logfmt, files, and webhooks remain machine-readable.
190
+
191
+ `color="auto"` emits ANSI only for a compatible terminal and respects `NO_COLOR`.
192
+
193
+ ## Queueing
194
+
195
+ Queue-backed handlers keep sink work away from application threads.
196
+
197
+ ```python
198
+ from yapl.extensions.queueing import QueueingConfig, QueueingHandler
199
+ ```
200
+
201
+ In the default queued configuration:
202
+
203
+ - queue insertion is bounded and non-blocking
204
+ - formatting runs on workers
205
+ - file and console sink work runs on workers
206
+ - webhook payload construction and network I/O run on workers
207
+ - retries and retry delays are bounded
208
+ - shutdown waiting is bounded
209
+
210
+ Queue capacity limits the number of retained records, not their total byte size. Queued records may retain message arguments, `extra` values, exceptions, tracebacks, and object graphs until processed or discarded.
211
+
212
+ ## Webhooks
213
+
214
+ Webhook delivery is optional and uses `httpx`.
215
+
216
+ Install it with:
217
+
218
+ ```bash
219
+ uv add "yapl-kit[webhook]"
220
+ ```
221
+
222
+ Configure a webhook:
223
+
224
+ ```python
225
+ import yapl
226
+ from yapl.extensions.webhook import WebhookConfig
227
+
228
+ webhook = WebhookConfig(
229
+ url="https://example.com/webhook",
230
+ min_level="ERROR",
231
+ )
232
+
233
+ log = yapl.setup_logging(webhook=webhook)
234
+ ```
235
+
236
+ Webhook work runs in the background so application threads do not intentionally wait for network I/O. Active webhook handlers reuse their HTTP client, and timeout/retry behavior is bounded.
237
+
238
+ ## Buffering
239
+
240
+ Buffering captures records during a block and then replays or discards them when the block exits.
241
+
242
+ ```python
243
+ from yapl.extensions.buffering import (
244
+ BufferedLogs,
245
+ BufferingConfig,
246
+ install_buffering,
247
+ )
248
+
249
+ install_buffering()
250
+
251
+ with BufferedLogs(BufferingConfig(flush_mode="ordered")):
252
+ log.info("preflight", phase="warmup")
253
+ log.warning("preflight_warning", stage=1)
254
+ ```
255
+
256
+ The default behavior flushes buffered records on success and on error. Configuration can be used to discard them instead when a block should remain silent.
257
+
258
+ ## Extended Levels
259
+
260
+ YAPL can register extra development levels:
261
+
262
+ ```python
263
+ import yapl
264
+
265
+ yapl.setup_logging(level_mode="extended")
266
+
267
+ log = yapl.get_logger(__name__)
268
+ log.trace("trace message")
269
+ log.dev("dev message")
270
+ ```
271
+
272
+ Built-in extended levels:
273
+
274
+ | Level | Value |
275
+ | --- | ---: |
276
+ | `TRACE` | 5 |
277
+ | `DEV` | 15 |
278
+
279
+ ## Stack Helpers
280
+
281
+ Callsite and tracing helpers live under `yapl.stack`.
282
+
283
+ ```python
284
+ from yapl import get_logger, setup_logging
285
+ from yapl.stack import FunctionCallTracer, get_callsite
286
+
287
+ setup_logging(level_mode="extended")
288
+ callsite = get_callsite()
289
+
290
+ tracer = FunctionCallTracer(get_logger(__name__))
291
+ tracer.enable_current_thread()
292
+ try:
293
+ run_complex_operation()
294
+ finally:
295
+ tracer.disable_current_thread()
296
+ ```
297
+
298
+ ## Guarantees and Non-Guarantees
299
+
300
+ In the default queued configuration, remote and sink I/O never runs on the caller thread, and queue insertion does not intentionally wait.
301
+
302
+ 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 possible configuration.
303
+
304
+ ### Guaranteed by default
305
+
306
+ - Queue-backed delivery has a bounded record count.
307
+ - Queue insertion uses non-blocking insertion under the default overflow policy.
308
+ - Formatting, file/console delivery, webhook payload work, HTTP, DNS, and retry waits happen on background workers.
309
+ - Webhook retry attempts and retry delays are bounded.
310
+ - Active webhook handlers reuse a lazily created HTTP client.
311
+ - Shutdown waiting is bounded by `shutdown_timeout_seconds`.
312
+ - Records may be discarded when the shutdown deadline expires so the caller can continue.
313
+
314
+ ### Not guaranteed
315
+
316
+ - Delivery of every record during overload, remote failure, or shutdown.
317
+ - A fixed byte-level memory limit.
318
+ - Termination of arbitrary custom handlers already blocked forever.
319
+
320
+ Python cannot safely terminate arbitrary user handler code. Keep custom handlers non-blocking or give them their own timeouts.
321
+
322
+ ### Explicit opt-outs
323
+
324
+ `overflow_policy="block"` deliberately enables application-level backpressure and may block the caller. With `enqueue_timeout_seconds=None`, that wait may be indefinite.
325
+
326
+ `queue_enabled=False` runs normal stdlib handlers directly, so file, console, or custom sink work may occur on the caller thread.
327
+
328
+ ## Optional Modules
329
+
330
+ YAPL keeps concrete optional features under explicit modules:
331
+
332
+ ```python
333
+ from yapl.stack import FunctionCallTracer, get_callsite
334
+ from yapl.extensions.buffering import BufferedLogs, BufferingConfig
335
+ from yapl.extensions.coloring import install_color_structured_console
336
+ from yapl.extensions.formatting import JSONFormatter, StructuredFormatterConfig
337
+ from yapl.extensions.queueing import QueueingConfig
338
+ from yapl.extensions.webhook import WebhookConfig
339
+ ```
340
+
341
+ The `yapl.extensions` package is a namespace; concrete features live in its submodules.
342
+
343
+ ## Package Philosophy
344
+
345
+ YAPL is intended to be a small quality-of-life logging toolkit rather than a replacement observability framework.
346
+
347
+ The focus is on:
348
+
349
+ - predictable behavior
350
+ - low caller-side overhead
351
+ - bounded background work
352
+ - readable configuration
353
+ - stdlib compatibility
354
+ - optional features without unnecessary runtime weight