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.
- yapl_kit-0.2.0/PKG-INFO +368 -0
- yapl_kit-0.2.0/PUBLIC.md +354 -0
- yapl_kit-0.2.0/pyproject.toml +79 -0
- yapl_kit-0.2.0/pyproject.toml.orig +80 -0
- {yapl_kit-0.1.0 → yapl_kit-0.2.0}/src/yapl/__init__.py +19 -9
- {yapl_kit-0.1.0 → yapl_kit-0.2.0}/src/yapl/config.py +80 -1
- yapl_kit-0.2.0/src/yapl/context.py +64 -0
- {yapl_kit-0.1.0 → yapl_kit-0.2.0}/src/yapl/extensions/buffering/__init__.py +0 -2
- {yapl_kit-0.1.0 → yapl_kit-0.2.0}/src/yapl/extensions/buffering/capture.py +66 -66
- {yapl_kit-0.1.0 → yapl_kit-0.2.0}/src/yapl/extensions/buffering/flush.py +71 -71
- {yapl_kit-0.1.0 → yapl_kit-0.2.0}/src/yapl/extensions/buffering/models.py +65 -65
- {yapl_kit-0.1.0 → yapl_kit-0.2.0}/src/yapl/extensions/coloring/__init__.py +0 -2
- {yapl_kit-0.1.0 → yapl_kit-0.2.0}/src/yapl/extensions/coloring/colors.py +86 -86
- {yapl_kit-0.1.0 → yapl_kit-0.2.0}/src/yapl/extensions/coloring/models.py +121 -121
- {yapl_kit-0.1.0 → yapl_kit-0.2.0}/src/yapl/extensions/coloring/plain.py +113 -113
- {yapl_kit-0.1.0 → yapl_kit-0.2.0}/src/yapl/extensions/coloring/registry.py +119 -119
- {yapl_kit-0.1.0 → yapl_kit-0.2.0}/src/yapl/extensions/coloring/structured.py +100 -100
- {yapl_kit-0.1.0 → yapl_kit-0.2.0}/src/yapl/extensions/coloring/themes.py +111 -111
- {yapl_kit-0.1.0 → yapl_kit-0.2.0}/src/yapl/extensions/formatting/__init__.py +0 -2
- {yapl_kit-0.1.0 → yapl_kit-0.2.0}/src/yapl/extensions/formatting/_types.py +21 -21
- {yapl_kit-0.1.0 → yapl_kit-0.2.0}/src/yapl/extensions/formatting/plain.py +103 -103
- {yapl_kit-0.1.0 → yapl_kit-0.2.0}/src/yapl/extensions/formatting/structured.py +651 -656
- {yapl_kit-0.1.0 → yapl_kit-0.2.0}/src/yapl/extensions/queueing/__init__.py +0 -2
- {yapl_kit-0.1.0 → yapl_kit-0.2.0}/src/yapl/extensions/queueing/handler.py +92 -28
- {yapl_kit-0.1.0 → yapl_kit-0.2.0}/src/yapl/extensions/queueing/models.py +129 -126
- {yapl_kit-0.1.0 → yapl_kit-0.2.0}/src/yapl/extensions/queueing/policy.py +0 -6
- {yapl_kit-0.1.0 → yapl_kit-0.2.0}/src/yapl/extensions/queueing/worker.py +4 -10
- {yapl_kit-0.1.0 → yapl_kit-0.2.0}/src/yapl/extensions/webhook/__init__.py +0 -2
- {yapl_kit-0.1.0 → yapl_kit-0.2.0}/src/yapl/extensions/webhook/client.py +22 -4
- {yapl_kit-0.1.0 → yapl_kit-0.2.0}/src/yapl/extensions/webhook/handler.py +12 -5
- {yapl_kit-0.1.0 → yapl_kit-0.2.0}/src/yapl/extensions/webhook/models.py +217 -210
- {yapl_kit-0.1.0 → yapl_kit-0.2.0}/src/yapl/extensions/webhook/payloads.py +67 -15
- {yapl_kit-0.1.0 → yapl_kit-0.2.0}/src/yapl/factory.py +248 -41
- {yapl_kit-0.1.0 → yapl_kit-0.2.0}/src/yapl/filters/__init__.py +0 -2
- {yapl_kit-0.1.0 → yapl_kit-0.2.0}/src/yapl/filters/enrichment.py +116 -116
- {yapl_kit-0.1.0 → yapl_kit-0.2.0}/src/yapl/filters/suppression.py +69 -69
- {yapl_kit-0.1.0 → yapl_kit-0.2.0}/src/yapl/levels.py +134 -134
- {yapl_kit-0.1.0 → yapl_kit-0.2.0}/src/yapl/logger.py +21 -0
- {yapl_kit-0.1.0 → yapl_kit-0.2.0}/src/yapl/stack/__init__.py +0 -2
- {yapl_kit-0.1.0 → yapl_kit-0.2.0}/src/yapl/stack/callsite.py +75 -75
- {yapl_kit-0.1.0 → yapl_kit-0.2.0}/src/yapl/stack/tracer.py +157 -157
- yapl_kit-0.2.0/src/yapl/status.py +29 -0
- yapl_kit-0.2.0/src/yapl/testing.py +42 -0
- {yapl_kit-0.1.0 → yapl_kit-0.2.0}/src/yapl/types.py +0 -6
- {yapl_kit-0.1.0 → yapl_kit-0.2.0}/src/yapl_kit/__init__.py +2 -2
- yapl_kit-0.1.0/PKG-INFO +0 -345
- yapl_kit-0.1.0/README.md +0 -331
- yapl_kit-0.1.0/pyproject.toml +0 -37
- yapl_kit-0.1.0/pyproject.toml.orig +0 -36
- {yapl_kit-0.1.0 → yapl_kit-0.2.0}/src/yapl/extensions/buffering/context.py +0 -0
- {yapl_kit-0.1.0 → yapl_kit-0.2.0}/src/yapl/extensions/coloring/policy.py +0 -0
- {yapl_kit-0.1.0 → yapl_kit-0.2.0}/src/yapl/extensions/coloring/text.py +0 -0
- {yapl_kit-0.1.0 → yapl_kit-0.2.0}/src/yapl/extensions/formatting/_helpers.py +0 -0
- {yapl_kit-0.1.0 → yapl_kit-0.2.0}/src/yapl/extensions/formatting/formatters.py +0 -0
- {yapl_kit-0.1.0 → yapl_kit-0.2.0}/src/yapl/extensions/formatting/json.py +0 -0
- {yapl_kit-0.1.0 → yapl_kit-0.2.0}/src/yapl/extensions/formatting/logfmt.py +0 -0
- {yapl_kit-0.1.0 → yapl_kit-0.2.0}/src/yapl/extensions/formatting/processors.py +0 -0
- {yapl_kit-0.1.0 → yapl_kit-0.2.0}/src/yapl/extensions/formatting/text.py +0 -0
- {yapl_kit-0.1.0 → yapl_kit-0.2.0}/src/yapl/extensions/queueing/queue.py +0 -0
- {yapl_kit-0.1.0 → yapl_kit-0.2.0}/src/yapl/py.typed +0 -0
- {yapl_kit-0.1.0 → yapl_kit-0.2.0}/src/yapl_kit/py.typed +0 -0
yapl_kit-0.2.0/PKG-INFO
ADDED
|
@@ -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
|
yapl_kit-0.2.0/PUBLIC.md
ADDED
|
@@ -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
|