Spaces:
Paused
Paused
Peng Ding commited on
Commit Β·
cd0db39
1
Parent(s): 0ae4e28
chore: replace deprecated jsonc with jsonx, remove benchmark_compare
Browse files
src/veilrender/_vendor/benchmark_compare.py
DELETED
|
@@ -1,323 +0,0 @@
|
|
| 1 |
-
#!/usr/bin/env python3
|
| 2 |
-
"""Three-way readability benchmark: zerodep vs readability-lxml vs Mozilla JS.
|
| 3 |
-
|
| 4 |
-
Runs each implementation on Mozilla's test fixtures and prints a comparison
|
| 5 |
-
table. JS timing is measured internally by bench_mozilla.js (no subprocess
|
| 6 |
-
overhead in the numbers).
|
| 7 |
-
|
| 8 |
-
Usage:
|
| 9 |
-
python benchmark_compare.py # all fixtures
|
| 10 |
-
python benchmark_compare.py 001 bbc-1 # specific fixtures
|
| 11 |
-
python benchmark_compare.py --rounds 20 # more rounds
|
| 12 |
-
"""
|
| 13 |
-
|
| 14 |
-
from __future__ import annotations
|
| 15 |
-
|
| 16 |
-
import argparse
|
| 17 |
-
import json
|
| 18 |
-
import os
|
| 19 |
-
import shutil
|
| 20 |
-
import subprocess
|
| 21 |
-
import sys
|
| 22 |
-
import timeit
|
| 23 |
-
|
| 24 |
-
# ββ Setup paths ββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ
|
| 25 |
-
|
| 26 |
-
_THIS_DIR = os.path.dirname(os.path.abspath(__file__))
|
| 27 |
-
_TEST_PAGES_DIR = os.path.join(_THIS_DIR, "test-pages")
|
| 28 |
-
_BENCH_JS = os.path.join(_THIS_DIR, "bench_mozilla.js")
|
| 29 |
-
|
| 30 |
-
sys.path.insert(0, _THIS_DIR)
|
| 31 |
-
|
| 32 |
-
|
| 33 |
-
# ββ Discover fixtures ββββββββββββββββββββββββββββββββββββββββββββββββββββββββ
|
| 34 |
-
|
| 35 |
-
|
| 36 |
-
def discover_fixtures() -> list[str]:
|
| 37 |
-
"""Return sorted list of available fixture names."""
|
| 38 |
-
if not os.path.isdir(_TEST_PAGES_DIR):
|
| 39 |
-
return []
|
| 40 |
-
return sorted(
|
| 41 |
-
d
|
| 42 |
-
for d in os.listdir(_TEST_PAGES_DIR)
|
| 43 |
-
if os.path.isdir(os.path.join(_TEST_PAGES_DIR, d))
|
| 44 |
-
and os.path.isfile(os.path.join(_TEST_PAGES_DIR, d, "source.html"))
|
| 45 |
-
)
|
| 46 |
-
|
| 47 |
-
|
| 48 |
-
def load_source(name: str) -> str:
|
| 49 |
-
"""Load source HTML for a fixture."""
|
| 50 |
-
path = os.path.join(_TEST_PAGES_DIR, name, "source.html")
|
| 51 |
-
with open(path, encoding="utf-8") as f:
|
| 52 |
-
return f.read()
|
| 53 |
-
|
| 54 |
-
|
| 55 |
-
# ββ Python: zerodep readability ββββββββββββββββββββββββββββββββββββββββββββββ
|
| 56 |
-
|
| 57 |
-
|
| 58 |
-
def bench_zerodep(html: str, rounds: int) -> dict:
|
| 59 |
-
"""Benchmark our readability.extract() and return timing dict."""
|
| 60 |
-
from readability import extract
|
| 61 |
-
|
| 62 |
-
# Warm-up.
|
| 63 |
-
result = extract(html)
|
| 64 |
-
|
| 65 |
-
times = []
|
| 66 |
-
for _ in range(rounds):
|
| 67 |
-
t0 = timeit.default_timer()
|
| 68 |
-
extract(html)
|
| 69 |
-
t1 = timeit.default_timer()
|
| 70 |
-
times.append((t1 - t0) * 1000) # ms
|
| 71 |
-
|
| 72 |
-
return {
|
| 73 |
-
"times_ms": times,
|
| 74 |
-
"min_ms": min(times),
|
| 75 |
-
"mean_ms": sum(times) / len(times),
|
| 76 |
-
"max_ms": max(times),
|
| 77 |
-
"title": result.title,
|
| 78 |
-
"length": result.length,
|
| 79 |
-
}
|
| 80 |
-
|
| 81 |
-
|
| 82 |
-
# ββ Python: readability-lxml ββββββββββββββββββββββββββββββββββββββββββββββββ
|
| 83 |
-
|
| 84 |
-
|
| 85 |
-
def _load_readability_lxml():
|
| 86 |
-
"""Load readability-lxml's Document class, working around name clash."""
|
| 87 |
-
import importlib
|
| 88 |
-
import importlib.metadata
|
| 89 |
-
|
| 90 |
-
try:
|
| 91 |
-
importlib.metadata.version("readability-lxml")
|
| 92 |
-
except importlib.metadata.PackageNotFoundError:
|
| 93 |
-
return None
|
| 94 |
-
|
| 95 |
-
saved_path = sys.path[:]
|
| 96 |
-
saved_modules = {
|
| 97 |
-
k: sys.modules.pop(k)
|
| 98 |
-
for k in list(sys.modules)
|
| 99 |
-
if k == "readability" or k.startswith("readability.")
|
| 100 |
-
}
|
| 101 |
-
try:
|
| 102 |
-
sys.path = [
|
| 103 |
-
p for p in sys.path if os.path.abspath(p) != os.path.abspath(_THIS_DIR)
|
| 104 |
-
]
|
| 105 |
-
mod = importlib.import_module("readability")
|
| 106 |
-
return mod.Document
|
| 107 |
-
finally:
|
| 108 |
-
sys.path = saved_path
|
| 109 |
-
for k in list(sys.modules):
|
| 110 |
-
if k == "readability" or k.startswith("readability."):
|
| 111 |
-
del sys.modules[k]
|
| 112 |
-
sys.modules.update(saved_modules)
|
| 113 |
-
|
| 114 |
-
|
| 115 |
-
_RefDocument = _load_readability_lxml()
|
| 116 |
-
|
| 117 |
-
|
| 118 |
-
def bench_readability_lxml(html: str, rounds: int) -> dict | None:
|
| 119 |
-
"""Benchmark readability-lxml and return timing dict, or None."""
|
| 120 |
-
if _RefDocument is None:
|
| 121 |
-
return None
|
| 122 |
-
|
| 123 |
-
# Warm-up.
|
| 124 |
-
doc = _RefDocument(html)
|
| 125 |
-
summary = doc.summary()
|
| 126 |
-
|
| 127 |
-
times = []
|
| 128 |
-
for _ in range(rounds):
|
| 129 |
-
t0 = timeit.default_timer()
|
| 130 |
-
doc = _RefDocument(html)
|
| 131 |
-
doc.summary()
|
| 132 |
-
t1 = timeit.default_timer()
|
| 133 |
-
times.append((t1 - t0) * 1000)
|
| 134 |
-
|
| 135 |
-
# Extract title from summary HTML (basic).
|
| 136 |
-
title = doc.short_title() if hasattr(doc, "short_title") else ""
|
| 137 |
-
length = len(summary) if summary else 0
|
| 138 |
-
|
| 139 |
-
return {
|
| 140 |
-
"times_ms": times,
|
| 141 |
-
"min_ms": min(times),
|
| 142 |
-
"mean_ms": sum(times) / len(times),
|
| 143 |
-
"max_ms": max(times),
|
| 144 |
-
"title": title,
|
| 145 |
-
"length": length,
|
| 146 |
-
}
|
| 147 |
-
|
| 148 |
-
|
| 149 |
-
# ββ JavaScript: Mozilla Readability.js βββββββββββββββββββββββββββββββββββββββ
|
| 150 |
-
|
| 151 |
-
|
| 152 |
-
def bench_mozilla_js(fixture_name: str, rounds: int) -> dict | None:
|
| 153 |
-
"""Benchmark Mozilla Readability.js via Node.js subprocess.
|
| 154 |
-
|
| 155 |
-
Timing is measured internally by bench_mozilla.js β no subprocess
|
| 156 |
-
overhead in the reported numbers.
|
| 157 |
-
"""
|
| 158 |
-
if not shutil.which("node"):
|
| 159 |
-
return None
|
| 160 |
-
if not os.path.isfile(_BENCH_JS):
|
| 161 |
-
return None
|
| 162 |
-
|
| 163 |
-
source_path = os.path.join(_TEST_PAGES_DIR, fixture_name, "source.html")
|
| 164 |
-
try:
|
| 165 |
-
result = subprocess.run(
|
| 166 |
-
["node", _BENCH_JS, source_path, str(rounds)],
|
| 167 |
-
capture_output=True,
|
| 168 |
-
text=True,
|
| 169 |
-
timeout=120,
|
| 170 |
-
cwd=_THIS_DIR,
|
| 171 |
-
)
|
| 172 |
-
if result.returncode != 0:
|
| 173 |
-
print(f" [JS error: {result.stderr.strip()[:100]}]", file=sys.stderr)
|
| 174 |
-
return None
|
| 175 |
-
return json.loads(result.stdout)
|
| 176 |
-
except (subprocess.TimeoutExpired, json.JSONDecodeError, FileNotFoundError):
|
| 177 |
-
return None
|
| 178 |
-
|
| 179 |
-
|
| 180 |
-
# ββ Output formatting ββββββββββββββββββββββββββββββββββββββββββββββββββββββββ
|
| 181 |
-
|
| 182 |
-
# ANSI colors (disabled if not a terminal).
|
| 183 |
-
if sys.stdout.isatty():
|
| 184 |
-
_BOLD = "\033[1m"
|
| 185 |
-
_GREEN = "\033[32m"
|
| 186 |
-
_YELLOW = "\033[33m"
|
| 187 |
-
_CYAN = "\033[36m"
|
| 188 |
-
_RESET = "\033[0m"
|
| 189 |
-
_DIM = "\033[2m"
|
| 190 |
-
else:
|
| 191 |
-
_BOLD = _GREEN = _YELLOW = _CYAN = _RESET = _DIM = ""
|
| 192 |
-
|
| 193 |
-
|
| 194 |
-
def _fmt_ms(ms: float) -> str:
|
| 195 |
-
"""Format milliseconds with appropriate unit."""
|
| 196 |
-
if ms < 1:
|
| 197 |
-
return f"{ms * 1000:.0f} Β΅s"
|
| 198 |
-
if ms < 1000:
|
| 199 |
-
return f"{ms:.1f} ms"
|
| 200 |
-
return f"{ms / 1000:.2f} s"
|
| 201 |
-
|
| 202 |
-
|
| 203 |
-
def _ratio_str(ms: float, baseline: float) -> str:
|
| 204 |
-
"""Format a ratio relative to baseline."""
|
| 205 |
-
if baseline <= 0:
|
| 206 |
-
return ""
|
| 207 |
-
ratio = ms / baseline
|
| 208 |
-
if ratio < 1.05:
|
| 209 |
-
return f"{_GREEN}1.00x{_RESET}"
|
| 210 |
-
return f"{_YELLOW}{ratio:.2f}x{_RESET}"
|
| 211 |
-
|
| 212 |
-
|
| 213 |
-
def print_results(
|
| 214 |
-
fixture_name: str,
|
| 215 |
-
html_size: int,
|
| 216 |
-
zd: dict,
|
| 217 |
-
lxml: dict | None,
|
| 218 |
-
js: dict | None,
|
| 219 |
-
) -> None:
|
| 220 |
-
"""Print a single fixture's results as a formatted row."""
|
| 221 |
-
baseline = zd["mean_ms"]
|
| 222 |
-
|
| 223 |
-
cols = [
|
| 224 |
-
f" {_BOLD}{fixture_name:<28s}{_RESET}",
|
| 225 |
-
f"{_DIM}{html_size / 1024:>7.1f} KB{_RESET}",
|
| 226 |
-
f"{_CYAN}zerodep{_RESET} {_fmt_ms(zd['mean_ms']):>10s}"
|
| 227 |
-
f" {_ratio_str(zd['mean_ms'], baseline)}",
|
| 228 |
-
]
|
| 229 |
-
|
| 230 |
-
if lxml is not None:
|
| 231 |
-
cols.append(
|
| 232 |
-
f"{_CYAN}lxml{_RESET} {_fmt_ms(lxml['mean_ms']):>10s}"
|
| 233 |
-
f" {_ratio_str(lxml['mean_ms'], baseline)}"
|
| 234 |
-
)
|
| 235 |
-
else:
|
| 236 |
-
cols.append(f"{_DIM}lxml {'n/a':>10s}{_RESET}")
|
| 237 |
-
|
| 238 |
-
if js is not None:
|
| 239 |
-
cols.append(
|
| 240 |
-
f"{_CYAN}mozilla{_RESET} {_fmt_ms(js['mean_ms']):>10s}"
|
| 241 |
-
f" {_ratio_str(js['mean_ms'], baseline)}"
|
| 242 |
-
)
|
| 243 |
-
else:
|
| 244 |
-
cols.append(f"{_DIM}mozilla {'n/a':>10s}{_RESET}")
|
| 245 |
-
|
| 246 |
-
print(" ".join(cols))
|
| 247 |
-
|
| 248 |
-
|
| 249 |
-
# ββ Main βββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ
|
| 250 |
-
|
| 251 |
-
|
| 252 |
-
def main() -> None:
|
| 253 |
-
parser = argparse.ArgumentParser(
|
| 254 |
-
description="Three-way readability benchmark comparison."
|
| 255 |
-
)
|
| 256 |
-
parser.add_argument(
|
| 257 |
-
"fixtures",
|
| 258 |
-
nargs="*",
|
| 259 |
-
help="Fixture names to benchmark (default: all).",
|
| 260 |
-
)
|
| 261 |
-
parser.add_argument(
|
| 262 |
-
"--rounds",
|
| 263 |
-
type=int,
|
| 264 |
-
default=10,
|
| 265 |
-
help="Number of timing rounds per fixture (default: 10).",
|
| 266 |
-
)
|
| 267 |
-
args = parser.parse_args()
|
| 268 |
-
|
| 269 |
-
all_fixtures = discover_fixtures()
|
| 270 |
-
if not all_fixtures:
|
| 271 |
-
print("No test fixtures found in test-pages/", file=sys.stderr)
|
| 272 |
-
sys.exit(1)
|
| 273 |
-
|
| 274 |
-
fixtures = args.fixtures if args.fixtures else all_fixtures
|
| 275 |
-
# Validate fixture names.
|
| 276 |
-
for name in fixtures:
|
| 277 |
-
if name not in all_fixtures:
|
| 278 |
-
print(f"Unknown fixture: {name}", file=sys.stderr)
|
| 279 |
-
print(f"Available: {', '.join(all_fixtures)}", file=sys.stderr)
|
| 280 |
-
sys.exit(1)
|
| 281 |
-
|
| 282 |
-
rounds = args.rounds
|
| 283 |
-
|
| 284 |
-
# Header.
|
| 285 |
-
print()
|
| 286 |
-
print(f"{_BOLD}Readability Benchmark ({rounds} rounds per fixture){_RESET}")
|
| 287 |
-
has_node = shutil.which("node") is not None
|
| 288 |
-
has_lxml = _RefDocument is not None
|
| 289 |
-
status = []
|
| 290 |
-
status.append(f"zerodep: {_GREEN}yes{_RESET}")
|
| 291 |
-
lxml_status = _GREEN + "yes" + _RESET if has_lxml else _DIM + "no" + _RESET
|
| 292 |
-
status.append(f"readability-lxml: {lxml_status}")
|
| 293 |
-
status.append(
|
| 294 |
-
f"mozilla js: {_GREEN + 'yes' + _RESET if has_node else _DIM + 'no' + _RESET}"
|
| 295 |
-
)
|
| 296 |
-
print(f" Implementations: {' | '.join(status)}")
|
| 297 |
-
print(f" {_DIM}Times shown are mean. Ratios relative to zerodep.{_RESET}")
|
| 298 |
-
print()
|
| 299 |
-
|
| 300 |
-
# Column headers.
|
| 301 |
-
print(
|
| 302 |
-
f" {'Fixture':<28s} {'Size':>9s} "
|
| 303 |
-
f"{'zerodep':>19s} {'readability-lxml':>19s} "
|
| 304 |
-
f"{'mozilla js':>19s}"
|
| 305 |
-
)
|
| 306 |
-
print(" " + "β" * 110)
|
| 307 |
-
|
| 308 |
-
for name in fixtures:
|
| 309 |
-
html = load_source(name)
|
| 310 |
-
html_size = len(html.encode("utf-8"))
|
| 311 |
-
|
| 312 |
-
# Benchmark all three.
|
| 313 |
-
zd = bench_zerodep(html, rounds)
|
| 314 |
-
lxml = bench_readability_lxml(html, rounds)
|
| 315 |
-
js = bench_mozilla_js(name, rounds)
|
| 316 |
-
|
| 317 |
-
print_results(name, html_size, zd, lxml, js)
|
| 318 |
-
|
| 319 |
-
print()
|
| 320 |
-
|
| 321 |
-
|
| 322 |
-
if __name__ == "__main__":
|
| 323 |
-
main()
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
src/veilrender/_vendor/{jsonc.py β jsonx.py}
RENAMED
|
@@ -1,23 +1,25 @@
|
|
| 1 |
# /// zerodep
|
| 2 |
-
# version = "0.
|
| 3 |
# deps = []
|
| 4 |
# tier = "simple"
|
| 5 |
# category = "serialization"
|
| 6 |
-
# note = "Install/update via `zerodep add
|
| 7 |
# ///
|
| 8 |
|
| 9 |
-
"""
|
| 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 |
|
| 16 |
Supports:
|
| 17 |
- Single-line comments: ``//`` and ``#``
|
| 18 |
- Block comments: ``/* ... */``
|
| 19 |
- Trailing commas in objects and arrays
|
| 20 |
- All standard JSON types
|
|
|
|
| 21 |
|
| 22 |
Example::
|
| 23 |
|
|
@@ -25,6 +27,10 @@ Example::
|
|
| 25 |
# {'a': 1, 'b': 2}
|
| 26 |
load(open("config.jsonc"))
|
| 27 |
# {...}
|
|
|
|
|
|
|
|
|
|
|
|
|
| 28 |
"""
|
| 29 |
|
| 30 |
from __future__ import annotations
|
|
@@ -39,6 +45,10 @@ __all__ = [
|
|
| 39 |
"load",
|
| 40 |
"dumps",
|
| 41 |
"dump",
|
|
|
|
|
|
|
|
|
|
|
|
|
| 42 |
]
|
| 43 |
|
| 44 |
# ββ Comment stripping βββββββββββββββββββββββββββββββββββββββββββββββββββββββββ
|
|
@@ -350,3 +360,117 @@ def dump(
|
|
| 350 |
sort_keys=sort_keys,
|
| 351 |
**kwargs,
|
| 352 |
)
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
| 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 |
|
|
|
|
| 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
|
|
|
|
| 45 |
"load",
|
| 46 |
"dumps",
|
| 47 |
"dump",
|
| 48 |
+
"loads_lines",
|
| 49 |
+
"load_lines",
|
| 50 |
+
"dumps_lines",
|
| 51 |
+
"dump_lines",
|
| 52 |
]
|
| 53 |
|
| 54 |
# ββ Comment stripping βββββββββββββββββββββββββββββββββββββββββββββββββββββββββ
|
|
|
|
| 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")
|