Spaces:
Paused
Paused
Peng Ding commited on
Commit ·
08c34fe
1
Parent(s): a6d9249
chore: remove 8 unused vendor modules (368K → 184K)
Browse filesRemove 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 +0 -723
- src/veilrender/_vendor/dotenv.py +0 -514
- src/veilrender/_vendor/jsonx.py +0 -476
- src/veilrender/_vendor/markdown.py +0 -904
- src/veilrender/_vendor/retry.py +0 -503
- src/veilrender/_vendor/structlog.py +0 -888
- src/veilrender/_vendor/useragent.py +0 -475
- src/veilrender/_vendor/yaml.py +0 -1124
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
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|