Peng Ding commited on
Commit
08c34fe
·
1 Parent(s): a6d9249

chore: remove 8 unused vendor modules (368K → 184K)

Browse files

Remove config, dotenv, yaml, jsonx, markdown, structlog, useragent,
retry — none are imported by project code. Remaining: httpserver,
cache, s3, readability, soup.

src/veilrender/_vendor/config.py DELETED
@@ -1,723 +0,0 @@
1
- # /// zerodep
2
- # version = "0.3.1"
3
- # deps = ["dotenv", "yaml", "jsonx"]
4
- # tier = "subsystem"
5
- # category = "config"
6
- # note = "Install/update via: https://zerodep.readthedocs.io/en/latest/guide/cli/"
7
- # ///
8
-
9
- """Unified configuration loader — zero dependencies, stdlib only, Python 3.10+.
10
-
11
- Part of zerodep: https://github.com/Oaklight/zerodep
12
- Copyright (c) 2026 Peng Ding. MIT License.
13
-
14
- Drop-in replacement for python-decouple / dynaconf core functionality.
15
- Loads settings from environment variables, .env files, and config files
16
- (JSON, JSONC, YAML, TOML, INI) with type coercion and prefix support.
17
-
18
- Example::
19
-
20
- from config import config, setup
21
-
22
- # Auto-discovers .env, reads env vars
23
- setup(prefix="MYAPP_")
24
- debug = config("DEBUG", default=False, cast=bool)
25
- port = config("PORT", default=8000, cast=int)
26
- hosts = config("ALLOWED_HOSTS", cast=Csv())
27
-
28
- # Or use Config directly
29
- cfg = Config(config_path="settings.yaml", prefix="MYAPP_")
30
- db_host = cfg("DATABASE__HOST", default="localhost")
31
- """
32
-
33
- from __future__ import annotations
34
-
35
- import configparser
36
- import json
37
- import os
38
- import sys
39
- from pathlib import Path
40
- from typing import Any, Callable, Sequence
41
-
42
- __all__ = [
43
- # Sentinels
44
- "MISSING",
45
- # Exceptions
46
- "ConfigError",
47
- "UndefinedValueError",
48
- # Type coercion helpers
49
- "Csv",
50
- "Choices",
51
- # Main class
52
- "Config",
53
- # Module-level convenience
54
- "setup",
55
- "config",
56
- ]
57
-
58
-
59
- def _ensure_sibling_path(name: str) -> str:
60
- """Return the sibling module directory and prepend it to ``sys.path``."""
61
- sibling_dir = os.path.join(os.path.dirname(os.path.abspath(__file__)), "..", name)
62
- if sibling_dir not in sys.path:
63
- sys.path.insert(0, sibling_dir)
64
- return sibling_dir
65
-
66
-
67
- # ── Sibling module loaders (lazy) ───────────────────────────────────────────
68
-
69
-
70
- def _load_dotenv_helpers() -> tuple[Callable[..., Any], Callable[..., Any]]:
71
- """Load sibling ``dotenv`` helpers on demand."""
72
- _ensure_sibling_path("dotenv")
73
- sys.modules.pop("dotenv", None)
74
- try:
75
- from dotenv import dotenv_values, find_dotenv
76
- except ImportError as exc:
77
- raise ImportError(
78
- ".env loading requires the sibling dotenv module. "
79
- "Copy dotenv/dotenv.py into your project, "
80
- "or set dotenv_path=None to disable."
81
- ) from exc
82
- return dotenv_values, find_dotenv
83
-
84
-
85
- def _load_yaml_loader() -> Callable[[str], Any]:
86
- """Load the sibling ``yaml`` module's ``load`` function on demand."""
87
- _ensure_sibling_path("yaml")
88
- sys.modules.pop("yaml", None)
89
- try:
90
- from yaml import load as yaml_load
91
- except ImportError as exc:
92
- raise ImportError(
93
- "YAML config files require the sibling yaml module. "
94
- "Copy yaml/yaml.py into your project."
95
- ) from exc
96
- return yaml_load
97
-
98
-
99
- def _load_jsonx_loader() -> Callable[[str], Any] | None:
100
- """Load the sibling ``jsonx`` (or legacy ``jsonc``) module's loader.
101
-
102
- Returns the ``loads`` function if available, else ``None``.
103
- """
104
- # Try jsonx first (renamed from jsonc)
105
- _ensure_sibling_path("jsonx")
106
- sys.modules.pop("jsonx", None)
107
- try:
108
- from jsonx import loads as jsonx_loads
109
- except ImportError:
110
- # Fall back to legacy jsonc for backward compatibility
111
- _ensure_sibling_path("jsonc")
112
- sys.modules.pop("jsonc", None)
113
- try:
114
- from jsonc import loads as jsonx_loads
115
- except ImportError:
116
- return None
117
- return jsonx_loads
118
-
119
-
120
- # ── Stdlib tomllib (Python 3.11+) ───────────────────────────────────────────
121
-
122
- try:
123
- import tomllib # type: ignore[import-not-found]
124
-
125
- _HAS_TOML = True
126
- except ModuleNotFoundError:
127
- _HAS_TOML = False
128
-
129
- # ── Sentinels ───────────────────────────────────────────────────────────────
130
-
131
-
132
- class _Missing:
133
- """Sentinel for missing configuration values."""
134
-
135
- _instance: _Missing | None = None
136
-
137
- def __new__(cls) -> _Missing:
138
- if cls._instance is None:
139
- cls._instance = super().__new__(cls)
140
- return cls._instance
141
-
142
- def __repr__(self) -> str:
143
- return "MISSING"
144
-
145
- def __bool__(self) -> bool:
146
- return False
147
-
148
-
149
- MISSING = _Missing()
150
-
151
-
152
- class _Auto:
153
- """Sentinel indicating auto-discovery of .env files."""
154
-
155
- _instance: _Auto | None = None
156
-
157
- def __new__(cls) -> _Auto:
158
- if cls._instance is None:
159
- cls._instance = super().__new__(cls)
160
- return cls._instance
161
-
162
- def __repr__(self) -> str:
163
- return "AUTO"
164
-
165
-
166
- _AUTO = _Auto()
167
-
168
- # ── Sentinel for injection parameters ──────────────────────────────────────
169
-
170
-
171
- class _Unset:
172
- """Sentinel indicating 'use default sibling auto-discovery'."""
173
-
174
- _instance: _Unset | None = None
175
-
176
- def __new__(cls) -> _Unset:
177
- if cls._instance is None:
178
- cls._instance = super().__new__(cls)
179
- return cls._instance
180
-
181
- def __repr__(self) -> str:
182
- return "UNSET"
183
-
184
-
185
- _UNSET = _Unset()
186
-
187
- # ── Exceptions ──────────────────────────────────────────────────────────────
188
-
189
-
190
- class ConfigError(Exception):
191
- """Base exception for all config operations."""
192
-
193
-
194
- class UndefinedValueError(ConfigError):
195
- """Raised when a required configuration value is missing."""
196
-
197
-
198
- # ── Bool constants ──────────────────────────────────────────────────────────
199
-
200
- _TRUTHY = frozenset({"1", "true", "yes", "on", "t", "y"})
201
- _FALSY = frozenset({"0", "false", "no", "off", "f", "n", ""})
202
-
203
- # ── Type coercion helpers ───────────────────────────────────────────────────
204
-
205
-
206
- class Csv:
207
- """Parse comma-separated values with optional per-item casting.
208
-
209
- Example::
210
-
211
- Csv()("a, b, c") # ["a", "b", "c"]
212
- Csv(cast=int)("1,2,3") # [1, 2, 3]
213
- Csv(delimiter=";")("a;b") # ["a", "b"]
214
-
215
- Args:
216
- cast: Callable applied to each item after splitting.
217
- delimiter: String to split on.
218
- strip: Characters to strip from each item. Use ``" %s"`` to strip
219
- whitespace around the format-string placeholder (default).
220
- post_process: Callable applied to the final list (e.g. ``tuple``).
221
- """
222
-
223
- def __init__(
224
- self,
225
- cast: Callable[[str], Any] = str,
226
- delimiter: str = ",",
227
- strip: str = " %s",
228
- post_process: Callable[[list[Any]], Any] = list,
229
- ) -> None:
230
- self.cast = cast
231
- self.delimiter = delimiter
232
- self.strip = strip
233
- self.post_process = post_process
234
-
235
- def __call__(self, value: str) -> Any:
236
- if isinstance(value, (list, tuple)):
237
- return self.post_process([self.cast(item) for item in value])
238
- parts = str(value).split(self.delimiter)
239
- result = []
240
- for part in parts:
241
- item = part.strip(self.strip.replace("%s", "")) if self.strip else part
242
- if item or not self.strip:
243
- result.append(self.cast(item))
244
- return self.post_process(result)
245
-
246
-
247
- class Choices:
248
- """Validate that a value belongs to a fixed set.
249
-
250
- Example::
251
-
252
- Choices(["dev", "staging", "prod"])("dev") # "dev"
253
- Choices([1, 2, 3], cast=int)("2") # 2
254
-
255
- Args:
256
- choices: Allowed values (after casting).
257
- cast: Callable applied before validation.
258
- """
259
-
260
- def __init__(
261
- self,
262
- choices: Sequence[Any],
263
- cast: Callable[[str], Any] = str,
264
- ) -> None:
265
- self.choices = choices
266
- self.cast = cast
267
-
268
- def __call__(self, value: str) -> Any:
269
- casted = self.cast(value)
270
- if casted not in self.choices:
271
- raise ValueError(
272
- f"{casted!r} is not a valid choice. Allowed: {list(self.choices)}"
273
- )
274
- return casted
275
-
276
-
277
- # ── File loaders ────────────────────────────────────────────────────────────
278
-
279
-
280
- def _load_json_file(path: str | os.PathLike[str]) -> dict[str, Any]:
281
- """Load a JSON file and return a dict."""
282
- with open(path, encoding="utf-8") as f:
283
- data = json.load(f)
284
- if not isinstance(data, dict):
285
- raise ValueError(f"JSON config must be an object, got {type(data).__name__}")
286
- return data
287
-
288
-
289
- def _load_jsonc_file(path: str | os.PathLike[str]) -> dict[str, Any]:
290
- """Load a JSONC file, falling back to plain JSON if jsonc module is unavailable."""
291
- with open(path, encoding="utf-8") as f:
292
- text = f.read()
293
- jsonc_loads = _load_jsonx_loader()
294
- if jsonc_loads is not None:
295
- data = jsonc_loads(text)
296
- else:
297
- data = json.loads(text)
298
- if not isinstance(data, dict):
299
- raise ValueError(f"JSONC config must be an object, got {type(data).__name__}")
300
- return data
301
-
302
-
303
- def _load_yaml_file(path: str | os.PathLike[str]) -> dict[str, Any]:
304
- """Load a YAML file using the sibling yaml module."""
305
- yaml_load = _load_yaml_loader()
306
- with open(path, encoding="utf-8") as f:
307
- text = f.read()
308
- data = yaml_load(text)
309
- if data is None:
310
- return {}
311
- if not isinstance(data, dict):
312
- raise ValueError(f"YAML config must be a mapping, got {type(data).__name__}")
313
- return data
314
-
315
-
316
- def _load_toml_file(path: str | os.PathLike[str]) -> dict[str, Any]:
317
- """Load a TOML file using stdlib tomllib (Python 3.11+)."""
318
- if not _HAS_TOML:
319
- raise ImportError("TOML config files require Python 3.11+ (tomllib).")
320
- with open(path, "rb") as f:
321
- return tomllib.load(f)
322
-
323
-
324
- def _load_ini_file(
325
- path: str | os.PathLike[str], separator: str = "__"
326
- ) -> dict[str, Any]:
327
- """Load an INI/CFG file and flatten sections into separator-joined keys.
328
-
329
- Example: ``[database]`` section with ``host = localhost`` becomes
330
- ``database__host = localhost`` (using the default separator).
331
- """
332
- parser = configparser.ConfigParser()
333
- parser.read(path, encoding="utf-8")
334
- data: dict[str, Any] = {}
335
- for section in parser.sections():
336
- for key, value in parser.items(section):
337
- flat_key = f"{section}{separator}{key}"
338
- data[flat_key] = value
339
- if parser.defaults():
340
- for key, value in parser.defaults().items():
341
- data[key] = value
342
- return data
343
-
344
-
345
- _LOADERS: dict[str, Callable[..., dict[str, Any]]] = {
346
- ".json": _load_json_file,
347
- ".jsonc": _load_jsonc_file,
348
- ".yaml": _load_yaml_file,
349
- ".yml": _load_yaml_file,
350
- ".toml": _load_toml_file,
351
- ".ini": _load_ini_file,
352
- ".cfg": _load_ini_file,
353
- }
354
-
355
- # ── Internal helpers ────────────────────────────────────────────────────────
356
-
357
-
358
- def _cast_bool(value: Any) -> bool:
359
- """Convert a value to bool using common truthy/falsy strings."""
360
- if isinstance(value, bool):
361
- return value
362
- s = str(value).lower().strip()
363
- if s in _TRUTHY:
364
- return True
365
- if s in _FALSY:
366
- return False
367
- raise ValueError(
368
- f"Cannot convert {value!r} to bool. Use one of: {sorted(_TRUTHY | _FALSY)}"
369
- )
370
-
371
-
372
- def _cast_list(value: Any) -> list[Any]:
373
- """Convert a value to list: try JSON array first, then comma-split."""
374
- if isinstance(value, list):
375
- return value
376
- if isinstance(value, tuple):
377
- return list(value)
378
- s = str(value).strip()
379
- if s.startswith("["):
380
- try:
381
- result = json.loads(s)
382
- if isinstance(result, list):
383
- return result
384
- except (json.JSONDecodeError, ValueError):
385
- pass
386
- return [item.strip() for item in s.split(",") if item.strip()]
387
-
388
-
389
- def _cast_tuple(value: Any) -> tuple[Any, ...]:
390
- """Convert a value to tuple via _cast_list."""
391
- return tuple(_cast_list(value))
392
-
393
-
394
- def _apply_cast(value: Any, cast: type | Callable[..., Any] | None) -> Any:
395
- """Apply a type cast to a value."""
396
- if cast is None:
397
- return value
398
- if cast is bool:
399
- return _cast_bool(value)
400
- if cast is list:
401
- return _cast_list(value)
402
- if cast is tuple:
403
- return _cast_tuple(value)
404
- return cast(value)
405
-
406
-
407
- def _deep_get(data: dict[str, Any], parts: list[str]) -> Any:
408
- """Retrieve a nested value from a dict using a list of key parts.
409
-
410
- Returns *MISSING* if any intermediate key is missing or not a dict.
411
- """
412
- current: Any = data
413
- for part in parts:
414
- if not isinstance(current, dict):
415
- return MISSING
416
- # Try exact key first, then case-insensitive
417
- if part in current:
418
- current = current[part]
419
- else:
420
- lower = part.lower()
421
- found = False
422
- for k in current:
423
- if k.lower() == lower:
424
- current = current[k]
425
- found = True
426
- break
427
- if not found:
428
- return MISSING
429
- return current
430
-
431
-
432
- def _flatten_dict(
433
- data: dict[str, Any], separator: str = "__", prefix: str = ""
434
- ) -> dict[str, Any]:
435
- """Flatten a nested dict into separator-joined keys."""
436
- result: dict[str, Any] = {}
437
- for key, value in data.items():
438
- full_key = f"{prefix}{separator}{key}" if prefix else key
439
- if isinstance(value, dict):
440
- result.update(_flatten_dict(value, separator, full_key))
441
- else:
442
- result[full_key] = value
443
- return result
444
-
445
-
446
- # ── Main Config class ───────────────────────────────────────────────────────
447
-
448
-
449
- class Config:
450
- """Unified configuration loader with multi-source support.
451
-
452
- Sources are checked in priority order (highest first):
453
-
454
- 1. Environment variables (``os.environ``), optionally prefixed
455
- 2. ``.env`` file values (via sibling dotenv module)
456
- 3. Config file values (JSON, JSONC, YAML, TOML, INI)
457
- 4. Default value passed to ``get()``/``__call__()``
458
-
459
- Args:
460
- dotenv_path: Path to ``.env`` file. Use ``None`` to disable,
461
- or omit (default ``_AUTO``) to auto-discover by searching
462
- upward from the current directory.
463
- config_path: Path to a config file. Format is detected from the
464
- file extension.
465
- prefix: Prefix for environment variable lookups. For example,
466
- ``prefix="MYAPP_"`` means looking up ``"PORT"`` checks
467
- ``os.environ["MYAPP_PORT"]``.
468
- separator: Separator for nested key access. Default ``"__"``
469
- means ``"DATABASE__HOST"`` resolves to ``data["DATABASE"]["HOST"]``
470
- or ``data["database"]["host"]`` in config files.
471
- loaders: Override the file-format loader registry. Defaults to
472
- ``_UNSET`` (use built-in loaders with sibling auto-discovery
473
- for yaml/jsonc). Pass a ``dict`` mapping extensions (e.g.
474
- ``".yaml"``) to loader callables to replace the defaults.
475
- Stdlib loaders (json, toml, ini) are always available unless
476
- explicitly overridden.
477
- dotenv_loader: Override the dotenv loading mechanism. Defaults to
478
- ``_UNSET`` (auto-discover sibling ``dotenv`` module). Pass
479
- ``None`` to disable .env loading entirely, or a callable that
480
- returns ``(dotenv_values_fn, find_dotenv_fn)`` to inject a
481
- custom implementation.
482
-
483
- Example::
484
-
485
- cfg = Config(config_path="settings.yaml", prefix="MYAPP_")
486
- debug = cfg("DEBUG", default=False, cast=bool)
487
- db_host = cfg("DATABASE__HOST", default="localhost")
488
- """
489
-
490
- def __init__(
491
- self,
492
- *,
493
- dotenv_path: str | os.PathLike[str] | None | _Auto = _AUTO,
494
- config_path: str | os.PathLike[str] | None = None,
495
- prefix: str = "",
496
- separator: str = "__",
497
- loaders: dict[str, Callable[..., dict[str, Any]]] | None | _Unset = _UNSET,
498
- dotenv_loader: Callable[[], tuple[Callable[..., Any], Callable[..., Any]]]
499
- | None
500
- | _Unset = _UNSET,
501
- ) -> None:
502
- self._prefix = prefix
503
- self._separator = separator
504
- self._dotenv_data: dict[str, str | None] = {}
505
- self._config_data: dict[str, Any] = {}
506
- self._loaders: dict[str, Callable[..., dict[str, Any]]]
507
-
508
- # Resolve loader registry
509
- if isinstance(loaders, _Unset):
510
- self._loaders = _LOADERS
511
- elif loaders is None:
512
- self._loaders = {}
513
- else:
514
- self._loaders = loaders
515
-
516
- # Load .env file
517
- if dotenv_loader is None:
518
- pass # .env explicitly disabled
519
- elif isinstance(dotenv_path, _Auto):
520
- try:
521
- if isinstance(dotenv_loader, _Unset):
522
- dotenv_values, find_dotenv = _load_dotenv_helpers()
523
- else:
524
- dotenv_values, find_dotenv = dotenv_loader()
525
- except ImportError:
526
- pass
527
- else:
528
- found = find_dotenv(usecwd=True)
529
- if found:
530
- self._dotenv_data = dotenv_values(found)
531
- elif dotenv_path is not None:
532
- if isinstance(dotenv_loader, _Unset):
533
- dotenv_values, _find_dotenv = _load_dotenv_helpers()
534
- else:
535
- dotenv_values, _find_dotenv = dotenv_loader()
536
- self._dotenv_data = dotenv_values(str(dotenv_path))
537
-
538
- # Load config file
539
- if config_path is not None:
540
- self._load_config_file(config_path)
541
-
542
- def _load_config_file(self, path: str | os.PathLike[str]) -> None:
543
- """Load a config file based on its extension."""
544
- p = Path(path)
545
- ext = p.suffix.lower()
546
- loader = self._loaders.get(ext)
547
- if loader is None:
548
- raise ValueError(
549
- f"Unsupported config file format: {ext!r}. "
550
- f"Supported: {', '.join(sorted(self._loaders))}"
551
- )
552
- if loader in (_load_ini_file,):
553
- self._config_data = loader(p, separator=self._separator)
554
- else:
555
- self._config_data = loader(p)
556
-
557
- def _lookup(self, key: str) -> Any:
558
- """Look up a key across all sources in priority order.
559
-
560
- Returns the value if found, or *MISSING* if not found anywhere.
561
- """
562
- # 1. Environment variables (with prefix)
563
- env_key = f"{self._prefix}{key}" if self._prefix else key
564
- env_val = os.environ.get(env_key)
565
- if env_val is not None:
566
- return env_val
567
-
568
- # 2. .env file values (with prefix)
569
- dotenv_val = self._dotenv_data.get(env_key)
570
- if dotenv_val is not None:
571
- return dotenv_val
572
-
573
- # 3. Config file values (exact key first, then nested lookup)
574
- if self._config_data:
575
- # Exact key match (e.g. INI-flattened keys)
576
- if key in self._config_data:
577
- return self._config_data[key]
578
- # Nested lookup via separator splitting
579
- if self._separator in key:
580
- parts = key.split(self._separator)
581
- result = _deep_get(self._config_data, parts)
582
- if result is not MISSING:
583
- return result
584
-
585
- return MISSING
586
-
587
- def get(
588
- self,
589
- key: str,
590
- *,
591
- default: Any = MISSING,
592
- cast: type | Callable[..., Any] | None = None,
593
- ) -> Any:
594
- """Retrieve a configuration value.
595
-
596
- Args:
597
- key: Configuration key to look up.
598
- default: Default value if key is not found. If not provided and
599
- the key is missing, ``UndefinedValueError`` is raised.
600
- cast: Type or callable to apply to the value. Built-in support
601
- for ``bool``, ``int``, ``float``, ``list``, ``tuple``.
602
- Also accepts ``Csv(...)`` and ``Choices(...)`` instances.
603
-
604
- Returns:
605
- The resolved and optionally cast configuration value.
606
-
607
- Raises:
608
- UndefinedValueError: If key is missing and no default is given.
609
- """
610
- value = self._lookup(key)
611
-
612
- if value is MISSING:
613
- if default is MISSING:
614
- raise UndefinedValueError(
615
- f"{key!r} is not set and has no default value."
616
- )
617
- value = default
618
-
619
- return _apply_cast(value, cast)
620
-
621
- def __call__(
622
- self,
623
- key: str,
624
- *,
625
- default: Any = MISSING,
626
- cast: type | Callable[..., Any] | None = None,
627
- ) -> Any:
628
- """Shorthand for ``get()``. See :meth:`get` for details."""
629
- return self.get(key, default=default, cast=cast)
630
-
631
- def has(self, key: str) -> bool:
632
- """Check whether a key exists in any source."""
633
- return self._lookup(key) is not MISSING
634
-
635
- def as_dict(self) -> dict[str, Any]:
636
- """Return a merged view of all config sources (flattened).
637
-
638
- Lower-priority sources are merged first, so higher-priority
639
- sources overwrite them.
640
- """
641
- merged: dict[str, Any] = {}
642
- # 3. Config file (lowest priority)
643
- if self._config_data:
644
- merged.update(_flatten_dict(self._config_data, self._separator))
645
- # 2. .env file
646
- for k, v in self._dotenv_data.items():
647
- if v is not None:
648
- merged[k] = v
649
- # 1. Environment variables (only those matching prefix)
650
- if self._prefix:
651
- plen = len(self._prefix)
652
- for k, v in os.environ.items():
653
- if k.startswith(self._prefix):
654
- merged[k[plen:]] = v
655
- else:
656
- merged.update(os.environ)
657
- return merged
658
-
659
-
660
- # ── Module-level convenience ────────────────────────────────────────────────
661
-
662
- _default_config: Config | None = None
663
-
664
-
665
- def setup(
666
- *,
667
- dotenv_path: str | os.PathLike[str] | None | _Auto = _AUTO,
668
- config_path: str | os.PathLike[str] | None = None,
669
- prefix: str = "",
670
- separator: str = "__",
671
- ) -> Config:
672
- """Initialize the module-level :class:`Config` instance.
673
-
674
- Call this once at application startup to configure sources and prefix.
675
- Subsequent calls to :func:`config` will use this instance.
676
-
677
- Args:
678
- dotenv_path: Path to ``.env`` file, ``None`` to disable, or
679
- ``_AUTO`` (default) to auto-discover.
680
- config_path: Path to a config file (JSON/YAML/TOML/INI).
681
- prefix: Prefix for environment variable lookups.
682
- separator: Separator for nested key access.
683
-
684
- Returns:
685
- The newly created :class:`Config` instance.
686
- """
687
- global _default_config
688
- _default_config = Config(
689
- dotenv_path=dotenv_path,
690
- config_path=config_path,
691
- prefix=prefix,
692
- separator=separator,
693
- )
694
- return _default_config
695
-
696
-
697
- def config(
698
- key: str,
699
- *,
700
- default: Any = MISSING,
701
- cast: type | Callable[..., Any] | None = None,
702
- ) -> Any:
703
- """Look up a configuration value using the module-level instance.
704
-
705
- If :func:`setup` has not been called, a default :class:`Config` is
706
- created automatically (auto-discovers ``.env``, no config file,
707
- no prefix).
708
-
709
- Args:
710
- key: Configuration key.
711
- default: Fallback value if missing.
712
- cast: Type or callable to coerce the value.
713
-
714
- Returns:
715
- The resolved configuration value.
716
-
717
- Raises:
718
- UndefinedValueError: If key is missing and no default.
719
- """
720
- global _default_config
721
- if _default_config is None:
722
- _default_config = Config()
723
- return _default_config(key, default=default, cast=cast)
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
src/veilrender/_vendor/dotenv.py DELETED
@@ -1,514 +0,0 @@
1
- # /// zerodep
2
- # version = "0.3.1"
3
- # deps = []
4
- # tier = "simple"
5
- # category = "config"
6
- # note = "Install/update via `zerodep add dotenv`"
7
- # ///
8
-
9
- """.env file parser and loader — zero dependencies, stdlib only, Python 3.10+.
10
-
11
- Part of zerodep: https://github.com/Oaklight/zerodep
12
- Copyright (c) 2026 Peng Ding. MIT License.
13
-
14
- Drop-in replacement for python-dotenv core functionality.
15
-
16
- Example::
17
-
18
- load_dotenv() # load .env into os.environ
19
- values = dotenv_values(".env") # parse without modifying environ
20
- path = find_dotenv() # search up for .env file
21
- """
22
-
23
- from __future__ import annotations
24
-
25
- import inspect
26
- import os
27
- import re
28
- import sys
29
- from pathlib import Path
30
- from typing import IO, Iterator, Mapping
31
-
32
- __all__ = [
33
- "find_dotenv",
34
- "get_key",
35
- "set_key",
36
- "unset_key",
37
- "dotenv_values",
38
- "load_dotenv",
39
- ]
40
-
41
- # ── Constants / Regex ──────────────────────────────────────────────────────────
42
-
43
- _ESCAPE_MAP = {
44
- "\\": "\\",
45
- "'": "'",
46
- '"': '"',
47
- "n": "\n",
48
- "r": "\r",
49
- "t": "\t",
50
- "$": "$",
51
- " ": " ",
52
- }
53
-
54
- # Matches a single .env binding line. Groups:
55
- # key – variable name
56
- # sq – single-quoted value content
57
- # dq – double-quoted value content (may span multiple lines)
58
- # uq – unquoted value content
59
- _BINDING_RE = re.compile(
60
- r"""
61
- \A\s* # leading whitespace
62
- (?:export\s+)? # optional export prefix
63
- (?P<key>[A-Za-z_]\w*) # key (must start with letter or _)
64
- (?: # optional =value part
65
- \s*=\s* # equals sign
66
- (?:
67
- '(?P<sq>[^']*)' # single-quoted (no escapes)
68
- | "(?P<dq>(?:[^"\\]|\\.)*)" # double-quoted (with escapes)
69
- | (?P<uq>[^\#\r\n]*) # unquoted (up to # or EOL)
70
- )
71
- )? # entire =value is optional
72
- \s* # trailing whitespace
73
- (?:\#.*)? # optional inline comment
74
- \s*\Z # end
75
- """,
76
- re.VERBOSE,
77
- )
78
-
79
- _INTERPOLATE_RE = re.compile(
80
- r"""
81
- (?<!\\) # not preceded by backslash
82
- \$ # dollar sign
83
- (?:
84
- \{(?P<brace>[^}]*)\} # ${VAR} or ${VAR:-default}
85
- | (?P<name>[A-Za-z_]\w*) # $VAR
86
- )
87
- """,
88
- re.VERBOSE,
89
- )
90
-
91
-
92
- # ── Internal helpers ───────────────────────────────────────────────────────────
93
-
94
-
95
- def _unescape_double_quoted(s: str) -> str:
96
- """Process escape sequences in a double-quoted value."""
97
-
98
- def _replace(m: re.Match[str]) -> str:
99
- ch = m.group(1)
100
- return _ESCAPE_MAP.get(ch, "\\" + ch)
101
-
102
- return re.sub(r"\\(.)", _replace, s)
103
-
104
-
105
- def _interpolate(
106
- value: str,
107
- env: dict[str, str | None],
108
- os_environ: Mapping[str, str],
109
- ) -> str:
110
- """Expand $VAR and ${VAR} references in *value*.
111
-
112
- Resolution order: file-local *env*, then *os_environ*, then empty string.
113
- Supports ${VAR:-default} syntax.
114
- """
115
-
116
- def _replace(m: re.Match[str]) -> str:
117
- brace = m.group("brace")
118
- if brace is not None:
119
- # Handle ${VAR:-default}
120
- if ":-" in brace:
121
- name, default = brace.split(":-", 1)
122
- name = name.strip()
123
- val = env.get(name) if name in env else os_environ.get(name)
124
- return val if val is not None else default
125
- name = brace.strip()
126
- else:
127
- name = m.group("name")
128
- val = env.get(name) if name in env else os_environ.get(name)
129
- return val if val is not None else ""
130
-
131
- return _INTERPOLATE_RE.sub(_replace, value)
132
-
133
-
134
- def _find_unescaped_quote(text: str) -> int:
135
- """Return position of the first unescaped double-quote in *text*, or -1."""
136
- pos = 0
137
- while pos < len(text):
138
- if text[pos] == "\\" and pos + 1 < len(text):
139
- pos += 2
140
- continue
141
- if text[pos] == '"':
142
- return pos
143
- pos += 1
144
- return -1
145
-
146
-
147
- def _collect_multiline_value(
148
- lines: list[str], start_idx: int, first_fragment: str
149
- ) -> tuple[str, int]:
150
- """Accumulate continuation lines for a multiline double-quoted value.
151
-
152
- Args:
153
- lines: All lines of the .env content.
154
- start_idx: Index of the first continuation line to inspect.
155
- first_fragment: Text after the opening ``"`` on the first line.
156
-
157
- Returns:
158
- Tuple of (raw concatenated value, next line index to process).
159
- """
160
- parts = [first_fragment]
161
- i = start_idx
162
- while i < len(lines):
163
- next_line = lines[i]
164
- i += 1
165
- close_pos = _find_unescaped_quote(next_line)
166
- if close_pos >= 0:
167
- parts.append(next_line[:close_pos])
168
- break
169
- parts.append(next_line)
170
- return "".join(parts), i
171
-
172
-
173
- _MULTILINE_OPEN_RE = re.compile(
174
- r'\A\s*(?:export\s+)?([A-Za-z_]\w*)\s*=\s*"',
175
- )
176
-
177
-
178
- def _extract_value_from_match(m: re.Match[str]) -> str | None:
179
- """Extract the value from a single-line binding regex match.
180
-
181
- Returns the raw value (unescaped for double-quoted, literal for
182
- single-quoted, stripped for unquoted, or None when no ``=`` present).
183
- """
184
- if m.group("sq") is not None:
185
- return m.group("sq")
186
- if m.group("dq") is not None:
187
- return _unescape_double_quoted(m.group("dq"))
188
- if m.group("uq") is not None:
189
- return m.group("uq").rstrip()
190
- return None
191
-
192
-
193
- def _parse_stream(
194
- stream: IO[str],
195
- interpolate: bool = True,
196
- override: bool = False,
197
- os_environ: Mapping[str, str] | None = None,
198
- ) -> Iterator[tuple[str, str | None]]:
199
- """Parse an .env stream, yielding (key, value) tuples."""
200
- if os_environ is None:
201
- os_environ = os.environ
202
-
203
- env: dict[str, str | None] = {}
204
- content = stream.read()
205
-
206
- # Strip UTF-8 BOM
207
- if content.startswith("\ufeff"):
208
- content = content[1:]
209
-
210
- lines = content.splitlines(keepends=True)
211
- i = 0
212
-
213
- while i < len(lines):
214
- line = lines[i]
215
- stripped = line.strip()
216
- i += 1
217
-
218
- # Skip blank lines and comment-only lines
219
- if not stripped or stripped.startswith("#"):
220
- continue
221
-
222
- # Check for multiline double-quoted values
223
- ml_match = _MULTILINE_OPEN_RE.match(line)
224
- if ml_match:
225
- after_eq_quote = line[ml_match.end() :]
226
- if _find_unescaped_quote(after_eq_quote) < 0:
227
- # Multiline: accumulate lines until closing "
228
- key = ml_match.group(1)
229
- raw_value, i = _collect_multiline_value(lines, i, after_eq_quote)
230
- value = _unescape_double_quoted(raw_value)
231
- if interpolate:
232
- value = _interpolate(value, env, os_environ)
233
- env[key] = value
234
- yield key, value
235
- continue
236
-
237
- # Single-line binding
238
- m = _BINDING_RE.match(stripped)
239
- if m is None:
240
- continue
241
-
242
- key = m.group("key")
243
- value: str | None = _extract_value_from_match(m)
244
-
245
- if value is not None and interpolate:
246
- value = _interpolate(value, env, os_environ)
247
-
248
- env[key] = value
249
- yield key, value
250
-
251
-
252
- # ── File search ────────────────────────────────────────────────────────────────
253
-
254
-
255
- def find_dotenv(
256
- filename: str = ".env",
257
- raise_error_if_not_found: bool = False,
258
- usecwd: bool = False,
259
- ) -> str:
260
- """Walk up from the calling file's directory (or cwd) to find *filename*.
261
-
262
- Args:
263
- filename: Name of the file to search for.
264
- raise_error_if_not_found: Raise IOError if the file is not found.
265
- usecwd: Start from the current working directory instead of the
266
- calling file's directory.
267
-
268
- Returns:
269
- Absolute path to the found file, or empty string if not found.
270
- """
271
- if usecwd:
272
- start = Path.cwd()
273
- else:
274
- frame = inspect.currentframe()
275
- caller = frame.f_back if frame is not None else None
276
- if caller is not None and caller.f_globals.get("__file__"):
277
- start = Path(caller.f_globals["__file__"]).resolve().parent
278
- else:
279
- start = Path.cwd()
280
-
281
- current = start
282
- while True:
283
- candidate = current / filename
284
- if candidate.is_file():
285
- return str(candidate)
286
- parent = current.parent
287
- if parent == current:
288
- break
289
- current = parent
290
-
291
- if raise_error_if_not_found:
292
- raise IOError(f"File {filename!r} not found starting from {start}")
293
- return ""
294
-
295
-
296
- # ── File I/O (set / unset) ────────────────────────────────────────────────────
297
-
298
-
299
- def get_key(
300
- dotenv_path: str | os.PathLike[str],
301
- key_to_get: str,
302
- encoding: str = "utf-8",
303
- ) -> str | None:
304
- """Get a single value from a .env file.
305
-
306
- Args:
307
- dotenv_path: Path to the .env file.
308
- key_to_get: The key to retrieve.
309
- encoding: File encoding.
310
-
311
- Returns:
312
- The value for the key, or None if not found.
313
- """
314
- values = dotenv_values(dotenv_path, encoding=encoding)
315
- return values.get(key_to_get)
316
-
317
-
318
- def set_key(
319
- dotenv_path: str | os.PathLike[str],
320
- key_to_set: str,
321
- value_to_set: str,
322
- quote_mode: str = "always",
323
- export: bool = False,
324
- encoding: str = "utf-8",
325
- ) -> tuple[bool, str, str]:
326
- """Set a key=value pair in a .env file, creating it if needed.
327
-
328
- Args:
329
- dotenv_path: Path to the .env file.
330
- key_to_set: The key to set.
331
- value_to_set: The value to set.
332
- quote_mode: Quoting strategy: "always", "auto", or "never".
333
- export: Whether to prefix with ``export``.
334
- encoding: File encoding.
335
-
336
- Returns:
337
- Tuple of (success, key, value).
338
- """
339
- path = Path(dotenv_path)
340
-
341
- if quote_mode == "always":
342
- value_out = f'"{value_to_set}"'
343
- elif quote_mode == "never":
344
- value_out = value_to_set
345
- else:
346
- # auto: quote if value contains spaces or special chars
347
- if re.search(r"[\s#\"']", value_to_set):
348
- value_out = f'"{value_to_set}"'
349
- else:
350
- value_out = value_to_set
351
-
352
- export_prefix = "export " if export else ""
353
- new_line = f"{export_prefix}{key_to_set}={value_out}\n"
354
-
355
- if path.is_file():
356
- lines = path.read_text(encoding=encoding).splitlines(keepends=True)
357
- replaced = False
358
- for idx, line in enumerate(lines):
359
- m = re.match(
360
- r"\A\s*(?:export\s+)?(" + re.escape(key_to_set) + r")\s*=",
361
- line,
362
- )
363
- if m:
364
- lines[idx] = new_line
365
- replaced = True
366
- break
367
- if not replaced:
368
- if lines and not lines[-1].endswith("\n"):
369
- lines[-1] += "\n"
370
- lines.append(new_line)
371
- path.write_text("".join(lines), encoding=encoding)
372
- else:
373
- path.parent.mkdir(parents=True, exist_ok=True)
374
- path.write_text(new_line, encoding=encoding)
375
-
376
- return True, key_to_set, value_to_set
377
-
378
-
379
- def unset_key(
380
- dotenv_path: str | os.PathLike[str],
381
- key_to_unset: str,
382
- quote_mode: str = "always",
383
- encoding: str = "utf-8",
384
- ) -> tuple[bool, str]:
385
- """Remove a key from a .env file.
386
-
387
- Args:
388
- dotenv_path: Path to the .env file.
389
- key_to_unset: The key to remove.
390
- quote_mode: Unused, kept for API compatibility.
391
- encoding: File encoding.
392
-
393
- Returns:
394
- Tuple of (success, key).
395
- """
396
- path = Path(dotenv_path)
397
- if not path.is_file():
398
- return True, key_to_unset
399
-
400
- lines = path.read_text(encoding=encoding).splitlines(keepends=True)
401
- new_lines = []
402
- for line in lines:
403
- m = re.match(
404
- r"\A\s*(?:export\s+)?(" + re.escape(key_to_unset) + r")\s*=",
405
- line,
406
- )
407
- if m:
408
- continue
409
- new_lines.append(line)
410
-
411
- path.write_text("".join(new_lines), encoding=encoding)
412
- return True, key_to_unset
413
-
414
-
415
- # ── Public API ─────────────────────────────────────────────────────────────────
416
-
417
-
418
- def _resolve_dotenv_path(
419
- dotenv_path: str | os.PathLike[str] | None,
420
- verbose: bool,
421
- ) -> Path | None:
422
- """Resolve *dotenv_path* to an existing file, or return None.
423
-
424
- When *verbose* is True and the file does not exist, a warning is printed.
425
- """
426
- if dotenv_path is None:
427
- dotenv_path = find_dotenv(usecwd=True)
428
-
429
- path = Path(dotenv_path)
430
- if path.is_file():
431
- return path
432
-
433
- if verbose:
434
- print( # noqa: T201
435
- f"Python-dotenv could not find configuration file {path}.",
436
- file=sys.stderr,
437
- )
438
- return None
439
-
440
-
441
- def _apply_to_environ(
442
- pairs: Iterator[tuple[str, str | None]],
443
- override: bool,
444
- ) -> None:
445
- """Write parsed (key, value) pairs into ``os.environ``."""
446
- for key, value in pairs:
447
- if value is not None and (override or key not in os.environ):
448
- os.environ[key] = value
449
-
450
-
451
- def dotenv_values(
452
- dotenv_path: str | os.PathLike[str] | None = None,
453
- stream: IO[str] | None = None,
454
- verbose: bool = False,
455
- interpolate: bool = True,
456
- override: bool = False,
457
- encoding: str = "utf-8",
458
- ) -> dict[str, str | None]:
459
- """Parse a .env file and return a dict without modifying ``os.environ``.
460
-
461
- Args:
462
- dotenv_path: Path to the .env file. If None, uses ``find_dotenv()``.
463
- stream: A text stream to read from (overrides *dotenv_path*).
464
- verbose: Print a warning when the file is missing.
465
- interpolate: Expand ``$VAR`` and ``${VAR}`` references.
466
- override: Unused for dotenv_values (kept for API compatibility).
467
- encoding: File encoding.
468
-
469
- Returns:
470
- Dictionary mapping variable names to their values.
471
- """
472
- if stream is not None:
473
- return dict(_parse_stream(stream, interpolate=interpolate))
474
-
475
- path = _resolve_dotenv_path(dotenv_path, verbose)
476
- if path is None:
477
- return {}
478
-
479
- with open(path, encoding=encoding) as f:
480
- return dict(_parse_stream(f, interpolate=interpolate))
481
-
482
-
483
- def load_dotenv(
484
- dotenv_path: str | os.PathLike[str] | None = None,
485
- stream: IO[str] | None = None,
486
- verbose: bool = False,
487
- interpolate: bool = True,
488
- override: bool = False,
489
- encoding: str = "utf-8",
490
- ) -> bool:
491
- """Read a .env file and set ``os.environ``.
492
-
493
- Args:
494
- dotenv_path: Path to the .env file. If None, uses ``find_dotenv()``.
495
- stream: A text stream to read from (overrides *dotenv_path*).
496
- verbose: Print a warning when the file is missing.
497
- interpolate: Expand ``$VAR`` and ``${VAR}`` references.
498
- override: If True, overwrite existing environment variables.
499
- encoding: File encoding.
500
-
501
- Returns:
502
- True if a file was found and loaded.
503
- """
504
- if stream is not None:
505
- _apply_to_environ(_parse_stream(stream, interpolate=interpolate), override)
506
- return True
507
-
508
- path = _resolve_dotenv_path(dotenv_path, verbose)
509
- if path is None:
510
- return False
511
-
512
- with open(path, encoding=encoding) as f:
513
- _apply_to_environ(_parse_stream(f, interpolate=interpolate), override)
514
- return True
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
src/veilrender/_vendor/jsonx.py DELETED
@@ -1,476 +0,0 @@
1
- # /// zerodep
2
- # version = "1.0.0"
3
- # deps = []
4
- # tier = "simple"
5
- # category = "serialization"
6
- # note = "Install/update via `zerodep add jsonx`"
7
- # ///
8
-
9
- """Extended JSON parser — zero dependencies, stdlib only, Python 3.10+.
10
-
11
- Part of zerodep: https://github.com/Oaklight/zerodep
12
- Copyright (c) 2026 Peng Ding. MIT License.
13
-
14
- Drop-in replacement for commentjson / stdlib json with JSONC support,
15
- plus JSONL (JSON Lines) helpers.
16
-
17
- Supports:
18
- - Single-line comments: ``//`` and ``#``
19
- - Block comments: ``/* ... */``
20
- - Trailing commas in objects and arrays
21
- - All standard JSON types
22
- - JSONL (one JSON value per line, with optional comments)
23
-
24
- Example::
25
-
26
- loads('{"a": 1, // comment\n"b": 2}')
27
- # {'a': 1, 'b': 2}
28
- load(open("config.jsonc"))
29
- # {...}
30
-
31
- # JSONL with comments
32
- loads_lines('{"a":1}\n// skip\n{"b":2}')
33
- # [{'a': 1}, {'b': 2}]
34
- """
35
-
36
- from __future__ import annotations
37
-
38
- import json
39
- import re
40
- from typing import IO, Any
41
-
42
- __all__ = [
43
- "JSONCDecodeError",
44
- "loads",
45
- "load",
46
- "dumps",
47
- "dump",
48
- "loads_lines",
49
- "load_lines",
50
- "dumps_lines",
51
- "dump_lines",
52
- ]
53
-
54
- # ── Comment stripping ─────────────────────────────────────────────────────────
55
-
56
- # Matches (in priority order):
57
- # 1. Double-quoted strings (group 1) — preserved as-is
58
- # 2. Single-line // comments — removed
59
- # 3. Single-line # comments — removed
60
- # 4. Block /* ... */ comments — removed
61
- _COMMENT_RE = re.compile(
62
- r"""
63
- ( "(?:[^"\\]|\\.)*" ) # group 1: double-quoted string (keep)
64
- | //[^\n]* # single-line // comment
65
- | \#[^\n]* # single-line # comment
66
- | /\*[\s\S]*?\*/ # block /* */ comment
67
- """,
68
- re.VERBOSE | re.MULTILINE,
69
- )
70
-
71
- # Trailing comma before closing ] or }
72
- _TRAILING_COMMA_RE = re.compile(
73
- r"""
74
- ( "(?:[^"\\]|\\.)*" ) # group 1: double-quoted string (keep)
75
- | ,\s*(?=[}\]]) # comma followed by optional whitespace then } or ]
76
- """,
77
- re.VERBOSE,
78
- )
79
-
80
-
81
- def _strip_comments(text: str) -> str:
82
- """Remove ``//``, ``#``, and ``/* */`` comments, preserving strings."""
83
-
84
- def _replace(m: re.Match[str]) -> str:
85
- if m.group(1) is not None:
86
- return m.group(1)
87
- return ""
88
-
89
- return _COMMENT_RE.sub(_replace, text)
90
-
91
-
92
- def _strip_trailing_commas(text: str) -> str:
93
- """Remove trailing commas before ``}`` and ``]``, preserving strings."""
94
-
95
- def _replace(m: re.Match[str]) -> str:
96
- if m.group(1) is not None:
97
- return m.group(1)
98
- return ""
99
-
100
- return _TRAILING_COMMA_RE.sub(_replace, text)
101
-
102
-
103
- def _preprocess(text: str) -> str:
104
- """Strip comments and trailing commas from JSONC text."""
105
- text = _strip_comments(text)
106
- text = _strip_trailing_commas(text)
107
- return text
108
-
109
-
110
- # ── Line-number error mapping ────────────────────────────────────────────────
111
-
112
-
113
- def _remap_error_position(
114
- original: str, cleaned: str, clean_pos: int
115
- ) -> tuple[int, int]:
116
- """Map a character offset in *cleaned* text back to *original* line/col.
117
-
118
- Returns (line, column), both 1-based.
119
- """
120
- # Build a mapping from cleaned-offset → original-offset by replaying the
121
- # comment-stripping regex. Each matched region in the original either maps
122
- # 1:1 (strings) or collapses to zero length (comments).
123
- orig_idx = 0
124
- clean_idx = 0
125
- mapping: list[tuple[int, int, int]] = [] # (clean_start, clean_end, orig_start)
126
-
127
- for m in _COMMENT_RE.finditer(original):
128
- # Characters before this match map 1:1
129
- pre_len = m.start() - orig_idx
130
- if pre_len > 0:
131
- mapping.append((clean_idx, clean_idx + pre_len, orig_idx))
132
- clean_idx += pre_len
133
- orig_idx = m.start()
134
-
135
- if m.group(1) is not None:
136
- # Preserved string — maps 1:1
137
- span_len = m.end() - m.start()
138
- mapping.append((clean_idx, clean_idx + span_len, orig_idx))
139
- clean_idx += span_len
140
- # else: comment — removed, clean_idx doesn't advance
141
-
142
- orig_idx = m.end()
143
-
144
- # Tail after last match
145
- tail_len = len(original) - orig_idx
146
- if tail_len > 0:
147
- mapping.append((clean_idx, clean_idx + tail_len, orig_idx))
148
-
149
- # Look up clean_pos in the mapping
150
- orig_offset = clean_pos # fallback
151
- for cs, ce, os_ in mapping:
152
- if cs <= clean_pos < ce:
153
- orig_offset = os_ + (clean_pos - cs)
154
- break
155
- if clean_pos < cs:
156
- orig_offset = os_
157
- break
158
-
159
- # Convert original offset to line/col
160
- line = original[:orig_offset].count("\n") + 1
161
- last_nl = original.rfind("\n", 0, orig_offset)
162
- col = orig_offset - last_nl # 1-based
163
- return line, col
164
-
165
-
166
- class JSONCDecodeError(json.JSONDecodeError):
167
- """Error raised when JSONC parsing fails.
168
-
169
- Provides line and column numbers relative to the original JSONC source
170
- (before comment/trailing-comma stripping).
171
- """
172
-
173
-
174
- # ── Public API ────────────────────────────────────────────────────────────────
175
-
176
-
177
- def loads(
178
- text: str,
179
- *,
180
- cls: type[json.JSONDecoder] | None = None,
181
- object_hook: Any = None,
182
- parse_float: Any = None,
183
- parse_int: Any = None,
184
- parse_constant: Any = None,
185
- object_pairs_hook: Any = None,
186
- **kwargs: Any,
187
- ) -> Any:
188
- """Deserialize a JSONC string to a Python object.
189
-
190
- Strips ``//``, ``#``, and ``/* */`` comments and trailing commas before
191
- delegating to :func:`json.loads`.
192
-
193
- Args:
194
- text: JSONC source string.
195
- cls: Custom JSON decoder class.
196
- object_hook: Called with the result of any object literal decoded.
197
- parse_float: Called with every JSON float string decoded.
198
- parse_int: Called with every JSON int string decoded.
199
- parse_constant: Called with ``-Infinity``, ``Infinity``, ``NaN``.
200
- object_pairs_hook: Called with an ordered list of pairs.
201
- **kwargs: Additional keyword arguments passed to :func:`json.loads`.
202
-
203
- Returns:
204
- Deserialized Python object.
205
-
206
- Raises:
207
- JSONCDecodeError: If the text is not valid JSONC.
208
- """
209
- cleaned = _preprocess(text)
210
- try:
211
- return json.loads(
212
- cleaned,
213
- cls=cls,
214
- object_hook=object_hook,
215
- parse_float=parse_float,
216
- parse_int=parse_int,
217
- parse_constant=parse_constant,
218
- object_pairs_hook=object_pairs_hook,
219
- **kwargs,
220
- )
221
- except json.JSONDecodeError as exc:
222
- line, col = _remap_error_position(text, cleaned, exc.pos)
223
- raise JSONCDecodeError(exc.msg, text, exc.pos) from None
224
-
225
-
226
- def load(
227
- fp: IO[str],
228
- *,
229
- cls: type[json.JSONDecoder] | None = None,
230
- object_hook: Any = None,
231
- parse_float: Any = None,
232
- parse_int: Any = None,
233
- parse_constant: Any = None,
234
- object_pairs_hook: Any = None,
235
- **kwargs: Any,
236
- ) -> Any:
237
- """Deserialize a JSONC file to a Python object.
238
-
239
- Args:
240
- fp: A text file-like object containing JSONC.
241
- cls: Custom JSON decoder class.
242
- object_hook: Called with the result of any object literal decoded.
243
- parse_float: Called with every JSON float string decoded.
244
- parse_int: Called with every JSON int string decoded.
245
- parse_constant: Called with ``-Infinity``, ``Infinity``, ``NaN``.
246
- object_pairs_hook: Called with an ordered list of pairs.
247
- **kwargs: Additional keyword arguments passed to :func:`json.loads`.
248
-
249
- Returns:
250
- Deserialized Python object.
251
-
252
- Raises:
253
- JSONCDecodeError: If the content is not valid JSONC.
254
- """
255
- return loads(
256
- fp.read(),
257
- cls=cls,
258
- object_hook=object_hook,
259
- parse_float=parse_float,
260
- parse_int=parse_int,
261
- parse_constant=parse_constant,
262
- object_pairs_hook=object_pairs_hook,
263
- **kwargs,
264
- )
265
-
266
-
267
- def dumps(
268
- obj: Any,
269
- *,
270
- skipkeys: bool = False,
271
- ensure_ascii: bool = True,
272
- check_circular: bool = True,
273
- allow_nan: bool = True,
274
- cls: type[json.JSONEncoder] | None = None,
275
- indent: int | str | None = None,
276
- separators: tuple[str, str] | None = None,
277
- default: Any = None,
278
- sort_keys: bool = False,
279
- **kwargs: Any,
280
- ) -> str:
281
- """Serialize a Python object to a JSON string.
282
-
283
- This is a pass-through to :func:`json.dumps` for API compatibility.
284
-
285
- Args:
286
- obj: Python object to serialize.
287
- skipkeys: Skip keys that are not basic types.
288
- ensure_ascii: Escape non-ASCII characters.
289
- check_circular: Check for circular references.
290
- allow_nan: Allow ``NaN``, ``Infinity``, ``-Infinity``.
291
- cls: Custom JSON encoder class.
292
- indent: Indentation level for pretty-printing.
293
- separators: Item and key separators.
294
- default: Called for objects that are not serializable.
295
- sort_keys: Sort dictionary keys.
296
- **kwargs: Additional keyword arguments passed to :func:`json.dumps`.
297
-
298
- Returns:
299
- JSON string.
300
- """
301
- return json.dumps(
302
- obj,
303
- skipkeys=skipkeys,
304
- ensure_ascii=ensure_ascii,
305
- check_circular=check_circular,
306
- allow_nan=allow_nan,
307
- cls=cls,
308
- indent=indent,
309
- separators=separators,
310
- default=default,
311
- sort_keys=sort_keys,
312
- **kwargs,
313
- )
314
-
315
-
316
- def dump(
317
- obj: Any,
318
- fp: IO[str],
319
- *,
320
- skipkeys: bool = False,
321
- ensure_ascii: bool = True,
322
- check_circular: bool = True,
323
- allow_nan: bool = True,
324
- cls: type[json.JSONEncoder] | None = None,
325
- indent: int | str | None = None,
326
- separators: tuple[str, str] | None = None,
327
- default: Any = None,
328
- sort_keys: bool = False,
329
- **kwargs: Any,
330
- ) -> None:
331
- """Serialize a Python object to a JSON file.
332
-
333
- This is a pass-through to :func:`json.dump` for API compatibility.
334
-
335
- Args:
336
- obj: Python object to serialize.
337
- fp: A text file-like object to write to.
338
- skipkeys: Skip keys that are not basic types.
339
- ensure_ascii: Escape non-ASCII characters.
340
- check_circular: Check for circular references.
341
- allow_nan: Allow ``NaN``, ``Infinity``, ``-Infinity``.
342
- cls: Custom JSON encoder class.
343
- indent: Indentation level for pretty-printing.
344
- separators: Item and key separators.
345
- default: Called for objects that are not serializable.
346
- sort_keys: Sort dictionary keys.
347
- **kwargs: Additional keyword arguments passed to :func:`json.dump`.
348
- """
349
- json.dump(
350
- obj,
351
- fp,
352
- skipkeys=skipkeys,
353
- ensure_ascii=ensure_ascii,
354
- check_circular=check_circular,
355
- allow_nan=allow_nan,
356
- cls=cls,
357
- indent=indent,
358
- separators=separators,
359
- default=default,
360
- sort_keys=sort_keys,
361
- **kwargs,
362
- )
363
-
364
-
365
- # ── JSONL (JSON Lines) API ────────────────────────────────────────────────────────────
366
-
367
- # JSONL = one JSON value per line. Each line is preprocessed through the
368
- # JSONC comment/trailing-comma stripper, so "JSONL with comments" works
369
- # out of the box.
370
-
371
-
372
- def _is_blank_or_comment(line: str) -> bool:
373
- """Return *True* if *line* is empty or a pure-comment line."""
374
- s = line.strip()
375
- return s == "" or s.startswith("//") or s.startswith("#")
376
-
377
-
378
- def loads_lines(
379
- text: str,
380
- **kwargs: Any,
381
- ) -> list[Any]:
382
- """Deserialize a JSONL string to a list of Python objects.
383
-
384
- Uses a batch fast-path for clean JSONL: non-empty lines are joined
385
- into a JSON array and parsed in a single :func:`json.loads` call,
386
- matching ``ndjson``-level performance. If that fails (comments,
387
- trailing commas, etc.), falls back to per-line JSONC processing.
388
-
389
- Args:
390
- text: JSONL source string (one JSON value per line).
391
- **kwargs: Keyword arguments forwarded to :func:`json.loads`
392
- (or :func:`loads` on fallback).
393
-
394
- Returns:
395
- List of deserialized Python objects.
396
-
397
- Raises:
398
- JSONCDecodeError: If any line contains invalid JSON/JSONC.
399
- """
400
- lines = text.split("\n")
401
- stripped = [ln for ln in lines if ln.strip()]
402
- if not stripped:
403
- return []
404
- # Fast path: join non-empty lines into a JSON array, single parse.
405
- # This avoids per-line Python overhead and lets the C json parser
406
- # handle everything in one call.
407
- _json_loads = json.loads
408
- try:
409
- return _json_loads("[" + ",".join(stripped) + "]", **kwargs)
410
- except json.JSONDecodeError:
411
- pass
412
- # Slow path: comments, trailing commas, or JSONC syntax present.
413
- results: list[Any] = []
414
- for line in lines:
415
- if _is_blank_or_comment(line):
416
- continue
417
- try:
418
- results.append(_json_loads(line, **kwargs))
419
- except json.JSONDecodeError:
420
- results.append(loads(line, **kwargs))
421
- return results
422
-
423
-
424
- def load_lines(
425
- fp: IO[str],
426
- **kwargs: Any,
427
- ) -> list[Any]:
428
- """Deserialize a JSONL file to a list of Python objects.
429
-
430
- Args:
431
- fp: A text file-like object containing JSONL.
432
- **kwargs: Keyword arguments forwarded to :func:`loads`.
433
-
434
- Returns:
435
- List of deserialized Python objects.
436
-
437
- Raises:
438
- JSONCDecodeError: If any line contains invalid JSON/JSONC.
439
- """
440
- return loads_lines(fp.read(), **kwargs)
441
-
442
-
443
- def dumps_lines(
444
- objects: list[Any],
445
- **kwargs: Any,
446
- ) -> str:
447
- """Serialize a list of Python objects to a JSONL string.
448
-
449
- Each object is serialized on its own line using :func:`json.dumps`.
450
- No trailing newline is emitted (consistent with ``"\\n".join(...)``
451
- semantics).
452
-
453
- Args:
454
- objects: Iterable of Python objects to serialize.
455
- **kwargs: Keyword arguments forwarded to :func:`json.dumps`.
456
-
457
- Returns:
458
- JSONL string (one JSON value per line).
459
- """
460
- return "\n".join(json.dumps(obj, **kwargs) for obj in objects)
461
-
462
-
463
- def dump_lines(
464
- objects: list[Any],
465
- fp: IO[str],
466
- **kwargs: Any,
467
- ) -> None:
468
- """Serialize a list of Python objects to a JSONL file.
469
-
470
- Args:
471
- objects: Iterable of Python objects to serialize.
472
- fp: A text file-like object to write to.
473
- **kwargs: Keyword arguments forwarded to :func:`json.dumps`.
474
- """
475
- fp.write(dumps_lines(objects, **kwargs))
476
- fp.write("\n")
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
src/veilrender/_vendor/markdown.py DELETED
@@ -1,904 +0,0 @@
1
- # /// zerodep
2
- # version = "0.4.1"
3
- # deps = []
4
- # tier = "medium"
5
- # category = "text"
6
- # note = "Install/update via `zerodep add markdown`"
7
- # ///
8
-
9
- """Markdown to HTML renderer — zero dependencies, stdlib only, Python 3.10+.
10
-
11
- Part of zerodep: https://github.com/Oaklight/zerodep
12
- Copyright (c) 2026 Peng Ding. MIT License.
13
-
14
- Drop-in replacement for mistune's ``mistune.html()`` for common Markdown.
15
-
16
- Supports:
17
- - ATX and Setext headings
18
- - Paragraphs, thematic breaks, hard line breaks
19
- - Emphasis (bold, italic, bold-italic)
20
- - Inline code and fenced/indented code blocks
21
- - Links (inline, reference, autolink) and images
22
- - Ordered and unordered lists with nesting
23
- - Block quotes with nesting
24
- - GFM tables with column alignment
25
- - GFM strikethrough (~~text~~)
26
- - GFM task lists (- [ ] / - [x])
27
- - GFM extended autolinks (bare URLs)
28
- - Backslash escapes
29
-
30
- Does NOT implement:
31
- - Raw HTML passthrough (escaped for safety)
32
- - Footnotes, definition lists, math/LaTeX
33
-
34
- Example::
35
-
36
- from markdown import render
37
- render("# Hello\\n\\nThis is **bold**.")
38
- # '<h1>Hello</h1>\\n<p>This is <strong>bold</strong>.</p>\\n'
39
- """
40
-
41
- from __future__ import annotations
42
-
43
- import html
44
- import re
45
-
46
- __all__ = [
47
- "render",
48
- ]
49
-
50
- # ── Constants ─────────────────────────────────────────────────────────────────
51
-
52
- _ESCAPED_CHARS = r"\\!\"#$%&'()*+,\-./:;<=>?@\[\\\]^_`{|}~"
53
-
54
- _HARMFUL_PROTOCOLS = ("javascript:", "vbscript:", "file:", "data:")
55
- _SAFE_DATA_PREFIXES = (
56
- "data:image/gif;",
57
- "data:image/png;",
58
- "data:image/jpeg;",
59
- "data:image/webp;",
60
- )
61
-
62
- # ── Block-level patterns ─────────────────────────────────────────────────────
63
-
64
- _ATX_HEADING_RE = re.compile(r"^(#{1,6})(?:\s+|$)(.*?)(?:\s+#+\s*)?$")
65
- _SETEXT_HEADING_RE = re.compile(r"^(=+|-+)\s*$")
66
- _FENCED_CODE_RE = re.compile(r"^( {0,3})(`{3,}|~{3,})\s*(\S*)\s*$")
67
- _THEMATIC_BREAK_RE = re.compile(
68
- r"^ {0,3}(?:(?:-[ \t]*){3,}|(?:\*[ \t]*){3,}|(?:_[ \t]*){3,})\s*$"
69
- )
70
- _BLOCK_QUOTE_RE = re.compile(r"^ {0,3}>[ \t]?(.*)")
71
- _UL_ITEM_RE = re.compile(r"^( *)([-*+]) (.*)")
72
- _OL_ITEM_RE = re.compile(r"^( *)(\d{1,9})([.)]) (.*)")
73
- _INDENT_CODE_RE = re.compile(r"^(?: {4}|\t)(.*)")
74
- _REF_LINK_RE = re.compile(
75
- r"""^ {0,3}\[([^\]]+)\]:\s+<?(\S+?)>?(?:\s+["'(](.+?)["')])?\s*$"""
76
- )
77
- _TABLE_DELIM_RE = re.compile(
78
- r"^ {0,3}\|?[ \t]*:?-+:?[ \t]*(?:\|[ \t]*:?-+:?[ \t]*)*\|?\s*$"
79
- )
80
- _BLANK_RE = re.compile(r"^\s*$")
81
-
82
- # ── Inline patterns ──────────────────────────────────────────────────────────
83
-
84
- _BACKSLASH_ESCAPE_RE = re.compile(r"\\([" + _ESCAPED_CHARS + r"])")
85
- _CODE_SPAN_RE = re.compile(r"(?<!`)(`+)(?!`)([\s\S]*?[^`])(\1)(?!`)")
86
- _AUTOLINK_RE = re.compile(r"<([a-zA-Z][a-zA-Z0-9.+-]{1,31}:[^<>\s]*)>")
87
- _AUTOEMAIL_RE = re.compile(
88
- r"<([a-zA-Z0-9.!#$%&'*+/=?^_`{|}~-]+@[a-zA-Z0-9]"
89
- r"(?:[a-zA-Z0-9-]{0,61}[a-zA-Z0-9])?"
90
- r"(?:\.[a-zA-Z0-9](?:[a-zA-Z0-9-]{0,61}[a-zA-Z0-9])?)*)>"
91
- )
92
- _IMAGE_RE = re.compile(
93
- r"!\[([^\[\]]*(?:\[[^\[\]]*\][^\[\]]*)*)\]"
94
- r"""\(\s*(\S+?)(?:\s+["'](.+?)["'])?\s*\)"""
95
- )
96
- _LINK_RE = re.compile(
97
- r"\[([^\[\]]*(?:\[[^\[\]]*\][^\[\]]*)*)\]"
98
- r"""\(\s*(\S+?)(?:\s+["'](.+?)["'])?\s*\)"""
99
- )
100
- _REF_LINK_USE_RE = re.compile(r"\[([^\[\]]+)\]\[([^\[\]]*)\]")
101
- _REF_LINK_SHORT_RE = re.compile(r"\[([^\[\]]+)\](?!\()")
102
- _STRONG_EM_RE = re.compile(r"\*{3}(.+?)\*{3}|_{3}(.+?)_{3}")
103
- _STRONG_RE = re.compile(r"\*{2}(.+?)\*{2}|_{2}(.+?)_{2}")
104
- _EM_RE = re.compile(r"(?<!\w)\*(.+?)\*(?!\w)|(?<!\w)_(.+?)_(?!\w)")
105
- _STRIKETHROUGH_RE = re.compile(r"~~(.+?)~~")
106
- _BARE_URL_RE = re.compile(r"(https?://[^\s<>\[\]]*[^\s<>\[\].,;:!?'\")}\]])")
107
- _HARD_BREAK_RE = re.compile(r"(?:\\| {2,})\n")
108
-
109
- # Task list marker: [ ], [x], or [X] at start of list item content
110
- _TASK_LIST_RE = re.compile(r"^\[([ xX])\]\s+")
111
-
112
- # ── Placeholder system ───────────────────────────────────────────────────────
113
-
114
- _PH_PREFIX = "\x00PH"
115
- _PH_SUFFIX = "\x00"
116
-
117
-
118
- class _Placeholders:
119
- """Manages placeholder substitution to protect parsed regions."""
120
-
121
- __slots__ = ("_store", "_counter")
122
-
123
- def __init__(self) -> None:
124
- self._store: list[str] = []
125
- self._counter = 0
126
-
127
- def put(self, value: str) -> str:
128
- idx = self._counter
129
- self._counter += 1
130
- self._store.append(value)
131
- return f"{_PH_PREFIX}{idx}{_PH_SUFFIX}"
132
-
133
- def restore(self, text: str) -> str:
134
- for i in range(len(self._store) - 1, -1, -1):
135
- text = text.replace(f"{_PH_PREFIX}{i}{_PH_SUFFIX}", self._store[i])
136
- return text
137
-
138
-
139
- # ── URL safety ────────��───────────────────────────────────────────────────────
140
-
141
-
142
- def _safe_url(url: str) -> str:
143
- """Sanitize a URL, blocking dangerous protocols."""
144
- lower = url.strip().lower()
145
- if lower.startswith(_HARMFUL_PROTOCOLS) and not lower.startswith(
146
- _SAFE_DATA_PREFIXES
147
- ):
148
- return "#harmful-link"
149
- return html.escape(url, quote=True)
150
-
151
-
152
- # ── Inline helper functions ──────────────────────────────────────────────────
153
-
154
-
155
- def _apply_bare_urls(text: str, ph: _Placeholders) -> str:
156
- """Replace bare http/https URLs with link placeholders."""
157
-
158
- def _bare_url_repl(m: re.Match[str]) -> str:
159
- url = m.group(1)
160
- return ph.put('<a href="' + _safe_url(url) + '">' + html.escape(url) + "</a>")
161
-
162
- return _BARE_URL_RE.sub(_bare_url_repl, text)
163
-
164
-
165
- def _apply_emphasis(
166
- text: str,
167
- ph: _Placeholders,
168
- ref_links: dict[str, tuple[str, str | None]],
169
- ) -> str:
170
- """Apply bold-italic, bold, italic, and strikethrough replacements."""
171
-
172
- # Bold-italic ***text***
173
- def _strong_em_repl(m: re.Match[str]) -> str:
174
- content = m.group(1) or m.group(2)
175
- return ph.put(
176
- "<em><strong>" + _parse_inline(content, ref_links) + "</strong></em>"
177
- )
178
-
179
- text = _STRONG_EM_RE.sub(_strong_em_repl, text)
180
-
181
- # Bold **text**
182
- def _strong_repl(m: re.Match[str]) -> str:
183
- content = m.group(1) or m.group(2)
184
- return ph.put("<strong>" + _parse_inline(content, ref_links) + "</strong>")
185
-
186
- text = _STRONG_RE.sub(_strong_repl, text)
187
-
188
- # Italic *text*
189
- def _em_repl(m: re.Match[str]) -> str:
190
- content = m.group(1) or m.group(2)
191
- return ph.put("<em>" + _parse_inline(content, ref_links) + "</em>")
192
-
193
- text = _EM_RE.sub(_em_repl, text)
194
-
195
- # Strikethrough ~~text~~
196
- def _strike_repl(m: re.Match[str]) -> str:
197
- content = m.group(1)
198
- return ph.put("<del>" + _parse_inline(content, ref_links) + "</del>")
199
-
200
- text = _STRIKETHROUGH_RE.sub(_strike_repl, text)
201
- return text
202
-
203
-
204
- # ── Inline parser ─────────────────────────────────────────────────────────────
205
-
206
-
207
- def _parse_inline(
208
- text: str,
209
- ref_links: dict[str, tuple[str, str | None]],
210
- ) -> str:
211
- """Parse inline Markdown elements and return HTML."""
212
- ph = _Placeholders()
213
-
214
- # 1. Backslash escapes → placeholder
215
- def _escape_repl(m: re.Match[str]) -> str:
216
- return ph.put(html.escape(m.group(1), quote=True))
217
-
218
- text = _BACKSLASH_ESCAPE_RE.sub(_escape_repl, text)
219
-
220
- # 2. Code spans → placeholder (no further parsing inside)
221
- def _code_repl(m: re.Match[str]) -> str:
222
- code = m.group(2).strip()
223
- return ph.put("<code>" + html.escape(code, quote=True) + "</code>")
224
-
225
- text = _CODE_SPAN_RE.sub(_code_repl, text)
226
-
227
- # 3. Autolinks
228
- def _autolink_repl(m: re.Match[str]) -> str:
229
- url = m.group(1)
230
- return ph.put('<a href="' + _safe_url(url) + '">' + html.escape(url) + "</a>")
231
-
232
- text = _AUTOLINK_RE.sub(_autolink_repl, text)
233
-
234
- # 3b. Auto emails
235
- def _autoemail_repl(m: re.Match[str]) -> str:
236
- email = m.group(1)
237
- return ph.put(
238
- '<a href="mailto:' + html.escape(email) + '">' + html.escape(email) + "</a>"
239
- )
240
-
241
- text = _AUTOEMAIL_RE.sub(_autoemail_repl, text)
242
-
243
- # 4. Images
244
- def _image_repl(m: re.Match[str]) -> str:
245
- alt = html.escape(m.group(1), quote=True)
246
- url = _safe_url(m.group(2))
247
- title = m.group(3)
248
- s = '<img src="' + url + '" alt="' + alt + '"'
249
- if title:
250
- s += ' title="' + html.escape(title, quote=True) + '"'
251
- s += " />"
252
- return ph.put(s)
253
-
254
- text = _IMAGE_RE.sub(_image_repl, text)
255
-
256
- # 5. Inline links
257
- def _link_repl(m: re.Match[str]) -> str:
258
- link_text = _parse_inline(m.group(1), ref_links)
259
- url = _safe_url(m.group(2))
260
- title = m.group(3)
261
- s = '<a href="' + url + '"'
262
- if title:
263
- s += ' title="' + html.escape(title, quote=True) + '"'
264
- s += ">" + link_text + "</a>"
265
- return ph.put(s)
266
-
267
- text = _LINK_RE.sub(_link_repl, text)
268
-
269
- # 5b. Reference links [text][ref]
270
- def _ref_link_repl(m: re.Match[str]) -> str:
271
- link_text = m.group(1)
272
- ref_key = (m.group(2) or link_text).strip().lower()
273
- ref = ref_links.get(ref_key)
274
- if ref is None:
275
- return m.group(0)
276
- url, title = ref
277
- s = '<a href="' + _safe_url(url) + '"'
278
- if title:
279
- s += ' title="' + html.escape(title, quote=True) + '"'
280
- s += ">" + _parse_inline(link_text, ref_links) + "</a>"
281
- return ph.put(s)
282
-
283
- text = _REF_LINK_USE_RE.sub(_ref_link_repl, text)
284
-
285
- # 5c. Shortcut reference links [ref]
286
- def _ref_short_repl(m: re.Match[str]) -> str:
287
- link_text = m.group(1)
288
- ref_key = link_text.strip().lower()
289
- ref = ref_links.get(ref_key)
290
- if ref is None:
291
- return m.group(0)
292
- url, title = ref
293
- s = '<a href="' + _safe_url(url) + '"'
294
- if title:
295
- s += ' title="' + html.escape(title, quote=True) + '"'
296
- s += ">" + _parse_inline(link_text, ref_links) + "</a>"
297
- return ph.put(s)
298
-
299
- text = _REF_LINK_SHORT_RE.sub(_ref_short_repl, text)
300
-
301
- # 5d. Extended autolinks (bare URLs without angle brackets)
302
- text = _apply_bare_urls(text, ph)
303
-
304
- # 6. Emphasis + strikethrough
305
- text = _apply_emphasis(text, ph, ref_links)
306
-
307
- # 7. Hard line breaks (protect with placeholder)
308
- text = _HARD_BREAK_RE.sub(lambda m: ph.put("<br />\n"), text)
309
-
310
- # 8. Escape remaining HTML in text
311
- # We need to be careful: only escape text that hasn't been processed.
312
- # The placeholder system handles this — placeholders contain final HTML.
313
- # We escape the remaining raw text segments between placeholders.
314
- parts = re.split(r"(\x00PH\d+\x00)", text)
315
- for i, part in enumerate(parts):
316
- if not part.startswith(_PH_PREFIX):
317
- parts[i] = html.escape(part, quote=False)
318
- text = "".join(parts)
319
-
320
- # 9. Restore placeholders
321
- text = ph.restore(text)
322
-
323
- return text
324
-
325
-
326
- # ── Table parser ──────────────────────────────────────────────────────────────
327
-
328
-
329
- def _parse_table_row(line: str) -> list[str]:
330
- """Split a table row into cells."""
331
- line = line.strip()
332
- if line.startswith("|"):
333
- line = line[1:]
334
- if line.endswith("|"):
335
- line = line[:-1]
336
- # Split on unescaped pipes
337
- cells = re.split(r"(?<!\\)\|", line)
338
- return [c.strip() for c in cells]
339
-
340
-
341
- def _parse_table_align(line: str) -> list[str | None]:
342
- """Parse alignment row, return list of 'left', 'right', 'center', or None."""
343
- cells = _parse_table_row(line)
344
- aligns: list[str | None] = []
345
- for cell in cells:
346
- cell = cell.strip()
347
- left = cell.startswith(":")
348
- right = cell.endswith(":")
349
- if left and right:
350
- aligns.append("center")
351
- elif right:
352
- aligns.append("right")
353
- elif left:
354
- aligns.append("left")
355
- else:
356
- aligns.append(None)
357
- return aligns
358
-
359
-
360
- def _render_table(
361
- header_line: str,
362
- align_line: str,
363
- body_lines: list[str],
364
- ref_links: dict[str, tuple[str, str | None]],
365
- ) -> str:
366
- """Render a GFM table to HTML."""
367
- headers = _parse_table_row(header_line)
368
- aligns = _parse_table_align(align_line)
369
-
370
- out: list[str] = ["<table>\n<thead>\n<tr>\n"]
371
- for i, h in enumerate(headers):
372
- align = aligns[i] if i < len(aligns) else None
373
- style = f' style="text-align:{align}"' if align else ""
374
- out.append(f" <th{style}>{_parse_inline(h, ref_links)}</th>\n")
375
- out.append("</tr>\n</thead>\n")
376
-
377
- if body_lines:
378
- out.append("<tbody>\n")
379
- for line in body_lines:
380
- cells = _parse_table_row(line)
381
- out.append("<tr>\n")
382
- for i, cell in enumerate(cells):
383
- align = aligns[i] if i < len(aligns) else None
384
- style = f' style="text-align:{align}"' if align else ""
385
- out.append(f" <td{style}>{_parse_inline(cell, ref_links)}</td>\n")
386
- out.append("</tr>\n")
387
- out.append("</tbody>\n")
388
-
389
- out.append("</table>\n")
390
- return "".join(out)
391
-
392
-
393
- # ── List parser ───────────────────────────────────────────────────────────────
394
-
395
-
396
- def _detect_list_type(
397
- line: str,
398
- ) -> tuple[bool, int, int] | None:
399
- """Detect whether a line starts a list item.
400
-
401
- Returns:
402
- (ordered, base_indent, start_num) or None if not a list item.
403
- """
404
- ol_m = _OL_ITEM_RE.match(line)
405
- if ol_m:
406
- return True, len(ol_m.group(1)), int(ol_m.group(2))
407
- ul_m = _UL_ITEM_RE.match(line)
408
- if ul_m:
409
- return False, len(ul_m.group(1)), 1
410
- return None
411
-
412
-
413
- def _blank_continues_list(
414
- lines: list[str],
415
- idx: int,
416
- ordered: bool,
417
- base_indent: int,
418
- ) -> bool:
419
- """Check whether a blank line at *idx* is followed by list continuation."""
420
- if idx + 1 >= len(lines):
421
- return False
422
- next_line = lines[idx + 1]
423
- if _BLANK_RE.match(next_line):
424
- return False
425
- # Same-level item?
426
- if ordered:
427
- m = _OL_ITEM_RE.match(next_line)
428
- if m and len(m.group(1)) == base_indent:
429
- return True
430
- else:
431
- m = _UL_ITEM_RE.match(next_line)
432
- if m and len(m.group(1)) == base_indent:
433
- return True
434
- # Indented continuation / nested content
435
- next_indent = len(next_line) - len(next_line.lstrip())
436
- return next_indent > base_indent
437
-
438
-
439
- def _match_same_level_item(
440
- line: str,
441
- ordered: bool,
442
- base_indent: int,
443
- ) -> str | None:
444
- """If *line* is a same-level list item, return its content text."""
445
- if ordered:
446
- m = _OL_ITEM_RE.match(line)
447
- if m and len(m.group(1)) == base_indent:
448
- return m.group(4)
449
- else:
450
- m = _UL_ITEM_RE.match(line)
451
- if m and len(m.group(1)) == base_indent:
452
- return m.group(3)
453
- return None
454
-
455
-
456
- def _collect_list_items(
457
- lines: list[str],
458
- start_idx: int,
459
- ordered: bool,
460
- base_indent: int,
461
- ) -> tuple[list[list[str]], int]:
462
- """Collect raw item line groups from a list block.
463
-
464
- Returns:
465
- (items, next_idx) where each item is a list of content lines.
466
- """
467
- idx = start_idx
468
- items: list[list[str]] = []
469
- current: list[str] = []
470
-
471
- while idx < len(lines):
472
- line = lines[idx]
473
-
474
- # Blank line — may separate items or end the list
475
- if _BLANK_RE.match(line):
476
- if _blank_continues_list(lines, idx, ordered, base_indent):
477
- current.append("")
478
- idx += 1
479
- continue
480
- break
481
-
482
- # Same-level item starts a new entry
483
- content = _match_same_level_item(line, ordered, base_indent)
484
- if content is not None:
485
- if current:
486
- items.append(current)
487
- current = [content]
488
- idx += 1
489
- continue
490
-
491
- # Nested / continuation line
492
- indent = len(line) - len(line.lstrip())
493
- if indent > base_indent and current:
494
- dedented = line[base_indent + 2 :] if len(line) > base_indent + 2 else ""
495
- current.append(dedented)
496
- idx += 1
497
- continue
498
-
499
- break
500
-
501
- if current:
502
- items.append(current)
503
- return items, idx
504
-
505
-
506
- def _render_list_item(
507
- item_lines: list[str],
508
- ref_links: dict[str, tuple[str, str | None]],
509
- ) -> str:
510
- """Render a single <li> element, recursing for nested sub-lists."""
511
- # Detect task list marker
512
- task_class = ""
513
- task_checkbox = ""
514
- first_line = item_lines[0]
515
- task_m = _TASK_LIST_RE.match(first_line)
516
- if task_m:
517
- checked = task_m.group(1) in ("x", "X")
518
- task_class = ' class="task-list-item"'
519
- task_checkbox = (
520
- '<input class="task-list-item-checkbox" type="checkbox" disabled'
521
- )
522
- if checked:
523
- task_checkbox += " checked"
524
- task_checkbox += "/>"
525
- item_lines = [first_line[task_m.end() :]] + item_lines[1:]
526
-
527
- has_sublist = any(
528
- _UL_ITEM_RE.match(il) or _OL_ITEM_RE.match(il) for il in item_lines[1:]
529
- )
530
- open_tag = f"<li{task_class}>" + task_checkbox
531
- if has_sublist:
532
- first = _parse_inline(item_lines[0], ref_links)
533
- sub_html = _parse_blocks(item_lines[1:], ref_links)
534
- return open_tag + first + sub_html + "</li>\n"
535
- content = "\n".join(item_lines).strip()
536
- return open_tag + _parse_inline(content, ref_links) + "</li>\n"
537
-
538
-
539
- def _parse_list_block(
540
- lines: list[str],
541
- start_idx: int,
542
- ref_links: dict[str, tuple[str, str | None]],
543
- ) -> tuple[str, int]:
544
- """Parse a list block starting at *start_idx*. Returns (html, next_idx)."""
545
- info = _detect_list_type(lines[start_idx])
546
- if info is None:
547
- return "", start_idx
548
- ordered, base_indent, start_num = info
549
-
550
- items, idx = _collect_list_items(lines, start_idx, ordered, base_indent)
551
-
552
- tag = "ol" if ordered else "ul"
553
- start_attr = f' start="{start_num}"' if ordered and start_num != 1 else ""
554
- parts: list[str] = [f"<{tag}{start_attr}>\n"]
555
- for item_lines in items:
556
- parts.append(_render_list_item(item_lines, ref_links))
557
- parts.append(f"</{tag}>\n")
558
- return "".join(parts), idx
559
-
560
-
561
- # ── Block-level try-parse helpers ────────────────────────────────────────────
562
-
563
- _BlockResult = tuple[str, int, bool]
564
- """(html, new_idx, consumed_para) returned by each _try_parse_* helper."""
565
-
566
-
567
- def _try_parse_hr(
568
- lines: list[str],
569
- idx: int,
570
- ref_links: dict[str, tuple[str, str | None]],
571
- para_lines: list[str],
572
- ) -> _BlockResult | None:
573
- """Try to parse a thematic break."""
574
- if para_lines:
575
- return None
576
- if _THEMATIC_BREAK_RE.match(lines[idx]):
577
- return "<hr />\n", idx + 1, False
578
- return None
579
-
580
-
581
- def _try_parse_atx_heading(
582
- lines: list[str],
583
- idx: int,
584
- ref_links: dict[str, tuple[str, str | None]],
585
- para_lines: list[str],
586
- ) -> _BlockResult | None:
587
- """Try to parse an ATX heading."""
588
- if para_lines:
589
- return None
590
- m = _ATX_HEADING_RE.match(lines[idx])
591
- if not m:
592
- return None
593
- level = len(m.group(1))
594
- content = re.sub(r"\s+#+\s*$", "", m.group(2).strip())
595
- tag = f"h{level}"
596
- h = f"<{tag}>{_parse_inline(content, ref_links)}</{tag}>\n"
597
- return h, idx + 1, False
598
-
599
-
600
- def _try_parse_setext_heading(
601
- lines: list[str],
602
- idx: int,
603
- ref_links: dict[str, tuple[str, str | None]],
604
- para_lines: list[str],
605
- ) -> _BlockResult | None:
606
- """Try to parse a Setext heading (requires accumulated paragraph lines)."""
607
- if not para_lines:
608
- return None
609
- line = lines[idx]
610
- if not _SETEXT_HEADING_RE.match(line):
611
- return None
612
- level = 1 if line.strip().startswith("=") else 2
613
- content = "\n".join(para_lines)
614
- tag = f"h{level}"
615
- h = f"<{tag}>{_parse_inline(content.strip(), ref_links)}</{tag}>\n"
616
- return h, idx + 1, True # consumed_para=True
617
-
618
-
619
- def _try_parse_code_fence(
620
- lines: list[str],
621
- idx: int,
622
- ref_links: dict[str, tuple[str, str | None]],
623
- para_lines: list[str],
624
- ) -> _BlockResult | None:
625
- """Try to parse a fenced code block."""
626
- if para_lines:
627
- return None
628
- m = _FENCED_CODE_RE.match(lines[idx])
629
- if not m:
630
- return None
631
- fence_indent = len(m.group(1))
632
- fence_char = m.group(2)[0]
633
- fence_len = len(m.group(2))
634
- lang = m.group(3).strip()
635
-
636
- code_lines: list[str] = []
637
- j = idx + 1
638
- close_re = re.compile(
639
- r"^ {0,3}" + re.escape(fence_char) + r"{" + str(fence_len) + r",}\s*$"
640
- )
641
- while j < len(lines):
642
- cl = lines[j]
643
- if close_re.match(cl):
644
- j += 1
645
- break
646
- code_lines.append(_strip_fence_indent(cl, fence_indent))
647
- j += 1
648
-
649
- code = "\n".join(code_lines)
650
- if code and not code.endswith("\n"):
651
- code += "\n"
652
- escaped_code = html.escape(code, quote=False)
653
- lang_attr = f' class="language-{html.escape(lang, quote=True)}"' if lang else ""
654
- h = f"<pre><code{lang_attr}>{escaped_code}</code></pre>\n"
655
- return h, j, False
656
-
657
-
658
- def _strip_fence_indent(line: str, indent: int) -> str:
659
- """Remove up to *indent* leading spaces from *line*."""
660
- if indent <= 0:
661
- return line
662
- for _ in range(indent):
663
- if line.startswith(" "):
664
- line = line[1:]
665
- else:
666
- break
667
- return line
668
-
669
-
670
- def _try_parse_indent_code(
671
- lines: list[str],
672
- idx: int,
673
- ref_links: dict[str, tuple[str, str | None]],
674
- para_lines: list[str],
675
- ) -> _BlockResult | None:
676
- """Try to parse an indented code block (4-space indent)."""
677
- if para_lines:
678
- return None
679
- if not _INDENT_CODE_RE.match(lines[idx]):
680
- return None
681
-
682
- code_lines: list[str] = []
683
- j = idx
684
- while j < len(lines):
685
- ic_m = _INDENT_CODE_RE.match(lines[j])
686
- if ic_m:
687
- code_lines.append(ic_m.group(1))
688
- j += 1
689
- elif _BLANK_RE.match(lines[j]):
690
- if j + 1 < len(lines) and _INDENT_CODE_RE.match(lines[j + 1]):
691
- code_lines.append("")
692
- j += 1
693
- else:
694
- break
695
- else:
696
- break
697
- # Remove trailing blank lines
698
- while code_lines and code_lines[-1] == "":
699
- code_lines.pop()
700
- escaped_code = html.escape("\n".join(code_lines), quote=False)
701
- h = f"<pre><code>{escaped_code}</code></pre>\n"
702
- return h, j, False
703
-
704
-
705
- def _try_parse_blockquote(
706
- lines: list[str],
707
- idx: int,
708
- ref_links: dict[str, tuple[str, str | None]],
709
- para_lines: list[str],
710
- ) -> _BlockResult | None:
711
- """Try to parse a block quote (can interrupt a paragraph)."""
712
- if not _BLOCK_QUOTE_RE.match(lines[idx]):
713
- return None
714
-
715
- bq_lines: list[str] = []
716
- j = idx
717
- while j < len(lines):
718
- bq_match = _BLOCK_QUOTE_RE.match(lines[j])
719
- if bq_match:
720
- bq_lines.append(bq_match.group(1))
721
- j += 1
722
- elif _BLANK_RE.match(lines[j]):
723
- if j + 1 < len(lines) and _BLOCK_QUOTE_RE.match(lines[j + 1]):
724
- bq_lines.append("")
725
- j += 1
726
- else:
727
- break
728
- elif lines[j].strip():
729
- # Lazy continuation
730
- bq_lines.append(lines[j])
731
- j += 1
732
- else:
733
- break
734
- inner = _parse_blocks(bq_lines, ref_links)
735
- h = "<blockquote>\n" + inner + "</blockquote>\n"
736
- return h, j, False
737
-
738
-
739
- def _try_parse_list(
740
- lines: list[str],
741
- idx: int,
742
- ref_links: dict[str, tuple[str, str | None]],
743
- para_lines: list[str],
744
- ) -> _BlockResult | None:
745
- """Try to parse an ordered or unordered list."""
746
- if para_lines:
747
- return None
748
- if not (_UL_ITEM_RE.match(lines[idx]) or _OL_ITEM_RE.match(lines[idx])):
749
- return None
750
- list_html, new_idx = _parse_list_block(lines, idx, ref_links)
751
- return list_html, new_idx, False
752
-
753
-
754
- def _try_parse_table(
755
- lines: list[str],
756
- idx: int,
757
- ref_links: dict[str, tuple[str, str | None]],
758
- para_lines: list[str],
759
- ) -> _BlockResult | None:
760
- """Try to parse a GFM table."""
761
- if para_lines:
762
- return None
763
- line = lines[idx]
764
- if "|" not in line or idx + 1 >= len(lines):
765
- return None
766
- if not _TABLE_DELIM_RE.match(lines[idx + 1]):
767
- return None
768
-
769
- header_line = line
770
- align_line = lines[idx + 1]
771
- body: list[str] = []
772
- j = idx + 2
773
- while j < len(lines):
774
- tl = lines[j]
775
- if "|" in tl and not _BLANK_RE.match(tl):
776
- body.append(tl)
777
- j += 1
778
- else:
779
- break
780
- h = _render_table(header_line, align_line, body, ref_links)
781
- return h, j, False
782
-
783
-
784
- # Ordered list of try-parse functions used by the block dispatcher.
785
- _BLOCK_PARSERS = (
786
- _try_parse_hr,
787
- _try_parse_atx_heading,
788
- _try_parse_setext_heading,
789
- _try_parse_code_fence,
790
- _try_parse_indent_code,
791
- _try_parse_blockquote,
792
- _try_parse_list,
793
- _try_parse_table,
794
- )
795
-
796
-
797
- # ── Block parser ──────────────────────────────────────────────────────────────
798
-
799
-
800
- def _collect_ref_links(
801
- lines: list[str],
802
- ) -> dict[str, tuple[str, str | None]]:
803
- """First pass: collect reference link definitions."""
804
- refs: dict[str, tuple[str, str | None]] = {}
805
- for line in lines:
806
- m = _REF_LINK_RE.match(line)
807
- if m:
808
- key = m.group(1).strip().lower()
809
- url = m.group(2)
810
- title = m.group(3)
811
- refs[key] = (url, title)
812
- return refs
813
-
814
-
815
- def _parse_blocks(
816
- lines: list[str],
817
- ref_links: dict[str, tuple[str, str | None]],
818
- ) -> str:
819
- """Parse block-level Markdown elements from a list of lines."""
820
- out: list[str] = []
821
- idx = 0
822
- para_lines: list[str] = []
823
-
824
- def flush_paragraph() -> None:
825
- if para_lines:
826
- text = "\n".join(para_lines)
827
- out.append("<p>" + _parse_inline(text.strip(), ref_links) + "</p>\n")
828
- para_lines.clear()
829
-
830
- while idx < len(lines):
831
- line = lines[idx]
832
-
833
- # Skip reference link definitions (already collected)
834
- if _REF_LINK_RE.match(line):
835
- flush_paragraph()
836
- idx += 1
837
- continue
838
-
839
- # Blank line
840
- if _BLANK_RE.match(line):
841
- flush_paragraph()
842
- idx += 1
843
- continue
844
-
845
- # Try each block-level parser in priority order
846
- result = _dispatch_block(lines, idx, ref_links, para_lines)
847
- if result is not None:
848
- block_html, idx, consumed_para = result
849
- if consumed_para:
850
- para_lines.clear()
851
- else:
852
- flush_paragraph()
853
- out.append(block_html)
854
- continue
855
-
856
- # Paragraph accumulation
857
- para_lines.append(line)
858
- idx += 1
859
-
860
- flush_paragraph()
861
- return "".join(out)
862
-
863
-
864
- def _dispatch_block(
865
- lines: list[str],
866
- idx: int,
867
- ref_links: dict[str, tuple[str, str | None]],
868
- para_lines: list[str],
869
- ) -> _BlockResult | None:
870
- """Try each registered block parser; return first match or None."""
871
- for try_fn in _BLOCK_PARSERS:
872
- result = try_fn(lines, idx, ref_links, para_lines)
873
- if result is not None:
874
- return result
875
- return None
876
-
877
-
878
- # ── Public API ────────────────────────────────────────────────────────────────
879
-
880
-
881
- def render(text: str) -> str:
882
- """Convert Markdown text to HTML.
883
-
884
- Args:
885
- text: Markdown source string.
886
-
887
- Returns:
888
- HTML string.
889
- """
890
- # Normalize line endings
891
- text = text.replace("\r\n", "\n").replace("\r", "\n")
892
-
893
- # Split into lines
894
- lines = text.split("\n")
895
-
896
- # Remove trailing newline that produces empty last element
897
- if lines and lines[-1] == "":
898
- lines.pop()
899
-
900
- # First pass: collect reference link definitions
901
- ref_links = _collect_ref_links(lines)
902
-
903
- # Second pass: parse blocks
904
- return _parse_blocks(lines, ref_links)
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
src/veilrender/_vendor/retry.py DELETED
@@ -1,503 +0,0 @@
1
- # /// zerodep
2
- # version = "0.3.0"
3
- # deps = []
4
- # tier = "simple"
5
- # category = "process"
6
- # note = "Install/update via `zerodep add retry`"
7
- # ///
8
-
9
- """Zero-dependency retry with configurable backoff strategies.
10
-
11
- Part of zerodep: https://github.com/Oaklight/zerodep
12
- Copyright (c) 2026 Peng Ding. MIT License.
13
-
14
- Decorator-based retry with exponential / linear / fixed backoff,
15
- jitter, exception and result filtering, and async support.
16
-
17
- Basic usage::
18
-
19
- @retry(max_retries=3)
20
- def call_api():
21
- return get("https://api.example.com/data")
22
-
23
- Async usage::
24
-
25
- @retry(max_retries=3, retry_on=(ConnectionError, TimeoutError))
26
- async def call_api():
27
- return await async_get("https://api.example.com/data")
28
-
29
- Imperative usage::
30
-
31
- result = retry_call(call_api, max_retries=5)
32
-
33
- HTTP status filtering::
34
-
35
- @retry(retry_on=retry_if_status(429, 502, 503))
36
- def call_api():
37
- resp = get("https://api.example.com/data")
38
- resp.raise_for_status()
39
- return resp
40
- """
41
-
42
- from __future__ import annotations
43
-
44
- import asyncio
45
- import dataclasses
46
- import functools
47
- import inspect
48
- import random
49
- import time
50
- from typing import Any, Callable
51
-
52
- __all__ = [
53
- # Constants
54
- "DEFAULT_MAX_RETRIES",
55
- "DEFAULT_BASE_DELAY",
56
- "DEFAULT_MAX_DELAY",
57
- "DEFAULT_BACKOFF_FACTOR",
58
- # Exceptions
59
- "RetryError",
60
- # Data classes
61
- "RetryState",
62
- # Predicates
63
- "retry_if_exception",
64
- "retry_if_result",
65
- "retry_if_status",
66
- # Main API
67
- "retry",
68
- "retry_call",
69
- ]
70
-
71
- # ── Defaults ──
72
-
73
- DEFAULT_MAX_RETRIES = 3
74
- DEFAULT_BASE_DELAY = 1.0
75
- DEFAULT_MAX_DELAY = 60.0
76
- DEFAULT_BACKOFF_FACTOR = 2.0
77
-
78
-
79
- # ── Exceptions ──
80
-
81
-
82
- class RetryError(Exception):
83
- """Raised when all retry attempts are exhausted.
84
-
85
- Attributes:
86
- last_exception: The exception from the final attempt, or ``None``
87
- if retries were triggered by result predicate.
88
- attempts: Total number of calls made (initial + retries).
89
- """
90
-
91
- def __init__(self, last_exception: BaseException | None, attempts: int) -> None:
92
- self.last_exception = last_exception
93
- self.attempts = attempts
94
- super().__init__(
95
- f"Retry exhausted after {attempts} attempt(s)"
96
- + (f": {last_exception}" if last_exception else "")
97
- )
98
-
99
-
100
- # ── Retry State ──
101
-
102
-
103
- @dataclasses.dataclass
104
- class RetryState:
105
- """Information about the current retry, passed to *on_retry* callback.
106
-
107
- Attributes:
108
- attempt: 1-based retry number (1 = first retry, not the initial call).
109
- exception: The exception that triggered this retry, or ``None``.
110
- result: The return value that triggered this retry, or ``None``.
111
- delay: Seconds to sleep before the next attempt.
112
- elapsed: Seconds elapsed since the initial call.
113
- """
114
-
115
- attempt: int
116
- exception: BaseException | None
117
- result: Any
118
- delay: float
119
- elapsed: float
120
-
121
-
122
- # ── Retry Condition Helpers ──
123
-
124
-
125
- def retry_if_exception(
126
- *exc_types: type[BaseException],
127
- ) -> Callable[[BaseException], bool]:
128
- """Build a predicate that matches specific exception types.
129
-
130
- Args:
131
- *exc_types: Exception classes to retry on.
132
-
133
- Returns:
134
- A callable ``(exc) -> bool``.
135
- """
136
-
137
- def predicate(exc: BaseException) -> bool:
138
- return isinstance(exc, exc_types)
139
-
140
- return predicate
141
-
142
-
143
- def retry_if_result(predicate: Callable[[Any], bool]) -> Callable[[Any], bool]:
144
- """Mark a callable as a result-retry predicate (identity helper).
145
-
146
- Args:
147
- predicate: A callable ``(result) -> bool`` returning ``True`` to retry.
148
-
149
- Returns:
150
- The same callable, for self-documenting call sites.
151
- """
152
- return predicate
153
-
154
-
155
- def retry_if_status(*status_codes: int) -> Callable[[BaseException], bool]:
156
- """Build a predicate that retries on HTTP status codes.
157
-
158
- Works with any exception carrying a ``status_code`` attribute
159
- (e.g. ``httpclient.HTTPError``).
160
-
161
- Args:
162
- *status_codes: HTTP status codes to retry on (e.g. 429, 502, 503).
163
-
164
- Returns:
165
- A callable ``(exc) -> bool``.
166
- """
167
- codes = set(status_codes)
168
-
169
- def predicate(exc: BaseException) -> bool:
170
- sc = getattr(exc, "status_code", None)
171
- return sc is not None and sc in codes
172
-
173
- return predicate
174
-
175
-
176
- # ── Internal Helpers ──
177
-
178
-
179
- def _compute_delay(
180
- attempt: int,
181
- backoff: str,
182
- base_delay: float,
183
- backoff_factor: float,
184
- max_delay: float,
185
- jitter: str,
186
- ) -> float:
187
- """Compute the sleep duration for a given retry attempt.
188
-
189
- Args:
190
- attempt: 0-based retry index (0 = first retry).
191
- backoff: Strategy name.
192
- base_delay: Base delay in seconds.
193
- backoff_factor: Multiplier for exponential backoff.
194
- max_delay: Upper bound on delay.
195
- jitter: Jitter mode.
196
-
197
- Returns:
198
- Sleep duration in seconds.
199
-
200
- Raises:
201
- ValueError: On unknown *backoff* or *jitter* value.
202
- """
203
- if backoff == "exponential":
204
- delay = base_delay * (backoff_factor**attempt)
205
- elif backoff == "linear":
206
- delay = base_delay * (attempt + 1)
207
- elif backoff == "fixed":
208
- delay = base_delay
209
- else:
210
- raise ValueError(f"Unknown backoff strategy: {backoff!r}")
211
-
212
- delay = min(delay, max_delay)
213
-
214
- if jitter == "full":
215
- delay = random.uniform(0, delay)
216
- elif jitter == "equal":
217
- half = delay / 2
218
- delay = half + random.uniform(0, half)
219
- elif jitter == "none":
220
- pass
221
- else:
222
- raise ValueError(f"Unknown jitter mode: {jitter!r}")
223
-
224
- return delay
225
-
226
-
227
- def _should_retry_exception(
228
- exc: BaseException,
229
- retry_on: tuple[type[BaseException], ...] | Callable[[BaseException], bool],
230
- ) -> bool:
231
- """Check whether *exc* matches the retry condition."""
232
- if isinstance(retry_on, tuple):
233
- return isinstance(exc, retry_on)
234
- return retry_on(exc)
235
-
236
-
237
- # ── Core Retry Loops ──
238
-
239
-
240
- def _retry_sync(
241
- fn: Callable[..., Any],
242
- args: tuple[Any, ...],
243
- kwargs: dict[str, Any],
244
- *,
245
- max_retries: int,
246
- base_delay: float,
247
- max_delay: float,
248
- backoff: str,
249
- backoff_factor: float,
250
- jitter: str,
251
- retry_on: tuple[type[BaseException], ...] | Callable[[BaseException], bool],
252
- retry_on_result: Callable[[Any], bool] | None,
253
- on_retry: Callable[[RetryState], None] | None,
254
- ) -> Any:
255
- start = time.monotonic()
256
-
257
- for attempt in range(max_retries + 1): # 0 = initial call
258
- try:
259
- result = fn(*args, **kwargs)
260
-
261
- if retry_on_result is not None and retry_on_result(result):
262
- if attempt >= max_retries:
263
- raise RetryError(None, max_retries + 1)
264
- delay = _compute_delay(
265
- attempt, backoff, base_delay, backoff_factor, max_delay, jitter
266
- )
267
- if on_retry:
268
- on_retry(
269
- RetryState(
270
- attempt=attempt + 1,
271
- exception=None,
272
- result=result,
273
- delay=delay,
274
- elapsed=time.monotonic() - start,
275
- )
276
- )
277
- time.sleep(delay)
278
- continue
279
-
280
- return result
281
-
282
- except BaseException as exc:
283
- if not _should_retry_exception(exc, retry_on) or attempt >= max_retries:
284
- raise
285
-
286
- delay = _compute_delay(
287
- attempt, backoff, base_delay, backoff_factor, max_delay, jitter
288
- )
289
- if on_retry:
290
- on_retry(
291
- RetryState(
292
- attempt=attempt + 1,
293
- exception=exc,
294
- result=None,
295
- delay=delay,
296
- elapsed=time.monotonic() - start,
297
- )
298
- )
299
- time.sleep(delay)
300
-
301
-
302
- async def _retry_async(
303
- fn: Callable[..., Any],
304
- args: tuple[Any, ...],
305
- kwargs: dict[str, Any],
306
- *,
307
- max_retries: int,
308
- base_delay: float,
309
- max_delay: float,
310
- backoff: str,
311
- backoff_factor: float,
312
- jitter: str,
313
- retry_on: tuple[type[BaseException], ...] | Callable[[BaseException], bool],
314
- retry_on_result: Callable[[Any], bool] | None,
315
- on_retry: Callable[[RetryState], None] | None,
316
- ) -> Any:
317
- start = time.monotonic()
318
-
319
- for attempt in range(max_retries + 1):
320
- try:
321
- result = await fn(*args, **kwargs)
322
-
323
- if retry_on_result is not None and retry_on_result(result):
324
- if attempt >= max_retries:
325
- raise RetryError(None, max_retries + 1)
326
- delay = _compute_delay(
327
- attempt, backoff, base_delay, backoff_factor, max_delay, jitter
328
- )
329
- if on_retry:
330
- on_retry(
331
- RetryState(
332
- attempt=attempt + 1,
333
- exception=None,
334
- result=result,
335
- delay=delay,
336
- elapsed=time.monotonic() - start,
337
- )
338
- )
339
- await asyncio.sleep(delay)
340
- continue
341
-
342
- return result
343
-
344
- except BaseException as exc:
345
- if not _should_retry_exception(exc, retry_on) or attempt >= max_retries:
346
- raise
347
-
348
- delay = _compute_delay(
349
- attempt, backoff, base_delay, backoff_factor, max_delay, jitter
350
- )
351
- if on_retry:
352
- on_retry(
353
- RetryState(
354
- attempt=attempt + 1,
355
- exception=exc,
356
- result=None,
357
- delay=delay,
358
- elapsed=time.monotonic() - start,
359
- )
360
- )
361
- await asyncio.sleep(delay)
362
-
363
-
364
- # ── Public API ──
365
-
366
-
367
- def retry(
368
- fn: Callable[..., Any] | None = None,
369
- *,
370
- max_retries: int = DEFAULT_MAX_RETRIES,
371
- base_delay: float = DEFAULT_BASE_DELAY,
372
- max_delay: float = DEFAULT_MAX_DELAY,
373
- backoff: str = "exponential",
374
- backoff_factor: float = DEFAULT_BACKOFF_FACTOR,
375
- jitter: str = "full",
376
- retry_on: tuple[type[BaseException], ...] | Callable[[BaseException], bool] = (
377
- Exception,
378
- ),
379
- retry_on_result: Callable[[Any], bool] | None = None,
380
- on_retry: Callable[[RetryState], None] | None = None,
381
- ) -> Callable[..., Any]:
382
- """Decorator that retries a function on failure with configurable backoff.
383
-
384
- Can be used with or without arguments::
385
-
386
- @retry
387
- def f(): ...
388
-
389
- @retry()
390
- def g(): ...
391
-
392
- @retry(max_retries=5, backoff="linear")
393
- def h(): ...
394
-
395
- Automatically detects async functions and uses ``asyncio.sleep``.
396
-
397
- Args:
398
- fn: The function to decorate (set automatically when used as
399
- ``@retry`` without parentheses).
400
- max_retries: Maximum number of retries (not counting the initial call).
401
- base_delay: Base delay in seconds before the first retry.
402
- max_delay: Upper bound on computed delay.
403
- backoff: Backoff strategy — ``"exponential"``, ``"linear"``, or
404
- ``"fixed"``.
405
- backoff_factor: Multiplier for exponential backoff.
406
- jitter: Jitter mode — ``"full"`` (uniform [0, delay]),
407
- ``"equal"`` (delay/2 + uniform [0, delay/2]), or ``"none"``.
408
- retry_on: Exception types or a callable ``(exc) -> bool`` deciding
409
- whether to retry. Defaults to ``(Exception,)``.
410
- retry_on_result: Optional callable ``(result) -> bool``. When it
411
- returns ``True`` the call is retried.
412
- on_retry: Optional callback invoked before each retry sleep with a
413
- :class:`RetryState` instance.
414
-
415
- Returns:
416
- The decorated function (sync or async, matching the original).
417
-
418
- Raises:
419
- RetryError: When retries are exhausted due to *retry_on_result*.
420
- The original exception: When retries are exhausted due to exceptions.
421
- """
422
-
423
- def decorator(fn: Callable[..., Any]) -> Callable[..., Any]:
424
- if inspect.iscoroutinefunction(fn):
425
-
426
- @functools.wraps(fn)
427
- async def async_wrapper(*args: Any, **kwargs: Any) -> Any:
428
- return await _retry_async(
429
- fn,
430
- args,
431
- kwargs,
432
- max_retries=max_retries,
433
- base_delay=base_delay,
434
- max_delay=max_delay,
435
- backoff=backoff,
436
- backoff_factor=backoff_factor,
437
- jitter=jitter,
438
- retry_on=retry_on,
439
- retry_on_result=retry_on_result,
440
- on_retry=on_retry,
441
- )
442
-
443
- return async_wrapper
444
-
445
- @functools.wraps(fn)
446
- def sync_wrapper(*args: Any, **kwargs: Any) -> Any:
447
- return _retry_sync(
448
- fn,
449
- args,
450
- kwargs,
451
- max_retries=max_retries,
452
- base_delay=base_delay,
453
- max_delay=max_delay,
454
- backoff=backoff,
455
- backoff_factor=backoff_factor,
456
- jitter=jitter,
457
- retry_on=retry_on,
458
- retry_on_result=retry_on_result,
459
- on_retry=on_retry,
460
- )
461
-
462
- return sync_wrapper
463
-
464
- if fn is not None:
465
- return decorator(fn)
466
- return decorator
467
-
468
-
469
- def retry_call(
470
- fn: Callable[..., Any],
471
- args: tuple[Any, ...] = (),
472
- kwargs: dict[str, Any] | None = None,
473
- **retry_kwargs: Any,
474
- ) -> Any:
475
- """Call *fn* with retry logic without using a decorator.
476
-
477
- Args:
478
- fn: The callable to invoke.
479
- args: Positional arguments for *fn*.
480
- kwargs: Keyword arguments for *fn*.
481
- **retry_kwargs: Same keyword arguments accepted by :func:`retry`.
482
-
483
- Returns:
484
- The return value of *fn* on success.
485
- """
486
- if kwargs is None:
487
- kwargs = {}
488
-
489
- opts: dict[str, Any] = dict(
490
- max_retries=retry_kwargs.pop("max_retries", DEFAULT_MAX_RETRIES),
491
- base_delay=retry_kwargs.pop("base_delay", DEFAULT_BASE_DELAY),
492
- max_delay=retry_kwargs.pop("max_delay", DEFAULT_MAX_DELAY),
493
- backoff=retry_kwargs.pop("backoff", "exponential"),
494
- backoff_factor=retry_kwargs.pop("backoff_factor", DEFAULT_BACKOFF_FACTOR),
495
- jitter=retry_kwargs.pop("jitter", "full"),
496
- retry_on=retry_kwargs.pop("retry_on", (Exception,)),
497
- retry_on_result=retry_kwargs.pop("retry_on_result", None),
498
- on_retry=retry_kwargs.pop("on_retry", None),
499
- )
500
-
501
- if inspect.iscoroutinefunction(fn):
502
- return _retry_async(fn, args, kwargs, **opts)
503
- return _retry_sync(fn, args, kwargs, **opts)
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
src/veilrender/_vendor/structlog.py DELETED
@@ -1,888 +0,0 @@
1
- # /// zerodep
2
- # version = "0.3.0"
3
- # deps = []
4
- # tier = "medium"
5
- # category = "devtools"
6
- # note = "Install/update via `zerodep add structlog`"
7
- # ///
8
-
9
- """Zero-dependency structured logging with pretty console output.
10
-
11
- Part of zerodep: https://github.com/Oaklight/zerodep
12
- Copyright (c) 2026 Peng Ding. MIT License.
13
-
14
- Structured logging library inspired by structlog, with a loguru-style
15
- colored console renderer. Provides bound loggers with context propagation,
16
- a processor pipeline, and multiple output renderers (console, JSON, key-value).
17
-
18
- Quick start (pretty console output, zero config)::
19
-
20
- from structlog import get_logger
21
- logger = get_logger()
22
- logger.info("server started", host="0.0.0.0", port=8080)
23
-
24
- Bound logger (context propagation)::
25
-
26
- log = get_logger().bind(request_id="abc-123")
27
- log.info("handling request")
28
- log = log.bind(user_id=42)
29
- log.info("authenticated")
30
-
31
- One-call setup with stdlib integration::
32
-
33
- from structlog import setup_logging
34
- logger = setup_logging(level="DEBUG", renderer="json")
35
- logger.info("structured", key="value")
36
-
37
- Custom processor pipeline::
38
-
39
- from structlog import configure, add_log_level, TimeStamper, JSONRenderer
40
- configure(processors=[add_log_level, TimeStamper(), JSONRenderer()])
41
- """
42
-
43
- from __future__ import annotations
44
-
45
- import dataclasses
46
- import datetime
47
- import json as _json
48
- import logging
49
- import os
50
- import sys
51
- import traceback
52
- from typing import IO, Any, Callable
53
-
54
- __all__ = [
55
- # Type aliases
56
- "EventDict",
57
- "Processor",
58
- "LoggerFactory",
59
- # Exceptions
60
- "DropEvent",
61
- # Logger factories
62
- "PrintLogger",
63
- "PrintLoggerFactory",
64
- "StdlibLoggerFactory",
65
- # Processors
66
- "add_log_level",
67
- "add_logger_name",
68
- "TimeStamper",
69
- "format_exc_info",
70
- # Renderers
71
- "KeyValueRenderer",
72
- "JSONRenderer",
73
- "ConsoleRenderer",
74
- # Bound logger
75
- "BoundLogger",
76
- # Configuration
77
- "configure",
78
- "reset_defaults",
79
- "get_config",
80
- "get_logger",
81
- "wrap_logger",
82
- # Setup helper
83
- "setup_logging",
84
- # Utilities
85
- "truncate_string",
86
- "truncate_base64",
87
- ]
88
-
89
- # ── Type Aliases ─────────────────────────────────────────────────────────────
90
-
91
- EventDict = dict[str, Any]
92
- """A log event dictionary passed through the processor pipeline."""
93
-
94
- Processor = Callable[[Any, str, EventDict], EventDict | str]
95
- """Signature: (logger, method_name, event_dict) -> event_dict or rendered str."""
96
-
97
- LoggerFactory = Callable[..., Any]
98
- """Callable that creates an underlying logger instance."""
99
-
100
-
101
- # ── Exceptions ───────────────────────────────────────────────────────────────
102
-
103
-
104
- class DropEvent(Exception):
105
- """Raise inside a processor to silently discard the current log event."""
106
-
107
-
108
- # ── Level Mapping ────────────────────────────────────────────────────────────
109
-
110
- _NAME_TO_LEVEL: dict[str, int] = {
111
- "debug": logging.DEBUG,
112
- "info": logging.INFO,
113
- "warning": logging.WARNING,
114
- "warn": logging.WARNING,
115
- "error": logging.ERROR,
116
- "critical": logging.CRITICAL,
117
- "fatal": logging.CRITICAL,
118
- "exception": logging.ERROR,
119
- }
120
-
121
- _LEVEL_TO_NAME: dict[int, str] = {
122
- logging.DEBUG: "debug",
123
- logging.INFO: "info",
124
- logging.WARNING: "warning",
125
- logging.ERROR: "error",
126
- logging.CRITICAL: "critical",
127
- }
128
-
129
-
130
- # ── ANSI Colors ──────────────────────────────────────────────────────────────
131
-
132
-
133
- class _Colors:
134
- """ANSI escape codes for terminal colorization."""
135
-
136
- RESET = "\033[0m"
137
- BOLD = "\033[1m"
138
- DIM = "\033[2m"
139
- ITALIC = "\033[3m"
140
- UNDERLINE = "\033[4m"
141
- STRIKETHROUGH = "\033[9m"
142
-
143
- BLACK = "\033[30m"
144
- RED = "\033[31m"
145
- GREEN = "\033[32m"
146
- YELLOW = "\033[33m"
147
- BLUE = "\033[34m"
148
- MAGENTA = "\033[35m"
149
- CYAN = "\033[36m"
150
- WHITE = "\033[37m"
151
-
152
- BRIGHT_BLACK = "\033[90m"
153
- BRIGHT_RED = "\033[91m"
154
- BRIGHT_GREEN = "\033[92m"
155
- BRIGHT_YELLOW = "\033[93m"
156
- BRIGHT_BLUE = "\033[94m"
157
- BRIGHT_MAGENTA = "\033[95m"
158
- BRIGHT_CYAN = "\033[96m"
159
- BRIGHT_WHITE = "\033[97m"
160
-
161
-
162
- _LEVEL_STYLES: dict[str, str] = {
163
- "debug": _Colors.BLUE,
164
- "info": _Colors.BRIGHT_WHITE,
165
- "warning": _Colors.YELLOW,
166
- "warn": _Colors.YELLOW,
167
- "error": _Colors.RED,
168
- "critical": _Colors.BRIGHT_RED + _Colors.BOLD,
169
- "fatal": _Colors.BRIGHT_RED + _Colors.BOLD,
170
- "exception": _Colors.RED,
171
- }
172
-
173
- _LEVEL_LABEL_STYLES: dict[str, str] = {
174
- "debug": _Colors.CYAN,
175
- "info": _Colors.GREEN,
176
- "warning": _Colors.YELLOW,
177
- "warn": _Colors.YELLOW,
178
- "error": _Colors.RED,
179
- "critical": _Colors.BRIGHT_RED + _Colors.BOLD,
180
- "fatal": _Colors.BRIGHT_RED + _Colors.BOLD,
181
- "exception": _Colors.RED,
182
- }
183
-
184
- _LEVEL_LABELS: dict[str, str] = {
185
- "debug": "DEBUG ",
186
- "info": "INFO ",
187
- "warning": "WARNING ",
188
- "warn": "WARNING ",
189
- "error": "ERROR ",
190
- "critical": "CRITICAL",
191
- "fatal": "FATAL ",
192
- "exception": "ERROR ",
193
- }
194
-
195
-
196
- def _supports_color(stream: Any = None) -> bool:
197
- """Check if the output stream supports ANSI color codes.
198
-
199
- Respects the ``FORCE_COLOR`` and ``NO_COLOR`` environment variables
200
- (see https://force-color.org/ and https://no-color.org/).
201
-
202
- Args:
203
- stream: The output stream to check. Defaults to ``sys.stderr``.
204
-
205
- Returns:
206
- True if the stream is a color-capable terminal.
207
- """
208
- if os.environ.get("FORCE_COLOR"):
209
- return True
210
- if os.environ.get("NO_COLOR"):
211
- return False
212
- s = stream or sys.stderr
213
- if not hasattr(s, "isatty") or not s.isatty():
214
- return False
215
- if os.environ.get("TERM", "") == "dumb":
216
- return False
217
- return True
218
-
219
-
220
- # ── Logger Factories ─────────────────────────────────────────────────────────
221
-
222
-
223
- class PrintLogger:
224
- """Minimal logger that writes to a file handle via ``print()``.
225
-
226
- This is the default underlying logger. It has no filtering, no
227
- handler chain -- just ``print()`` to the configured stream.
228
-
229
- Args:
230
- file: Output stream. Defaults to ``sys.stderr``.
231
- """
232
-
233
- def __init__(self, file: IO[str] | None = None) -> None:
234
- self._file = file or sys.stderr
235
- self._write = self._file.write
236
- self._flush = self._file.flush
237
-
238
- def msg(self, message: str) -> None:
239
- """Write *message* followed by a newline."""
240
- self._write(message + "\n")
241
- self._flush()
242
-
243
- debug = info = warning = warn = error = critical = fatal = msg
244
-
245
-
246
- class PrintLoggerFactory:
247
- """Factory that creates :class:`PrintLogger` instances.
248
-
249
- Args:
250
- file: Output stream passed to each ``PrintLogger``.
251
- """
252
-
253
- def __init__(self, file: IO[str] | None = None) -> None:
254
- self._file = file
255
-
256
- def __call__(self, *args: Any) -> PrintLogger:
257
- return PrintLogger(file=self._file)
258
-
259
-
260
- class StdlibLoggerFactory:
261
- """Factory that returns a :class:`logging.Logger` from the stdlib.
262
-
263
- Args:
264
- name: Logger name passed to ``logging.getLogger()``.
265
- If *None*, uses the root logger.
266
- """
267
-
268
- def __init__(self, name: str | None = None) -> None:
269
- self._name = name
270
-
271
- def __call__(self, *args: Any) -> logging.Logger:
272
- if args:
273
- return logging.getLogger(args[0])
274
- return logging.getLogger(self._name)
275
-
276
-
277
- # ── Built-in Processors ──────────────────────────────────────────────────────
278
-
279
-
280
- def add_log_level(logger: Any, method_name: str, event_dict: EventDict) -> EventDict:
281
- """Add ``level`` key derived from the log method name.
282
-
283
- Example:
284
- ``logger.info(...)`` -> ``event_dict["level"] = "info"``
285
- """
286
- event_dict["level"] = method_name
287
- return event_dict
288
-
289
-
290
- def add_logger_name(logger: Any, method_name: str, event_dict: EventDict) -> EventDict:
291
- """Add ``logger`` key from the underlying logger's name."""
292
- name = getattr(logger, "name", None) or ""
293
- event_dict["logger"] = name
294
- return event_dict
295
-
296
-
297
- class TimeStamper:
298
- """Processor that adds a timestamp to the event dict.
299
-
300
- Args:
301
- fmt: Timestamp format. ``"iso"`` for ISO 8601, ``None`` for a
302
- UNIX float, or a :func:`~datetime.datetime.strftime` format
303
- string. Defaults to ``"iso"``.
304
- utc: If *True*, use UTC; otherwise local time.
305
- key: Dict key for the timestamp. Defaults to ``"timestamp"``.
306
- """
307
-
308
- __slots__ = ("_fmt", "_utc", "_key")
309
-
310
- def __init__(
311
- self,
312
- fmt: str | None = "iso",
313
- utc: bool = True,
314
- key: str = "timestamp",
315
- ) -> None:
316
- self._fmt = fmt
317
- self._utc = utc
318
- self._key = key
319
-
320
- def __call__(
321
- self, logger: Any, method_name: str, event_dict: EventDict
322
- ) -> EventDict:
323
- now = (
324
- datetime.datetime.now(datetime.timezone.utc)
325
- if self._utc
326
- else datetime.datetime.now()
327
- )
328
- if self._fmt is None:
329
- event_dict[self._key] = now.timestamp()
330
- elif self._fmt == "iso":
331
- event_dict[self._key] = now.isoformat()
332
- else:
333
- event_dict[self._key] = now.strftime(self._fmt)
334
- return event_dict
335
-
336
-
337
- def format_exc_info(logger: Any, method_name: str, event_dict: EventDict) -> EventDict:
338
- """Replace ``exc_info`` with a formatted ``exception`` string.
339
-
340
- If ``exc_info`` is *True*, captures the current exception via
341
- :func:`sys.exc_info`. If it is an exception tuple, formats it
342
- directly. The ``exc_info`` key is removed and replaced with
343
- ``exception``.
344
- """
345
- exc_info = event_dict.pop("exc_info", None)
346
- if exc_info is None or exc_info is False:
347
- return event_dict
348
-
349
- if exc_info is True:
350
- exc_info = sys.exc_info()
351
-
352
- if isinstance(exc_info, BaseException):
353
- exc_info = (type(exc_info), exc_info, exc_info.__traceback__)
354
-
355
- if isinstance(exc_info, tuple) and exc_info[0] is not None:
356
- event_dict["exception"] = "".join(
357
- traceback.format_exception(*exc_info)
358
- ).rstrip()
359
-
360
- return event_dict
361
-
362
-
363
- # ── Renderers (final processors) ─────────────────────────────────────────────
364
-
365
-
366
- class KeyValueRenderer:
367
- """Render the event dict as ``key=value`` pairs.
368
-
369
- Args:
370
- key_order: Keys to render first, in this order.
371
- sort_keys: Sort remaining keys alphabetically.
372
- drop_missing: Skip *key_order* keys that are absent from the dict.
373
- """
374
-
375
- __slots__ = ("_key_order", "_sort_keys", "_drop_missing")
376
-
377
- def __init__(
378
- self,
379
- key_order: list[str] | None = None,
380
- sort_keys: bool = False,
381
- drop_missing: bool = True,
382
- ) -> None:
383
- self._key_order = key_order or []
384
- self._sort_keys = sort_keys
385
- self._drop_missing = drop_missing
386
-
387
- def __call__(self, logger: Any, method_name: str, event_dict: EventDict) -> str:
388
- ordered: list[tuple[str, Any]] = []
389
- remaining = dict(event_dict)
390
-
391
- for key in self._key_order:
392
- if key in remaining:
393
- ordered.append((key, remaining.pop(key)))
394
- elif not self._drop_missing:
395
- ordered.append((key, None))
396
-
397
- rest = sorted(remaining.items()) if self._sort_keys else list(remaining.items())
398
- ordered.extend(rest)
399
-
400
- parts = [
401
- f"{k}={v!r}" if not isinstance(v, str) else f"{k}={v}" for k, v in ordered
402
- ]
403
- return " ".join(parts)
404
-
405
-
406
- class JSONRenderer:
407
- """Render the event dict as a JSON string.
408
-
409
- Args:
410
- serializer: JSON serialization function. Defaults to
411
- :func:`json.dumps`.
412
- **dumps_kw: Extra keyword arguments passed to *serializer*.
413
- """
414
-
415
- __slots__ = ("_serializer", "_dumps_kw")
416
-
417
- def __init__(
418
- self,
419
- serializer: Callable[..., str] = _json.dumps,
420
- **dumps_kw: Any,
421
- ) -> None:
422
- self._serializer = serializer
423
- self._dumps_kw = dumps_kw
424
- if "default" not in self._dumps_kw:
425
- self._dumps_kw["default"] = _json_default
426
-
427
- def __call__(self, logger: Any, method_name: str, event_dict: EventDict) -> str:
428
- return self._serializer(event_dict, **self._dumps_kw)
429
-
430
-
431
- def _json_default(obj: Any) -> Any:
432
- """Fallback serializer for objects that ``json.dumps`` cannot handle."""
433
- if isinstance(obj, datetime.datetime):
434
- return obj.isoformat()
435
- if isinstance(obj, datetime.date):
436
- return obj.isoformat()
437
- if isinstance(obj, set | frozenset):
438
- return sorted(obj, key=str)
439
- if isinstance(obj, bytes):
440
- return obj.decode("utf-8", errors="replace")
441
- return str(obj)
442
-
443
-
444
- class ConsoleRenderer:
445
- """Render the event dict as colorized, loguru-style console output.
446
-
447
- Output format::
448
-
449
- 2026-03-27 14:30:00.123 | INFO | event message key=val key=val
450
-
451
- Args:
452
- colors: Enable ANSI color codes. *None* auto-detects terminal
453
- support.
454
- pad_event: Pad the event field to this width for alignment.
455
- level_styles: Override per-level ANSI color strings.
456
- """
457
-
458
- __slots__ = ("_colors", "_pad_event", "_level_styles")
459
-
460
- def __init__(
461
- self,
462
- colors: bool | None = None,
463
- pad_event: int = 30,
464
- level_styles: dict[str, str] | None = None,
465
- ) -> None:
466
- self._colors = _supports_color() if colors is None else colors
467
- self._pad_event = pad_event
468
- self._level_styles = level_styles or _LEVEL_STYLES
469
-
470
- def __call__(self, logger: Any, method_name: str, event_dict: EventDict) -> str:
471
- # Extract well-known keys
472
- event = str(event_dict.pop("event", ""))
473
- level = event_dict.pop("level", method_name)
474
- timestamp = event_dict.pop("timestamp", None)
475
- event_dict.pop("logger", None)
476
- exception = event_dict.pop("exception", None)
477
-
478
- # Build timestamp string
479
- if timestamp is None:
480
- now = datetime.datetime.now()
481
- ms = now.microsecond // 1000
482
- ts_str = now.strftime("%Y-%m-%d %H:%M:%S.") + f"{ms:03d}"
483
- elif isinstance(timestamp, str):
484
- # Try to format ISO timestamps more compactly
485
- ts_str = _compact_iso(timestamp)
486
- elif isinstance(timestamp, float):
487
- dt = datetime.datetime.fromtimestamp(timestamp)
488
- ts_str = dt.strftime("%Y-%m-%d %H:%M:%S.") + f"{dt.microsecond // 1000:03d}"
489
- else:
490
- ts_str = str(timestamp)
491
-
492
- # Build level label
493
- level_str = _LEVEL_LABELS.get(level, f"{level.upper():<8s}")
494
-
495
- # Build key=value pairs from remaining context
496
- kv_parts: list[str] = []
497
- for k, v in event_dict.items():
498
- kv_parts.append(f"{k}={v!r}" if not isinstance(v, str) else f"{k}={v}")
499
- kv_str = " ".join(kv_parts)
500
-
501
- # Pad event
502
- padded_event = event.ljust(self._pad_event) if kv_str else event
503
-
504
- # Assemble
505
- if self._colors:
506
- msg_color = self._level_styles.get(level, _Colors.WHITE)
507
- label_color = _LEVEL_LABEL_STYLES.get(level, _Colors.WHITE)
508
-
509
- line = (
510
- f"{_Colors.GREEN}{ts_str}{_Colors.RESET} | "
511
- f"{label_color}{_Colors.BOLD}{level_str}{_Colors.RESET} | "
512
- f"{msg_color}{padded_event}{_Colors.RESET}"
513
- )
514
- if kv_str:
515
- line += f" {_Colors.DIM}{kv_str}{_Colors.RESET}"
516
- if exception:
517
- line += f"\n{_Colors.RED}{exception}{_Colors.RESET}"
518
- else:
519
- line = f"{ts_str} | {level_str} | {padded_event}"
520
- if kv_str:
521
- line += f" {kv_str}"
522
- if exception:
523
- line += f"\n{exception}"
524
-
525
- return line
526
-
527
-
528
- def _compact_iso(ts: str) -> str:
529
- """Convert an ISO 8601 timestamp to ``YYYY-MM-DD HH:MM:SS.mmm`` format."""
530
- try:
531
- dt = datetime.datetime.fromisoformat(ts)
532
- return dt.strftime("%Y-%m-%d %H:%M:%S.") + f"{dt.microsecond // 1000:03d}"
533
- except (ValueError, AttributeError):
534
- return ts
535
-
536
-
537
- # ── BoundLogger ──────────────────────────────────────────────────────────────
538
-
539
-
540
- class BoundLogger:
541
- """A logger that carries bound context through a processor pipeline.
542
-
543
- Do not instantiate directly; use :func:`get_logger` or
544
- :func:`wrap_logger` instead.
545
-
546
- Args:
547
- logger: The underlying logger instance (e.g. ``PrintLogger``).
548
- processors: Ordered list of processors to run on each log event.
549
- context: Initial context dictionary.
550
- """
551
-
552
- __slots__ = ("_logger", "_processors", "_context")
553
-
554
- def __init__(
555
- self,
556
- logger: Any,
557
- processors: list[Processor],
558
- context: dict[str, Any],
559
- ) -> None:
560
- self._logger = logger
561
- self._processors = processors
562
- self._context = context
563
-
564
- def bind(self, **new_values: Any) -> BoundLogger:
565
- """Return a new logger with *new_values* merged into the context."""
566
- new_ctx = {**self._context, **new_values}
567
- return BoundLogger(self._logger, self._processors, new_ctx)
568
-
569
- def unbind(self, *keys: str) -> BoundLogger:
570
- """Return a new logger with *keys* removed from the context."""
571
- new_ctx = {k: v for k, v in self._context.items() if k not in keys}
572
- return BoundLogger(self._logger, self._processors, new_ctx)
573
-
574
- def new(self, **new_values: Any) -> BoundLogger:
575
- """Return a new logger with *new_values* replacing the context."""
576
- return BoundLogger(self._logger, self._processors, dict(new_values))
577
-
578
- # ── Log methods ──
579
-
580
- def debug(self, event: str | None = None, /, **kw: Any) -> None:
581
- self._process("debug", event, kw)
582
-
583
- def info(self, event: str | None = None, /, **kw: Any) -> None:
584
- self._process("info", event, kw)
585
-
586
- def warning(self, event: str | None = None, /, **kw: Any) -> None:
587
- self._process("warning", event, kw)
588
-
589
- def warn(self, event: str | None = None, /, **kw: Any) -> None:
590
- self._process("warning", event, kw)
591
-
592
- def error(self, event: str | None = None, /, **kw: Any) -> None:
593
- self._process("error", event, kw)
594
-
595
- def critical(self, event: str | None = None, /, **kw: Any) -> None:
596
- self._process("critical", event, kw)
597
-
598
- def fatal(self, event: str | None = None, /, **kw: Any) -> None:
599
- self._process("critical", event, kw)
600
-
601
- def exception(self, event: str | None = None, /, **kw: Any) -> None:
602
- kw.setdefault("exc_info", True)
603
- self._process("error", event, kw)
604
-
605
- def log(self, level: int, event: str | None = None, /, **kw: Any) -> None:
606
- method_name = _LEVEL_TO_NAME.get(level, "info")
607
- self._process(method_name, event, kw)
608
-
609
- # ── Internal ──
610
-
611
- def _process(self, method_name: str, event: str | None, kw: dict[str, Any]) -> None:
612
- """Merge context, run processors, and emit via the underlying logger."""
613
- event_dict: EventDict = {**self._context, **kw}
614
- if event is not None:
615
- event_dict["event"] = event
616
- elif "event" not in event_dict:
617
- event_dict["event"] = ""
618
-
619
- try:
620
- for proc in self._processors:
621
- event_dict_or_str = proc(self._logger, method_name, event_dict)
622
- if isinstance(event_dict_or_str, str):
623
- # Final renderer returned a string -- emit and stop.
624
- _emit(self._logger, method_name, event_dict_or_str)
625
- return
626
- event_dict = event_dict_or_str
627
- except DropEvent:
628
- return
629
-
630
- # If no processor returned a string, emit the repr of event_dict.
631
- _emit(self._logger, method_name, str(event_dict))
632
-
633
-
634
- def _emit(logger: Any, method_name: str, message: str) -> None:
635
- """Dispatch *message* to the underlying logger."""
636
- if isinstance(logger, logging.Logger):
637
- level = _NAME_TO_LEVEL.get(method_name, logging.INFO)
638
- logger.log(level, "%s", message)
639
- else:
640
- func = getattr(logger, method_name, None) or getattr(logger, "msg", None)
641
- if func:
642
- func(message)
643
-
644
-
645
- # ── Configuration ────────────────────────────────────────────────────────────
646
-
647
-
648
- @dataclasses.dataclass
649
- class _Configuration:
650
- """Global structlog configuration."""
651
-
652
- processors: list[Processor]
653
- wrapper_class: type[BoundLogger]
654
- context_class: type
655
- logger_factory: LoggerFactory
656
- cache_logger_on_first_use: bool
657
-
658
-
659
- def _make_defaults() -> _Configuration:
660
- return _Configuration(
661
- processors=[add_log_level, TimeStamper(), ConsoleRenderer()],
662
- wrapper_class=BoundLogger,
663
- context_class=dict,
664
- logger_factory=PrintLoggerFactory(),
665
- cache_logger_on_first_use=True,
666
- )
667
-
668
-
669
- _config: _Configuration = _make_defaults()
670
- _logger_cache: dict[Any, BoundLogger] = {}
671
-
672
-
673
- def configure(
674
- processors: list[Processor] | None = None,
675
- wrapper_class: type[BoundLogger] | None = None,
676
- context_class: type[dict] | None = None,
677
- logger_factory: LoggerFactory | None = None,
678
- cache_logger_on_first_use: bool | None = None,
679
- ) -> None:
680
- """Override the global configuration.
681
-
682
- Only non-*None* arguments are changed. Call :func:`reset_defaults` to
683
- restore factory settings.
684
-
685
- Args:
686
- processors: Ordered processor list.
687
- wrapper_class: BoundLogger subclass to use.
688
- context_class: Dict-like class for context storage.
689
- logger_factory: Factory for the underlying logger.
690
- cache_logger_on_first_use: Cache loggers returned by
691
- :func:`get_logger`.
692
- """
693
- global _config
694
- _logger_cache.clear()
695
- p = _config
696
- _config = _Configuration(
697
- processors=(processors if processors is not None else p.processors),
698
- wrapper_class=(wrapper_class if wrapper_class is not None else p.wrapper_class),
699
- context_class=(context_class if context_class is not None else p.context_class),
700
- logger_factory=(
701
- logger_factory if logger_factory is not None else p.logger_factory
702
- ),
703
- cache_logger_on_first_use=(
704
- cache_logger_on_first_use
705
- if cache_logger_on_first_use is not None
706
- else p.cache_logger_on_first_use
707
- ),
708
- )
709
-
710
-
711
- def reset_defaults() -> None:
712
- """Restore the global configuration to factory defaults."""
713
- global _config
714
- _logger_cache.clear()
715
- _config = _make_defaults()
716
-
717
-
718
- def get_config() -> _Configuration:
719
- """Return the current global configuration (read-only snapshot)."""
720
- return _config
721
-
722
-
723
- # ── Logger Creation ──────────────────────────────────────────────────────────
724
-
725
-
726
- def get_logger(*args: Any, **initial_values: Any) -> BoundLogger:
727
- """Create a :class:`BoundLogger` using the global configuration.
728
-
729
- Positional arguments are forwarded to the logger factory (e.g. a
730
- logger name). Keyword arguments become the initial bound context.
731
-
732
- Returns:
733
- A configured :class:`BoundLogger`.
734
- """
735
- cache_key = args if not initial_values else None
736
-
737
- if cache_key is not None and _config.cache_logger_on_first_use:
738
- cached = _logger_cache.get(cache_key)
739
- if cached is not None:
740
- return cached
741
-
742
- underlying = _config.logger_factory(*args)
743
- ctx = (
744
- _config.context_class(initial_values)
745
- if initial_values
746
- else _config.context_class()
747
- )
748
- bound = _config.wrapper_class(
749
- logger=underlying,
750
- processors=list(_config.processors),
751
- context=ctx,
752
- )
753
-
754
- if cache_key is not None and _config.cache_logger_on_first_use:
755
- _logger_cache[cache_key] = bound
756
-
757
- return bound
758
-
759
-
760
- def wrap_logger(
761
- logger: Any,
762
- processors: list[Processor] | None = None,
763
- **initial_values: Any,
764
- ) -> BoundLogger:
765
- """Wrap an existing logger with a processor pipeline.
766
-
767
- Args:
768
- logger: Any object with ``debug``/``info``/... methods.
769
- processors: Processor list. Defaults to the global config.
770
- **initial_values: Initial bound context.
771
-
772
- Returns:
773
- A :class:`BoundLogger` wrapping *logger*.
774
- """
775
- procs = processors if processors is not None else list(_config.processors)
776
- ctx = dict(initial_values)
777
- return BoundLogger(logger=logger, processors=procs, context=ctx)
778
-
779
-
780
- # ── Convenience Setup ────────────────────────────────────────────────────────
781
-
782
-
783
- def _resolve_level(level: int | str) -> int:
784
- """Convert a level name or int to a logging level int."""
785
- if isinstance(level, int):
786
- return level
787
- return _NAME_TO_LEVEL.get(level.lower(), logging.INFO)
788
-
789
-
790
- def setup_logging(
791
- level: int | str = logging.INFO,
792
- renderer: str = "console",
793
- colors: bool | None = None,
794
- processors: list[Processor] | None = None,
795
- logger_name: str | None = None,
796
- stream: IO[str] | None = None,
797
- ) -> BoundLogger:
798
- """One-call logging setup with stdlib integration.
799
-
800
- Configures both stdlib ``logging`` and the structlog processor
801
- pipeline in a single call.
802
-
803
- Args:
804
- level: Log level (name or int). Defaults to ``INFO``.
805
- renderer: Output renderer: ``"console"``, ``"json"``, or ``"kv"``.
806
- colors: Enable ANSI colors. *None* auto-detects.
807
- processors: Custom processor list. Overrides *renderer* if given.
808
- logger_name: stdlib logger name.
809
- stream: Output stream. Defaults to ``sys.stderr``.
810
-
811
- Returns:
812
- A ready-to-use :class:`BoundLogger`.
813
- """
814
- resolved_level = _resolve_level(level)
815
- out = stream or sys.stderr
816
-
817
- if processors is None:
818
- base: list[Processor] = [add_log_level, TimeStamper()]
819
- if renderer == "json":
820
- base.append(JSONRenderer())
821
- elif renderer == "kv":
822
- base.append(KeyValueRenderer(key_order=["event", "level", "timestamp"]))
823
- else:
824
- base.append(ConsoleRenderer(colors=colors))
825
- processors = base
826
-
827
- # Configure stdlib logging to pass through rendered strings.
828
- stdlib_logger = logging.getLogger(logger_name)
829
- stdlib_logger.setLevel(resolved_level)
830
- stdlib_logger.propagate = False
831
-
832
- # Remove existing handlers to avoid duplicate output on repeated calls.
833
- stdlib_logger.handlers.clear()
834
-
835
- handler = logging.StreamHandler(out)
836
- handler.setLevel(resolved_level)
837
- handler.setFormatter(logging.Formatter("%(message)s"))
838
- stdlib_logger.addHandler(handler)
839
-
840
- configure(
841
- processors=processors,
842
- logger_factory=StdlibLoggerFactory(name=logger_name),
843
- )
844
-
845
- return get_logger()
846
-
847
-
848
- # ── Utilities ────────────────────────────────────────────────────────────────
849
-
850
-
851
- def truncate_string(s: str, max_length: int, suffix: str = "...") -> str:
852
- """Truncate *s* to *max_length*, appending a count of remaining chars.
853
-
854
- Args:
855
- s: The string to truncate.
856
- max_length: Maximum number of characters to keep.
857
- suffix: Separator between the kept text and the count.
858
-
859
- Returns:
860
- The original string if short enough, otherwise truncated with a
861
- ``"...[N more chars]"`` suffix.
862
- """
863
- if len(s) <= max_length:
864
- return s
865
- remaining = len(s) - max_length
866
- return f"{s[:max_length]}{suffix}[{remaining} more chars]"
867
-
868
-
869
- def truncate_base64(data_url: str, max_length: int = 100) -> str:
870
- """Truncate base64 data-URLs for cleaner logging.
871
-
872
- Args:
873
- data_url: A ``data:`` URL or any string.
874
- max_length: Maximum base64 payload chars to keep.
875
-
876
- Returns:
877
- The truncated URL, or the original string if not a data-URL.
878
- """
879
- if not data_url.startswith("data:"):
880
- return data_url
881
- if ";base64," in data_url:
882
- header, base64_data = data_url.split(";base64,", 1)
883
- if len(base64_data) > max_length:
884
- remaining = len(base64_data) - max_length
885
- return (
886
- f"{header};base64,{base64_data[:max_length]}...[{remaining} more chars]"
887
- )
888
- return data_url
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
src/veilrender/_vendor/useragent.py DELETED
@@ -1,475 +0,0 @@
1
- # /// zerodep
2
- # version = "0.1.0"
3
- # deps = []
4
- # tier = "simple"
5
- # category = "network"
6
- # note = "Install/update via `zerodep add useragent`"
7
- # ///
8
-
9
- """Lightweight User-Agent generator for Chrome/Edge with Client Hints.
10
-
11
- Part of zerodep: https://github.com/Oaklight/zerodep
12
- Copyright (c) 2026 Peng Ding. MIT License.
13
-
14
- Generates realistic browser UA strings and matching ``Sec-CH-UA-*`` headers.
15
- Covers Windows, macOS, Linux (desktop) and Android (mobile) platforms with
16
- Chrome and Edge browsers only -- this is intentionally minimal.
17
-
18
- Inspired by `ua-generator <https://github.com/iamdual/ua-generator>`_ (Apache-2.0).
19
-
20
- Zero external dependencies -- stdlib ``random`` only.
21
-
22
- Basic usage::
23
-
24
- from useragent import generate
25
-
26
- ua = generate(browser="chrome", device="desktop")
27
- print(ua.text) # full User-Agent string
28
- print(ua.headers.get()) # dict with UA + Client Hints headers
29
- """
30
-
31
- from __future__ import annotations
32
-
33
- import random
34
- from typing import Sequence, Union
35
-
36
- __all__ = ["UserAgent", "generate"]
37
-
38
- __version__ = "0.1.0"
39
-
40
- # ---------------------------------------------------------------------------
41
- # Version data
42
- # ---------------------------------------------------------------------------
43
-
44
- # (major, build) pairs. Patch is randomised at generation time.
45
- # Sources:
46
- # Chrome -- https://chromereleases.googleblog.com/search/label/Stable%20updates
47
- # Edge -- https://learn.microsoft.com/en-us/deployedge/microsoft-edge-release-schedule
48
-
49
- _CHROME_VERSIONS: list[tuple[int, int]] = [
50
- (120, 6099),
51
- (121, 6167),
52
- (122, 6261),
53
- (123, 6312),
54
- (124, 6367),
55
- (125, 6422),
56
- (126, 6478),
57
- (127, 6533),
58
- (128, 6613),
59
- (129, 6668),
60
- (130, 6723),
61
- (131, 6778),
62
- (132, 6834),
63
- (133, 6943),
64
- (134, 6998),
65
- (135, 7049),
66
- (136, 7103),
67
- (137, 7151),
68
- (138, 7204),
69
- (139, 7258),
70
- (140, 7339),
71
- (141, 7390),
72
- (142, 7444),
73
- (143, 7499),
74
- (144, 7559),
75
- (145, 7632),
76
- (146, 7680),
77
- ]
78
-
79
- _EDGE_VERSIONS: list[tuple[int, int]] = [
80
- (120, 2210),
81
- (121, 2277),
82
- (122, 2365),
83
- (123, 2420),
84
- (124, 2478),
85
- (125, 2535),
86
- (126, 2592),
87
- (127, 2651),
88
- (128, 2739),
89
- (129, 2792),
90
- (130, 2849),
91
- (131, 2903),
92
- (132, 2957),
93
- (133, 3065),
94
- (134, 3124),
95
- (135, 3179),
96
- (136, 3240),
97
- (137, 3296),
98
- (138, 3351),
99
- (139, 3405),
100
- (140, 3485),
101
- (141, 3537),
102
- (142, 3595),
103
- (143, 3650),
104
- (144, 3719),
105
- (145, 3800),
106
- (146, 3856),
107
- ]
108
-
109
- # Windows NT versions: (nt_major, nt_minor, ch_platform_range)
110
- _WINDOWS_VERSIONS: list[tuple[float, tuple[int, int]]] = [
111
- (10.0, (1, 10)), # Windows 10
112
- (10.0, (13, 16)), # Windows 11
113
- ]
114
-
115
- # macOS versions: (major, minor, max_build)
116
- _MACOS_VERSIONS: list[tuple[int, int, int]] = [
117
- (13, 6, 9),
118
- (13, 7, 8),
119
- (14, 4, 1),
120
- (14, 5, 0),
121
- (14, 6, 1),
122
- (14, 7, 8),
123
- (14, 8, 4),
124
- (15, 0, 1),
125
- (15, 1, 1),
126
- (15, 2, 1),
127
- (15, 3, 1),
128
- (15, 4, 1),
129
- (15, 5, 0),
130
- (15, 6, 1),
131
- (15, 7, 4),
132
- (26, 0, 1),
133
- (26, 1, 0),
134
- (26, 2, 0),
135
- (26, 3, 2),
136
- ]
137
-
138
- # Android model strings (Samsung subset -- most common vendor)
139
- _ANDROID_MODELS: tuple[str, ...] = (
140
- "SM-G991B",
141
- "SM-G996B",
142
- "SM-G998B",
143
- "SM-A526B",
144
- "SM-A536B",
145
- "SM-S901B",
146
- "SM-S906B",
147
- "SM-S908B",
148
- "SM-S911B",
149
- "SM-S916B",
150
- "SM-S918B",
151
- "SM-S921B",
152
- "SM-S926B",
153
- "SM-S928B",
154
- "SM-A546B",
155
- "SM-A556B",
156
- "SM-A346B",
157
- "SM-A256B",
158
- "SM-A156B",
159
- "SM-G781B",
160
- )
161
-
162
- _DESKTOP_PLATFORMS = ("windows", "macos", "linux")
163
- _MOBILE_PLATFORMS = ("android",)
164
- _ALL_PLATFORMS = _DESKTOP_PLATFORMS + _MOBILE_PLATFORMS
165
-
166
- _WEBKIT = "537.36"
167
-
168
-
169
- # ---------------------------------------------------------------------------
170
- # Internal helpers
171
- # ---------------------------------------------------------------------------
172
-
173
-
174
- def _pick_chrome_version() -> tuple[int, int, int, int]:
175
- """Return (major, minor=0, build, patch)."""
176
- major, build = random.choice(_CHROME_VERSIONS)
177
- return (major, 0, build, random.randint(0, 255))
178
-
179
-
180
- def _pick_edge_version() -> tuple[int, int, int, int]:
181
- major, build = random.choice(_EDGE_VERSIONS)
182
- return (major, 0, build, random.randint(0, 99))
183
-
184
-
185
- def _fmt_ver(v: tuple[int, ...], n: int = 4, sep: str = ".") -> str:
186
- """Format version tuple to string, padding with 0s up to *n* parts."""
187
- parts = list(v[:n])
188
- while len(parts) < n:
189
- parts.append(0)
190
- return sep.join(str(p) for p in parts)
191
-
192
-
193
- def _pick_platform(device: str | None) -> str:
194
- if device == "desktop":
195
- return random.choice(_DESKTOP_PLATFORMS)
196
- if device == "mobile":
197
- return random.choice(_MOBILE_PLATFORMS)
198
- return random.choice(_ALL_PLATFORMS)
199
-
200
-
201
- def _build_ua_string(
202
- browser: str,
203
- platform: str,
204
- ver: tuple[int, int, int, int],
205
- ) -> str:
206
- """Build a User-Agent string from browser/platform/version."""
207
- chrome_str = _fmt_ver(ver)
208
-
209
- if platform == "windows":
210
- nt = random.choice(_WINDOWS_VERSIONS)
211
- nt_str = f"{nt[0]:.1f}".replace(".0", ".0") # "10.0"
212
- base = (
213
- f"Mozilla/5.0 (Windows NT {nt_str}; Win64; x64) "
214
- f"AppleWebKit/{_WEBKIT} (KHTML, like Gecko) "
215
- f"Chrome/{chrome_str} Safari/{_WEBKIT}"
216
- )
217
- if browser == "edge":
218
- base += f" Edg/{chrome_str}"
219
- return base
220
-
221
- if platform == "linux":
222
- tpl = random.choice(
223
- (
224
- f"Mozilla/5.0 (X11; Linux x86_64) AppleWebKit/{_WEBKIT} "
225
- f"(KHTML, like Gecko) Chrome/{chrome_str} Safari/{_WEBKIT}",
226
- f"Mozilla/5.0 (X11; Ubuntu; Linux x86_64) AppleWebKit/{_WEBKIT} "
227
- f"(KHTML, like Gecko) Chrome/{chrome_str} Safari/{_WEBKIT}",
228
- )
229
- )
230
- if browser == "edge":
231
- tpl += f" Edg/{chrome_str}"
232
- return tpl
233
-
234
- if platform == "macos":
235
- mv = random.choice(_MACOS_VERSIONS)
236
- build = random.randint(0, mv[2]) if mv[2] > 0 else 0
237
- mac_str = f"{mv[0]}_{mv[1]}"
238
- if build:
239
- mac_str += f"_{build}"
240
- base = (
241
- f"Mozilla/5.0 (Macintosh; Intel Mac OS X {mac_str}) "
242
- f"AppleWebKit/{_WEBKIT} (KHTML, like Gecko) "
243
- f"Chrome/{chrome_str} Safari/{_WEBKIT}"
244
- )
245
- if browser == "edge":
246
- base += f" Edg/{chrome_str}"
247
- return base
248
-
249
- if platform == "android":
250
- android_ver = random.randint(12, 16)
251
- model = random.choice(_ANDROID_MODELS)
252
- base = (
253
- f"Mozilla/5.0 (Linux; Android {android_ver}; {model}) "
254
- f"AppleWebKit/{_WEBKIT} (KHTML, like Gecko) "
255
- f"Chrome/{chrome_str} Mobile Safari/{_WEBKIT}"
256
- )
257
- if browser == "edge":
258
- base += f" EdgA/{chrome_str}"
259
- return base
260
-
261
- raise ValueError(f"Unsupported platform: {platform}")
262
-
263
-
264
- # ---------------------------------------------------------------------------
265
- # Client Hints serialization
266
- # ---------------------------------------------------------------------------
267
-
268
-
269
- def _ch_bool(val: bool) -> str:
270
- return "?1" if val else "?0"
271
-
272
-
273
- def _ch_string(val: str) -> str:
274
- return f'"{val}"'
275
-
276
-
277
- def _ch_brand_list(brands: list[dict[str, str]]) -> str:
278
- return ", ".join(f'"{b["brand"]}";v="{b["version"]}"' for b in brands)
279
-
280
-
281
- # ---------------------------------------------------------------------------
282
- # Public API
283
- # ---------------------------------------------------------------------------
284
-
285
-
286
- class UserAgent:
287
- """A generated user-agent with matching Client Hints headers.
288
-
289
- Attributes:
290
- browser: Browser name (``"chrome"`` or ``"edge"``).
291
- platform: Platform name (``"windows"``, ``"macos"``, ``"linux"``,
292
- or ``"android"``).
293
- version: 4-tuple ``(major, minor, build, patch)``.
294
- text: The full User-Agent string.
295
- headers: A :class:`_Headers` instance for Client Hints.
296
-
297
- Example::
298
-
299
- ua = generate(browser=["chrome", "edge"])
300
- ua.headers.accept_ch("Sec-CH-UA-Platform-Version")
301
- headers = ua.headers.get()
302
- """
303
-
304
- def __init__(
305
- self,
306
- *,
307
- browser: str,
308
- platform: str,
309
- version: tuple[int, int, int, int],
310
- ua_string: str,
311
- ) -> None:
312
- self.browser = browser
313
- self.platform = platform
314
- self.version = version
315
- self.text = ua_string
316
- self.headers = _Headers(self)
317
-
318
- # -- Client Hints data methods --
319
-
320
- def _is_mobile(self) -> bool:
321
- return self.platform in _MOBILE_PLATFORMS
322
-
323
- def _ch_platform_name(self) -> str:
324
- mapping = {
325
- "windows": "Windows",
326
- "macos": "macOS",
327
- "linux": "Linux",
328
- "android": "Android",
329
- }
330
- return mapping.get(self.platform, self.platform.title())
331
-
332
- def _ch_platform_version(self) -> str:
333
- if self.platform == "windows":
334
- lo, hi = random.choice(_WINDOWS_VERSIONS)[1]
335
- return f"{random.randint(lo, hi)}.0.0"
336
- if self.platform == "macos":
337
- mv = random.choice(_MACOS_VERSIONS)
338
- return f"{mv[0]}.{mv[1]}.{random.randint(0, max(mv[2], 1))}"
339
- if self.platform == "android":
340
- return f"{random.randint(12, 16)}.0.0"
341
- # Linux
342
- return ""
343
-
344
- def _ch_brands(self, full_version: bool = False) -> list[dict[str, str]]:
345
- ver_str = _fmt_ver(self.version) if full_version else str(self.version[0])
346
- filler_ver = "99.0.0.0" if full_version else "99"
347
- brands: list[dict[str, str]] = [{"brand": "Not A(Brand", "version": filler_ver}]
348
- if self.browser == "chrome":
349
- brands.append({"brand": "Chromium", "version": ver_str})
350
- brands.append({"brand": "Google Chrome", "version": ver_str})
351
- elif self.browser == "edge":
352
- brands.append({"brand": "Chromium", "version": ver_str})
353
- brands.append({"brand": "Microsoft Edge", "version": ver_str})
354
- return brands
355
-
356
- def _ch_architecture(self) -> str:
357
- if self.platform in ("android",):
358
- return "arm"
359
- if self.platform == "macos":
360
- return random.choice(("arm", "x86", "arm", "arm"))
361
- return "x86"
362
-
363
- def _ch_bitness(self) -> str:
364
- if self.platform == "android":
365
- return random.choice(("32", "64", "32", "32"))
366
- return "64"
367
-
368
- def _ch_model(self) -> str:
369
- if self.platform == "android":
370
- return random.choice(_ANDROID_MODELS)
371
- return ""
372
-
373
- def __str__(self) -> str:
374
- return self.text
375
-
376
- def __repr__(self) -> str:
377
- return f"UserAgent(browser={self.browser!r}, platform={self.platform!r})"
378
-
379
-
380
- class _Headers:
381
- """Lazy header builder matching the ``ua_generator.Headers`` interface."""
382
-
383
- def __init__(self, ua: UserAgent) -> None:
384
- self._ua = ua
385
- self._headers: dict[str, str] = {}
386
- self._initialised = False
387
-
388
- def _reset(self) -> None:
389
- self._initialised = True
390
- self._headers = {"user-agent": self._ua.text}
391
- # Low-entropy hints (always included for Chromium)
392
- self._add("sec-ch-ua")
393
- self._add("sec-ch-ua-mobile")
394
- self._add("sec-ch-ua-platform")
395
-
396
- def _add(self, key: str) -> None:
397
- ua = self._ua
398
- if key == "sec-ch-ua":
399
- self._headers[key] = _ch_brand_list(ua._ch_brands(full_version=False))
400
- elif key == "sec-ch-ua-full-version-list":
401
- self._headers[key] = _ch_brand_list(ua._ch_brands(full_version=True))
402
- elif key == "sec-ch-ua-platform":
403
- self._headers[key] = _ch_string(ua._ch_platform_name())
404
- elif key == "sec-ch-ua-platform-version":
405
- self._headers[key] = _ch_string(ua._ch_platform_version())
406
- elif key == "sec-ch-ua-mobile":
407
- self._headers[key] = _ch_bool(ua._is_mobile())
408
- elif key == "sec-ch-ua-arch":
409
- self._headers[key] = _ch_string(ua._ch_architecture())
410
- elif key == "sec-ch-ua-bitness":
411
- self._headers[key] = _ch_string(ua._ch_bitness())
412
- elif key == "sec-ch-ua-model":
413
- self._headers[key] = _ch_string(ua._ch_model())
414
-
415
- def accept_ch(self, val: str) -> None:
416
- """Process an ``Accept-CH`` header value and populate matching hints.
417
-
418
- Args:
419
- val: Comma-separated list of hint names
420
- (e.g. ``"Sec-CH-UA-Platform-Version, Sec-CH-UA-Arch"``).
421
- """
422
- self._reset()
423
- for hint in val.split(","):
424
- self._add(hint.strip().lower())
425
-
426
- def get(self) -> dict[str, str]:
427
- """Return all generated headers as a dict."""
428
- if not self._initialised:
429
- self._reset()
430
- return self._headers
431
-
432
-
433
- def generate(
434
- *,
435
- browser: Union[str, Sequence[str]] | None = None,
436
- device: str | None = None,
437
- ) -> UserAgent:
438
- """Generate a random User-Agent with matching Client Hints.
439
-
440
- Args:
441
- browser: Browser name or list of names to pick from.
442
- Supported: ``"chrome"``, ``"edge"``. Defaults to both.
443
- device: Device type -- ``"desktop"`` or ``"mobile"``.
444
- Defaults to random selection across all platforms.
445
-
446
- Returns:
447
- A :class:`UserAgent` instance.
448
-
449
- Raises:
450
- ValueError: If *browser* is not ``"chrome"`` or ``"edge"``.
451
- """
452
- # Resolve browser
453
- if browser is None:
454
- chosen_browser = random.choice(("chrome", "edge"))
455
- elif isinstance(browser, str):
456
- chosen_browser = browser
457
- else:
458
- chosen_browser = random.choice(list(browser))
459
-
460
- if chosen_browser not in ("chrome", "edge"):
461
- raise ValueError(f"Unsupported browser: {chosen_browser!r}")
462
-
463
- # Resolve platform
464
- platform = _pick_platform(device)
465
-
466
- # Pick version
467
- if chosen_browser == "chrome":
468
- ver = _pick_chrome_version()
469
- else:
470
- ver = _pick_edge_version()
471
-
472
- ua_string = _build_ua_string(chosen_browser, platform, ver)
473
- return UserAgent(
474
- browser=chosen_browser, platform=platform, version=ver, ua_string=ua_string
475
- )
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
src/veilrender/_vendor/yaml.py DELETED
@@ -1,1124 +0,0 @@
1
- # /// zerodep
2
- # version = "0.3.1"
3
- # deps = []
4
- # tier = "subsystem"
5
- # category = "serialization"
6
- # note = "Install/update via `zerodep add yaml`"
7
- # ///
8
-
9
- """YAML parser and serializer (common subset) — zero dependencies, stdlib only, Python 3.10+.
10
-
11
- Part of zerodep: https://github.com/Oaklight/zerodep
12
- Copyright (c) 2026 Peng Ding. MIT License.
13
-
14
- Supports the most commonly used YAML features: mappings, sequences,
15
- scalars (str/int/float/bool/null), flow style, block scalars,
16
- multi-document streams, and comments.
17
-
18
- Does NOT implement: anchors/aliases, tags, merge keys, complex keys.
19
-
20
- Example::
21
-
22
- data = load("name: Alice\nage: 30")
23
- # {'name': 'Alice', 'age': 30}
24
- print(dump(data))
25
- # age: 30
26
- # name: Alice
27
- """
28
-
29
- from __future__ import annotations
30
-
31
- import math
32
- import re
33
- from typing import IO, Any, Iterator, overload
34
-
35
- __all__ = [
36
- "YAMLError",
37
- "load",
38
- "load_all",
39
- "dump",
40
- "dump_all",
41
- ]
42
-
43
- # ── Exceptions ─────────────────────────────────────────────────────────────────
44
-
45
-
46
- class YAMLError(Exception):
47
- """Raised when YAML parsing fails."""
48
-
49
-
50
- # ── Scalar type resolution ─────────────────────────────────────────────────────
51
-
52
- _NULL_RE = re.compile(r"\A(?:null|Null|NULL|~)\Z")
53
- _BOOL_TRUE_RE = re.compile(r"\A(?:true|True|TRUE|yes|Yes|YES|on|On|ON)\Z")
54
- _BOOL_FALSE_RE = re.compile(r"\A(?:false|False|FALSE|no|No|NO|off|Off|OFF)\Z")
55
- _INT_RE = re.compile(r"\A[-+]?(?:0|[1-9][0-9_]*)\Z")
56
- _INT_HEX_RE = re.compile(r"\A0x[0-9a-fA-F_]+\Z")
57
- _INT_OCT_RE = re.compile(r"\A0[0-7_]+\Z") # YAML 1.1 octal: 0777 (not 0o777)
58
- _INT_BIN_RE = re.compile(r"\A0b[01_]+\Z")
59
- # YAML 1.1 requires explicit sign (+/-) in exponent when base has decimal point
60
- _FLOAT_RE = re.compile(r"\A[-+]?(?:\.[0-9]+|[0-9]+\.[0-9]*)(?:[eE][-+][0-9]+)?\Z")
61
- _INF_RE = re.compile(r"\A[-+]?\.(?:inf|Inf|INF)\Z")
62
- _NAN_RE = re.compile(r"\A\.(?:nan|NaN|NAN)\Z")
63
-
64
-
65
- def _resolve_scalar(value: str) -> str | int | float | bool | None:
66
- """Resolve a plain (unquoted) scalar string to a typed Python value."""
67
- if not value:
68
- return None
69
- if _NULL_RE.match(value):
70
- return None
71
- if _BOOL_TRUE_RE.match(value):
72
- return True
73
- if _BOOL_FALSE_RE.match(value):
74
- return False
75
- if _INT_RE.match(value):
76
- return int(value.replace("_", ""))
77
- if _INT_HEX_RE.match(value):
78
- return int(value.replace("_", ""), 16)
79
- if _INT_OCT_RE.match(value):
80
- return int(value.replace("_", ""), 8) # YAML 1.1: 0777 -> 511
81
- if _INT_BIN_RE.match(value):
82
- return int(value.replace("_", ""), 2)
83
- if _FLOAT_RE.match(value):
84
- return float(value.replace("_", ""))
85
- if _INF_RE.match(value):
86
- return float("-inf") if value.startswith("-") else float("inf")
87
- if _NAN_RE.match(value):
88
- return float("nan")
89
- return value
90
-
91
-
92
- # ── String unquoting ───────────────────────────────────────────────────────────
93
-
94
- _DQ_ESCAPE_MAP = {
95
- "\\": "\\",
96
- '"': '"',
97
- "n": "\n",
98
- "r": "\r",
99
- "t": "\t",
100
- "0": "\0",
101
- "a": "\a",
102
- "b": "\b",
103
- "e": "\x1b",
104
- "v": "\v",
105
- "/": "/",
106
- " ": " ",
107
- "N": "\x85",
108
- "_": "\xa0",
109
- }
110
-
111
-
112
- def _unescape_double_quoted(s: str) -> str:
113
- """Process escape sequences in a double-quoted YAML string."""
114
- result: list[str] = []
115
- i = 0
116
- while i < len(s):
117
- if s[i] == "\\" and i + 1 < len(s):
118
- nxt = s[i + 1]
119
- if nxt in _DQ_ESCAPE_MAP:
120
- result.append(_DQ_ESCAPE_MAP[nxt])
121
- i += 2
122
- elif nxt == "x" and i + 3 < len(s):
123
- result.append(chr(int(s[i + 2 : i + 4], 16)))
124
- i += 4
125
- elif nxt == "u" and i + 5 < len(s):
126
- result.append(chr(int(s[i + 2 : i + 6], 16)))
127
- i += 6
128
- elif nxt == "U" and i + 9 < len(s):
129
- result.append(chr(int(s[i + 2 : i + 10], 16)))
130
- i += 10
131
- else:
132
- result.append(s[i])
133
- i += 1
134
- else:
135
- result.append(s[i])
136
- i += 1
137
- return "".join(result)
138
-
139
-
140
- def _unquote(s: str) -> str:
141
- """Remove quotes from a YAML scalar and process escapes if needed."""
142
- if len(s) >= 2:
143
- if s[0] == "'" and s[-1] == "'":
144
- # Single-quoted: only '' escapes to '
145
- return s[1:-1].replace("''", "'")
146
- if s[0] == '"' and s[-1] == '"':
147
- return _unescape_double_quoted(s[1:-1])
148
- return s
149
-
150
-
151
- # ── Scanner ────────────────────────────────────────────────────────────────────
152
-
153
-
154
- class _Line:
155
- """A logical line with tracked indentation and line number."""
156
-
157
- __slots__ = ("indent", "text", "lineno")
158
-
159
- def __init__(self, indent: int, text: str, lineno: int):
160
- self.indent = indent
161
- self.text = text
162
- self.lineno = lineno
163
-
164
- def __repr__(self) -> str:
165
- return f"_Line({self.lineno}: indent={self.indent}, {self.text!r})"
166
-
167
-
168
- def _strip_inline_comment(text: str) -> str:
169
- """Remove inline comments from a line, respecting quoted strings."""
170
- in_single = False
171
- in_double = False
172
- i = 0
173
- while i < len(text):
174
- ch = text[i]
175
- if ch == "\\" and in_double and i + 1 < len(text):
176
- i += 2
177
- continue
178
- if ch == "'" and not in_double:
179
- in_single = not in_single
180
- elif ch == '"' and not in_single:
181
- in_double = not in_double
182
- elif ch == "#" and not in_single and not in_double:
183
- # Must be preceded by whitespace to be a comment
184
- if i == 0 or text[i - 1] in (" ", "\t"):
185
- return text[:i].rstrip()
186
- i += 1
187
- return text
188
-
189
-
190
- def _scan(text: str) -> list[_Line]:
191
- """Convert raw YAML text into a list of logical lines."""
192
- lines: list[_Line] = []
193
- for lineno, raw in enumerate(text.splitlines(), 1):
194
- # Preserve completely empty lines for block scalar detection
195
- stripped = raw.lstrip()
196
- if not stripped or stripped[0] == "#":
197
- continue
198
- indent = len(raw) - len(stripped)
199
- # Don't strip comments from block scalar indicators or document markers
200
- if stripped.startswith("---") or stripped.startswith("..."):
201
- lines.append(_Line(indent, stripped, lineno))
202
- else:
203
- cleaned = _strip_inline_comment(stripped)
204
- if cleaned:
205
- lines.append(_Line(indent, cleaned, lineno))
206
- return lines
207
-
208
-
209
- # ── Parser ─────────────────────────────────────────────────────────────────────
210
-
211
-
212
- class _Parser:
213
- """Recursive-descent YAML parser for the common subset."""
214
-
215
- def __init__(self, lines: list[_Line], raw_lines: list[str]):
216
- self._lines = lines
217
- self._raw_lines = raw_lines # original text lines for block scalars
218
- self._pos = 0
219
-
220
- def _peek(self) -> _Line | None:
221
- if self._pos < len(self._lines):
222
- return self._lines[self._pos]
223
- return None
224
-
225
- def _advance(self) -> _Line:
226
- line = self._lines[self._pos]
227
- self._pos += 1
228
- return line
229
-
230
- def _error(self, msg: str, lineno: int | None = None) -> YAMLError:
231
- if lineno is None:
232
- cur = self._peek()
233
- lineno = cur.lineno if cur else -1
234
- return YAMLError(f"line {lineno}: {msg}")
235
-
236
- # ── Document parsing ──
237
-
238
- def parse_stream(self) -> list[Any]:
239
- """Parse the entire stream, returning a list of documents."""
240
- documents: list[Any] = []
241
-
242
- # Skip leading document marker if present
243
- cur = self._peek()
244
- if cur is not None and cur.text == "---":
245
- self._advance()
246
-
247
- while self._pos < len(self._lines):
248
- doc = self._parse_node(-1)
249
- documents.append(doc)
250
-
251
- # Check for document separator
252
- cur = self._peek()
253
- if cur is not None and cur.text in ("---", "..."):
254
- self._advance()
255
- # '...' without following '---' ends the stream
256
- if cur.text == "...":
257
- cur2 = self._peek()
258
- if cur2 is None or cur2.text != "---":
259
- break
260
- self._advance() # skip the ---
261
-
262
- if not documents:
263
- documents.append(None)
264
-
265
- return documents
266
-
267
- def _parse_node(self, parent_indent: int) -> Any:
268
- """Parse a YAML node (mapping, sequence, or scalar)."""
269
- cur = self._peek()
270
- if cur is None:
271
- return None
272
-
273
- # Document end markers
274
- if cur.text in ("---", "..."):
275
- return None
276
-
277
- text = cur.text
278
-
279
- # Flow collections
280
- if text.startswith("{"):
281
- return self._parse_flow_mapping()
282
- if text.startswith("["):
283
- return self._parse_flow_sequence()
284
-
285
- # Block scalar
286
- if text.startswith("|") or text.startswith(">"):
287
- return self._parse_block_scalar()
288
-
289
- # Block sequence
290
- if text.startswith("- ") or text == "-":
291
- return self._parse_block_sequence(cur.indent)
292
-
293
- # Check if it's a mapping (contains ': ' or ends with ':')
294
- if self._is_mapping_line(text):
295
- return self._parse_block_mapping(cur.indent)
296
-
297
- # Plain scalar
298
- self._advance()
299
- return self._parse_scalar_value(text)
300
-
301
- @staticmethod
302
- def _skip_quoted_key(text: str) -> int:
303
- """Return the index after the quoted prefix of *text*.
304
-
305
- If *text* starts with a single- or double-quoted string the returned
306
- index points just past the closing quote. For unquoted text ``0`` is
307
- returned so callers can scan from the beginning.
308
-
309
- Returns ``-1`` when a single-quoted string has no closing quote (the
310
- caller should treat this as "not a mapping line").
311
- """
312
- if text.startswith("'"):
313
- end = text.find("'", 1)
314
- return -1 if end < 0 else end + 1
315
- if text.startswith('"'):
316
- i = 1
317
- while i < len(text):
318
- if text[i] == "\\" and i + 1 < len(text):
319
- i += 2
320
- continue
321
- if text[i] == '"':
322
- return i + 1
323
- i += 1
324
- return 0
325
-
326
- @staticmethod
327
- def _find_mapping_colon(text: str, start: int) -> int:
328
- """Find the position of the mapping separator colon starting from *start*.
329
-
330
- Returns the index of the ``:`` that acts as a mapping separator, or
331
- ``-1`` if none is found. A colon qualifies when it is either the last
332
- character or is immediately followed by a space or tab.
333
- """
334
- i = start
335
- while i < len(text):
336
- if text[i] == ":":
337
- if i + 1 == len(text) or text[i + 1] in (" ", "\t"):
338
- return i
339
- i += 1
340
- return -1
341
-
342
- def _is_mapping_line(self, text: str) -> bool:
343
- """Check if a line represents a mapping key."""
344
- i = self._skip_quoted_key(text)
345
- if i < 0:
346
- return False
347
- return self._find_mapping_colon(text, i) >= 0
348
-
349
- def _split_mapping_line(self, text: str) -> tuple[str, str]:
350
- """Split a mapping line into key and value parts."""
351
- i = self._skip_quoted_key(text)
352
- if i < 0:
353
- return text, ""
354
- colon = self._find_mapping_colon(text, i)
355
- if colon < 0:
356
- return text, ""
357
- if colon + 1 == len(text):
358
- return text[:colon], ""
359
- return text[:colon], text[colon + 2 :].strip()
360
-
361
- # ── Block mapping ──
362
-
363
- def _parse_inline_value(self, raw_value: str, lineno: int) -> Any:
364
- """Parse an inline mapping or sequence value."""
365
- if raw_value.startswith(("{", "[")):
366
- return self._parse_flow_from_text(raw_value)
367
- if raw_value.startswith(("|", ">")):
368
- return self._parse_block_scalar_from_indicator(raw_value, lineno)
369
- return self._parse_scalar_value(raw_value)
370
-
371
- def _at_block_end(self, cur: _Line | None, indent: int) -> bool:
372
- """Return True when the current line should stop a block collection."""
373
- if cur is None or cur.indent < indent:
374
- return True
375
- return cur.text in ("---", "...") or cur.indent != indent
376
-
377
- def _parse_block_mapping(self, indent: int) -> dict:
378
- result: dict[Any, Any] = {}
379
- while True:
380
- cur = self._peek()
381
- if self._at_block_end(cur, indent):
382
- break
383
- assert cur is not None # guaranteed by _at_block_end
384
- if not self._is_mapping_line(cur.text):
385
- break
386
-
387
- self._advance()
388
- raw_key, raw_value = self._split_mapping_line(cur.text)
389
- key = self._parse_scalar_value(raw_key)
390
-
391
- if raw_value:
392
- value = self._parse_inline_value(raw_value, cur.lineno)
393
- else:
394
- nxt = self._peek()
395
- if nxt is None or nxt.indent <= indent or nxt.text in ("---", "..."):
396
- value = None
397
- else:
398
- value = self._parse_node(indent)
399
- result[key] = value
400
- return result
401
-
402
- # ── Block sequence ──
403
-
404
- def _parse_sequence_mapping_item(
405
- self, item_text: str, cur: _Line, indent: int
406
- ) -> dict:
407
- """Parse a mapping that starts on a sequence item line (``- key: val``)."""
408
- raw_key, raw_value = self._split_mapping_line(item_text)
409
- key = self._parse_scalar_value(raw_key)
410
- mapping: dict[Any, Any] = {}
411
-
412
- if raw_value:
413
- mapping[key] = self._parse_inline_value(raw_value, cur.lineno)
414
- else:
415
- nxt = self._peek()
416
- if (
417
- nxt is not None
418
- and nxt.indent > indent
419
- and nxt.text not in ("---", "...")
420
- ):
421
- mapping[key] = self._parse_node(indent)
422
- else:
423
- mapping[key] = None
424
-
425
- # Continue reading mapping entries at deeper indent
426
- nxt = self._peek()
427
- if nxt is not None and nxt.indent > indent and self._is_mapping_line(nxt.text):
428
- rest = self._parse_block_mapping(nxt.indent)
429
- mapping.update(rest)
430
-
431
- return mapping
432
-
433
- def _parse_sequence_item(self, item_text: str, cur: _Line, indent: int) -> Any:
434
- """Parse the value part of a single sequence item."""
435
- if not item_text:
436
- nxt = self._peek()
437
- if nxt is None or nxt.indent <= indent or nxt.text in ("---", "..."):
438
- return None
439
- return self._parse_node(indent)
440
- if item_text.startswith(("{", "[")):
441
- return self._parse_flow_from_text(item_text)
442
- if self._is_mapping_line(item_text):
443
- return self._parse_sequence_mapping_item(item_text, cur, indent)
444
- return self._parse_scalar_value(item_text)
445
-
446
- def _parse_block_sequence(self, indent: int) -> list:
447
- result: list[Any] = []
448
- while True:
449
- cur = self._peek()
450
- if self._at_block_end(cur, indent):
451
- break
452
- assert cur is not None
453
- if not (cur.text.startswith("- ") or cur.text == "-"):
454
- break
455
-
456
- self._advance()
457
- item_text = cur.text[2:].strip() if cur.text.startswith("- ") else ""
458
- result.append(self._parse_sequence_item(item_text, cur, indent))
459
-
460
- return result
461
-
462
- # ── Block scalars ──
463
-
464
- def _parse_block_scalar(self) -> str:
465
- cur = self._advance()
466
- return self._parse_block_scalar_from_indicator(cur.text, cur.lineno)
467
-
468
- @staticmethod
469
- def _parse_chomping_indicator(header: str) -> tuple[str, int]:
470
- """Parse the block scalar header for chomping mode and explicit indent.
471
-
472
- Args:
473
- header: The portion of the indicator line after ``|`` or ``>``.
474
-
475
- Returns:
476
- A ``(chomp, explicit_indent)`` tuple.
477
- """
478
- chomp = "clip"
479
- explicit_indent = 0
480
- for ch in header:
481
- if ch == "-":
482
- chomp = "strip"
483
- elif ch == "+":
484
- chomp = "keep"
485
- elif ch.isdigit():
486
- explicit_indent = int(ch)
487
- return chomp, explicit_indent
488
-
489
- def _collect_scalar_lines(self, raw_lineno: int, explicit_indent: int) -> list[str]:
490
- """Collect raw content lines for a block scalar.
491
-
492
- Args:
493
- raw_lineno: 1-based line number of the indicator (content starts
494
- on the *next* raw line).
495
- explicit_indent: Explicit indentation width from the header, or
496
- ``0`` to auto-detect.
497
-
498
- Returns:
499
- List of content lines with leading indentation stripped.
500
- """
501
- if raw_lineno >= len(self._raw_lines):
502
- return []
503
-
504
- content_indent = self._detect_scalar_indent(raw_lineno, explicit_indent)
505
- if content_indent == 0:
506
- return []
507
-
508
- content_lines: list[str] = []
509
- for j in range(raw_lineno, len(self._raw_lines)):
510
- raw = self._raw_lines[j]
511
- if not raw.strip():
512
- content_lines.append("")
513
- continue
514
- line_indent = len(raw) - len(raw.lstrip())
515
- if line_indent < content_indent:
516
- break
517
- content_lines.append(raw[content_indent:])
518
- return content_lines
519
-
520
- def _detect_scalar_indent(self, raw_lineno: int, explicit: int) -> int:
521
- """Determine the content indentation for a block scalar."""
522
- if explicit > 0:
523
- return explicit
524
- for j in range(raw_lineno, len(self._raw_lines)):
525
- raw = self._raw_lines[j]
526
- stripped = raw.lstrip()
527
- if stripped and not stripped.startswith("#"):
528
- return len(raw) - len(stripped)
529
- return 0
530
-
531
- @staticmethod
532
- def _fold_lines(content_lines: list[str]) -> str:
533
- """Fold content lines (``>`` mode): replace single newlines with spaces."""
534
- parts: list[str] = []
535
- for line in content_lines:
536
- if not line:
537
- parts.append("\n")
538
- elif parts and parts[-1] != "\n" and not parts[-1].endswith("\n"):
539
- parts.append(" " + line)
540
- else:
541
- parts.append(line)
542
- return "".join(parts)
543
-
544
- @staticmethod
545
- def _apply_chomping(text: str, chomp: str) -> str:
546
- """Apply the chomping rule (strip / keep / clip) to block scalar text."""
547
- if chomp == "strip":
548
- return text
549
- if chomp == "keep":
550
- return text + "\n"
551
- # clip
552
- return text + "\n" if text else ""
553
-
554
- def _parse_block_scalar_from_indicator(
555
- self, indicator_line: str, lineno: int
556
- ) -> str:
557
- """Parse a | or > block scalar, reading content lines from raw_lines."""
558
- indicator = indicator_line[0]
559
- header = indicator_line[1:].strip()
560
-
561
- chomp, explicit_indent = self._parse_chomping_indicator(header)
562
- content_lines = self._collect_scalar_lines(lineno, explicit_indent)
563
-
564
- # Skip consumed content lines in the scanner
565
- while True:
566
- nxt = self._peek()
567
- if nxt is None:
568
- break
569
- if nxt.lineno <= lineno + len(content_lines):
570
- self._advance()
571
- else:
572
- break
573
-
574
- # Remove trailing empty lines
575
- while content_lines and not content_lines[-1]:
576
- content_lines.pop()
577
-
578
- if indicator == "|":
579
- text = "\n".join(content_lines)
580
- else:
581
- text = self._fold_lines(content_lines)
582
-
583
- return self._apply_chomping(text, chomp)
584
-
585
- # ── Flow collections ──
586
-
587
- def _parse_flow_mapping(self) -> dict:
588
- cur = self._advance()
589
- return self._parse_flow_from_text(cur.text)
590
-
591
- def _parse_flow_sequence(self) -> list:
592
- cur = self._advance()
593
- return self._parse_flow_from_text(cur.text)
594
-
595
- def _parse_flow_from_text(self, text: str) -> Any:
596
- """Parse a flow collection from raw text."""
597
- tokens = _FlowTokenizer(text)
598
- return tokens.parse()
599
-
600
- # ── Scalar value ──
601
-
602
- def _parse_scalar_value(self, text: str) -> Any:
603
- """Parse a scalar value, handling quoting and type resolution."""
604
- if not text:
605
- return None
606
- # Quoted strings
607
- if (text.startswith("'") and text.endswith("'")) or (
608
- text.startswith('"') and text.endswith('"')
609
- ):
610
- return _unquote(text)
611
- # Plain scalar
612
- return _resolve_scalar(text)
613
-
614
-
615
- # ── Flow tokenizer ────────────────────────────────────────────────────────────
616
-
617
-
618
- class _FlowTokenizer:
619
- """Character-level parser for flow-style YAML collections."""
620
-
621
- def __init__(self, text: str):
622
- self._text = text
623
- self._pos = 0
624
-
625
- def _skip_ws(self) -> None:
626
- while self._pos < len(self._text) and self._text[self._pos] in (
627
- " ",
628
- "\t",
629
- "\n",
630
- "\r",
631
- ):
632
- self._pos += 1
633
-
634
- def _peek(self) -> str:
635
- if self._pos < len(self._text):
636
- return self._text[self._pos]
637
- return ""
638
-
639
- def parse(self) -> Any:
640
- self._skip_ws()
641
- ch = self._peek()
642
- if ch == "{":
643
- return self._parse_mapping()
644
- if ch == "[":
645
- return self._parse_sequence()
646
- return self._parse_value()
647
-
648
- def _parse_mapping(self) -> dict:
649
- self._pos += 1 # skip {
650
- result: dict[Any, Any] = {}
651
- self._skip_ws()
652
- if self._peek() == "}":
653
- self._pos += 1
654
- return result
655
-
656
- while True:
657
- self._skip_ws()
658
- key = self._parse_value()
659
- self._skip_ws()
660
- if self._peek() == ":":
661
- self._pos += 1
662
- self._skip_ws()
663
- value = self.parse()
664
- else:
665
- value = None
666
- result[key] = value
667
- self._skip_ws()
668
- if self._peek() == ",":
669
- self._pos += 1
670
- self._skip_ws()
671
- if self._peek() == "}":
672
- self._pos += 1
673
- break
674
- elif self._peek() == "}":
675
- self._pos += 1
676
- break
677
- else:
678
- break
679
- return result
680
-
681
- def _parse_sequence(self) -> list:
682
- self._pos += 1 # skip [
683
- result: list[Any] = []
684
- self._skip_ws()
685
- if self._peek() == "]":
686
- self._pos += 1
687
- return result
688
-
689
- while True:
690
- self._skip_ws()
691
- item = self.parse()
692
- result.append(item)
693
- self._skip_ws()
694
- if self._peek() == ",":
695
- self._pos += 1
696
- self._skip_ws()
697
- if self._peek() == "]":
698
- self._pos += 1
699
- break
700
- elif self._peek() == "]":
701
- self._pos += 1
702
- break
703
- else:
704
- break
705
- return result
706
-
707
- def _parse_value(self) -> Any:
708
- self._skip_ws()
709
- ch = self._peek()
710
- if ch == "{":
711
- return self._parse_mapping()
712
- if ch == "[":
713
- return self._parse_sequence()
714
- if ch == "'":
715
- return self._parse_single_quoted()
716
- if ch == '"':
717
- return self._parse_double_quoted()
718
- return self._parse_plain_scalar()
719
-
720
- def _parse_single_quoted(self) -> str:
721
- self._pos += 1 # skip opening '
722
- parts: list[str] = []
723
- while self._pos < len(self._text):
724
- ch = self._text[self._pos]
725
- if ch == "'":
726
- if self._pos + 1 < len(self._text) and self._text[self._pos + 1] == "'":
727
- parts.append("'")
728
- self._pos += 2
729
- else:
730
- self._pos += 1
731
- break
732
- else:
733
- parts.append(ch)
734
- self._pos += 1
735
- return "".join(parts)
736
-
737
- def _parse_double_quoted(self) -> str:
738
- self._pos += 1 # skip opening "
739
- parts: list[str] = []
740
- while self._pos < len(self._text):
741
- ch = self._text[self._pos]
742
- if ch == "\\" and self._pos + 1 < len(self._text):
743
- nxt = self._text[self._pos + 1]
744
- if nxt in _DQ_ESCAPE_MAP:
745
- parts.append(_DQ_ESCAPE_MAP[nxt])
746
- self._pos += 2
747
- else:
748
- parts.append(ch)
749
- self._pos += 1
750
- elif ch == '"':
751
- self._pos += 1
752
- break
753
- else:
754
- parts.append(ch)
755
- self._pos += 1
756
- return "".join(parts)
757
-
758
- def _parse_plain_scalar(self) -> Any:
759
- start = self._pos
760
- # Read until a flow indicator or end
761
- while self._pos < len(self._text):
762
- ch = self._text[self._pos]
763
- if ch in (",", "}", "]", "{", "[", ":"):
764
- break
765
- self._pos += 1
766
- raw = self._text[start : self._pos].strip()
767
- if not raw:
768
- return None
769
- return _resolve_scalar(raw)
770
-
771
-
772
- # ── Dumper ─────────────────────────────────────────────────────────────────────
773
-
774
- # Characters that force quoting in a plain scalar
775
- _NEEDS_QUOTE_RE = re.compile(
776
- r"[:\#{}\[\],&*?|>!%@`]"
777
- r"|^[-?]$"
778
- r"|^\s"
779
- r"|\s$"
780
- r"|\n"
781
- )
782
-
783
-
784
- class _Dumper:
785
- """YAML serializer."""
786
-
787
- def __init__(
788
- self,
789
- indent: int = 2,
790
- default_flow_style: bool | None = None,
791
- sort_keys: bool = True,
792
- allow_unicode: bool = True,
793
- ):
794
- self._indent = indent
795
- self._flow = default_flow_style
796
- self._sort_keys = sort_keys
797
- self._allow_unicode = allow_unicode
798
- self._seen: set[int] = set()
799
-
800
- def dump(self, data: Any) -> str:
801
- self._seen.clear()
802
- result = self._represent(data, 0)
803
- if result.endswith("\n"):
804
- return result
805
- return result + "\n"
806
-
807
- def _represent(self, data: Any, level: int) -> str:
808
- if isinstance(data, dict):
809
- return self._represent_mapping(data, level)
810
- if isinstance(data, (list, tuple)):
811
- return self._represent_sequence(data, level)
812
- return self._represent_scalar(data)
813
-
814
- def _represent_mapping(self, data: dict, level: int) -> str:
815
- if id(data) in self._seen:
816
- raise YAMLError("Circular reference detected")
817
- self._seen.add(id(data))
818
-
819
- if not data:
820
- return "{}"
821
-
822
- if self._flow is True:
823
- items = []
824
- keys = sorted(data.keys(), key=str) if self._sort_keys else data.keys()
825
- for key in keys:
826
- k = self._represent_scalar(key)
827
- v = self._represent(data[key], level)
828
- items.append(f"{k}: {v}")
829
- self._seen.discard(id(data))
830
- return "{" + ", ".join(items) + "}"
831
-
832
- lines: list[str] = []
833
- prefix = " " * (self._indent * level)
834
- keys = sorted(data.keys(), key=str) if self._sort_keys else data.keys()
835
- for key in keys:
836
- k = self._represent_scalar(key)
837
- val = data[key]
838
- if isinstance(val, dict) and val:
839
- lines.append(f"{prefix}{k}:")
840
- lines.append(self._represent_mapping(val, level + 1))
841
- elif isinstance(val, (list, tuple)) and val:
842
- lines.append(f"{prefix}{k}:")
843
- lines.append(self._represent_sequence(val, level + 1))
844
- else:
845
- v = self._represent(val, level + 1)
846
- lines.append(f"{prefix}{k}: {v}")
847
- self._seen.discard(id(data))
848
- return "\n".join(lines)
849
-
850
- def _represent_key_value_line(
851
- self, key_str: str, val: Any, line_prefix: str, level: int
852
- ) -> list[str]:
853
- """Represent a single key-value pair for use inside a sequence item."""
854
- if isinstance(val, (dict, list, tuple)) and val:
855
- return [f"{line_prefix}{key_str}:", self._represent(val, level)]
856
- v = self._represent(val, level)
857
- return [f"{line_prefix}{key_str}: {v}"]
858
-
859
- def _represent_dict_in_sequence(
860
- self, item: dict, prefix: str, level: int
861
- ) -> list[str]:
862
- """Represent a dict that appears as a sequence item (``- key: val``)."""
863
- keys = sorted(item.keys(), key=str) if self._sort_keys else list(item.keys())
864
- first_key = keys[0]
865
- k = self._represent_scalar(first_key)
866
- lines = self._represent_key_value_line(
867
- k, item[first_key], f"{prefix}- ", level + 2
868
- )
869
- inner_prefix = prefix + " " * self._indent
870
- for rk in keys[1:]:
871
- rk_s = self._represent_scalar(rk)
872
- lines.extend(
873
- self._represent_key_value_line(rk_s, item[rk], inner_prefix, level + 2)
874
- )
875
- return lines
876
-
877
- def _represent_sequence(self, data: list | tuple, level: int) -> str:
878
- if id(data) in self._seen:
879
- raise YAMLError("Circular reference detected")
880
- self._seen.add(id(data))
881
-
882
- if not data:
883
- return "[]"
884
-
885
- if self._flow is True:
886
- items = [self._represent(item, level) for item in data]
887
- self._seen.discard(id(data))
888
- return "[" + ", ".join(items) + "]"
889
-
890
- lines: list[str] = []
891
- prefix = " " * (self._indent * level)
892
- for item in data:
893
- if isinstance(item, dict) and item:
894
- lines.extend(self._represent_dict_in_sequence(item, prefix, level))
895
- elif isinstance(item, (list, tuple)) and item:
896
- lines.append(f"{prefix}-")
897
- lines.append(self._represent_sequence(item, level + 1))
898
- else:
899
- v = self._represent(item, level + 1)
900
- lines.append(f"{prefix}- {v}")
901
-
902
- self._seen.discard(id(data))
903
- return "\n".join(lines)
904
-
905
- def _represent_scalar(self, data: Any) -> str:
906
- if data is None:
907
- return "null"
908
- if isinstance(data, bool):
909
- return "true" if data else "false"
910
- if isinstance(data, int):
911
- return str(data)
912
- if isinstance(data, float):
913
- if math.isnan(data):
914
- return ".nan"
915
- if math.isinf(data):
916
- return ".inf" if data > 0 else "-.inf"
917
- return str(data)
918
- if isinstance(data, str):
919
- return self._represent_str(data)
920
- return str(data)
921
-
922
- def _represent_str(self, s: str) -> str:
923
- if not s:
924
- return "''"
925
-
926
- # Check if it looks like a special YAML value
927
- if (
928
- _NULL_RE.match(s)
929
- or _BOOL_TRUE_RE.match(s)
930
- or _BOOL_FALSE_RE.match(s)
931
- or _INT_RE.match(s)
932
- or _INT_HEX_RE.match(s)
933
- or _FLOAT_RE.match(s)
934
- or _INF_RE.match(s)
935
- or _NAN_RE.match(s)
936
- ):
937
- return f"'{s}'"
938
-
939
- # Check if quoting is needed
940
- if _NEEDS_QUOTE_RE.search(s):
941
- if "\n" in s:
942
- # Use literal block scalar for multiline
943
- return "|\n" + "\n".join(" " + line for line in s.split("\n"))
944
- # Use single quotes, escaping internal single quotes
945
- return "'" + s.replace("'", "''") + "'"
946
-
947
- return s
948
-
949
-
950
- # ── Public API ─────────────────────────────────────────────────────────────────
951
-
952
-
953
- def load(text: str) -> Any:
954
- """Parse a YAML string and return a Python object.
955
-
956
- Only produces safe types: dict, list, str, int, float, bool, None.
957
- Equivalent to PyYAML's ``yaml.safe_load()``.
958
-
959
- Args:
960
- text: YAML document string.
961
-
962
- Returns:
963
- Parsed Python object.
964
-
965
- Raises:
966
- YAMLError: If the YAML is malformed.
967
- """
968
- if not text or not text.strip():
969
- return None
970
- raw_lines = text.splitlines()
971
- lines = _scan(text)
972
- if not lines:
973
- return None
974
- parser = _Parser(lines, raw_lines)
975
- docs = parser.parse_stream()
976
- return docs[0] if docs else None
977
-
978
-
979
- def load_all(text: str) -> Iterator[Any]:
980
- """Parse a multi-document YAML string.
981
-
982
- Yields one Python object per YAML document (separated by ``---``).
983
-
984
- Args:
985
- text: Multi-document YAML string.
986
-
987
- Yields:
988
- Parsed Python objects, one per document.
989
- """
990
- if not text or not text.strip():
991
- yield None
992
- return
993
- raw_lines = text.splitlines()
994
- lines = _scan(text)
995
- if not lines:
996
- yield None
997
- return
998
- parser = _Parser(lines, raw_lines)
999
- docs = parser.parse_stream()
1000
- yield from docs
1001
-
1002
-
1003
- @overload
1004
- def dump(
1005
- data: Any,
1006
- stream: None = None,
1007
- *,
1008
- default_flow_style: bool | None = None,
1009
- indent: int = 2,
1010
- sort_keys: bool = True,
1011
- allow_unicode: bool = True,
1012
- ) -> str: ...
1013
-
1014
-
1015
- @overload
1016
- def dump(
1017
- data: Any,
1018
- stream: IO[str],
1019
- *,
1020
- default_flow_style: bool | None = None,
1021
- indent: int = 2,
1022
- sort_keys: bool = True,
1023
- allow_unicode: bool = True,
1024
- ) -> None: ...
1025
-
1026
-
1027
- def dump(
1028
- data: Any,
1029
- stream: IO[str] | None = None,
1030
- *,
1031
- default_flow_style: bool | None = None,
1032
- indent: int = 2,
1033
- sort_keys: bool = True,
1034
- allow_unicode: bool = True,
1035
- ) -> str | None:
1036
- """Serialize a Python object to a YAML string.
1037
-
1038
- Args:
1039
- data: Python object to serialize.
1040
- stream: If provided, write to this stream and return None.
1041
- default_flow_style: True for flow (inline) style, False for block,
1042
- None for auto (empty collections use flow).
1043
- indent: Number of spaces per indentation level.
1044
- sort_keys: Sort mapping keys alphabetically.
1045
- allow_unicode: Allow unicode characters in output.
1046
-
1047
- Returns:
1048
- YAML string if *stream* is None, otherwise None.
1049
- """
1050
- dumper = _Dumper(
1051
- indent=indent,
1052
- default_flow_style=default_flow_style,
1053
- sort_keys=sort_keys,
1054
- allow_unicode=allow_unicode,
1055
- )
1056
- result = dumper.dump(data)
1057
- if stream is not None:
1058
- stream.write(result)
1059
- return None
1060
- return result
1061
-
1062
-
1063
- @overload
1064
- def dump_all(
1065
- documents: list[Any] | tuple[Any, ...],
1066
- stream: None = None,
1067
- *,
1068
- default_flow_style: bool | None = None,
1069
- indent: int = 2,
1070
- sort_keys: bool = True,
1071
- allow_unicode: bool = True,
1072
- ) -> str: ...
1073
-
1074
-
1075
- @overload
1076
- def dump_all(
1077
- documents: list[Any] | tuple[Any, ...],
1078
- stream: IO[str],
1079
- *,
1080
- default_flow_style: bool | None = None,
1081
- indent: int = 2,
1082
- sort_keys: bool = True,
1083
- allow_unicode: bool = True,
1084
- ) -> None: ...
1085
-
1086
-
1087
- def dump_all(
1088
- documents: list[Any] | tuple[Any, ...],
1089
- stream: IO[str] | None = None,
1090
- *,
1091
- default_flow_style: bool | None = None,
1092
- indent: int = 2,
1093
- sort_keys: bool = True,
1094
- allow_unicode: bool = True,
1095
- ) -> str | None:
1096
- """Serialize multiple Python objects as a multi-document YAML string.
1097
-
1098
- Args:
1099
- documents: Iterable of Python objects to serialize.
1100
- stream: If provided, write to this stream and return None.
1101
- default_flow_style: True for flow style, False for block, None for auto.
1102
- indent: Number of spaces per indentation level.
1103
- sort_keys: Sort mapping keys alphabetically.
1104
- allow_unicode: Allow unicode characters in output.
1105
-
1106
- Returns:
1107
- YAML string if *stream* is None, otherwise None.
1108
- """
1109
- dumper = _Dumper(
1110
- indent=indent,
1111
- default_flow_style=default_flow_style,
1112
- sort_keys=sort_keys,
1113
- allow_unicode=allow_unicode,
1114
- )
1115
- parts: list[str] = []
1116
- for i, doc in enumerate(documents):
1117
- if i > 0:
1118
- parts.append("---\n")
1119
- parts.append(dumper.dump(doc))
1120
- result = "".join(parts)
1121
- if stream is not None:
1122
- stream.write(result)
1123
- return None
1124
- return result