dsh-zju-lecture-note 2.2.5 → 2.2.7

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -18,6 +18,7 @@ Security boundaries:
18
18
 
19
19
  import hashlib
20
20
  import os
21
+ import tempfile
21
22
  import urllib.error
22
23
  import urllib.parse
23
24
  import zlib
@@ -79,6 +80,7 @@ def _download_one(
79
80
  target_dir: str,
80
81
  timeout: int,
81
82
  token: Optional[str],
83
+ diagnostics: Optional[List[str]] = None,
82
84
  ) -> Tuple[int, Optional[Dict[str, Any]], Optional[str]]:
83
85
  url = str(slide.get("image_url") or "").strip()
84
86
  if not url:
@@ -104,6 +106,7 @@ def _download_one(
104
106
  attempts=3,
105
107
  max_bytes=MAX_IMAGE_BYTES,
106
108
  allow_cross_host_redirect=True,
109
+ diagnostics=diagnostics,
107
110
  )
108
111
  except urllib.error.HTTPError as error:
109
112
  if error.code in (401, 403) and token:
@@ -116,6 +119,7 @@ def _download_one(
116
119
  attempts=2,
117
120
  max_bytes=MAX_IMAGE_BYTES,
118
121
  allow_cross_host_redirect=True,
122
+ diagnostics=diagnostics,
119
123
  )
120
124
  else:
121
125
  raise
@@ -129,16 +133,21 @@ def _download_one(
129
133
  return index, None, "响应不是 JPEG/PNG(可能是登录失效页或错误页)"
130
134
 
131
135
  path = os.path.join(target_dir, f"slide-{index + 1:04d}{extension}")
132
- part = path + ".part"
136
+ part = ""
133
137
  try:
134
- with open(part, "wb") as handle:
138
+ descriptor, part = tempfile.mkstemp(
139
+ dir=target_dir, prefix=".slide-", suffix=".part"
140
+ )
141
+ with os.fdopen(descriptor, "wb") as handle:
135
142
  handle.write(data)
136
143
  os.replace(part, path)
144
+ part = ""
137
145
  except OSError as error:
138
- try:
139
- os.unlink(part)
140
- except OSError:
141
- pass
146
+ if part:
147
+ try:
148
+ os.unlink(part)
149
+ except OSError:
150
+ pass
142
151
  return index, None, f"截图写入失败: {error}"
143
152
 
144
153
  return index, {
@@ -188,22 +197,42 @@ def download_slides(
188
197
 
189
198
  results: List[Tuple[int, Optional[Dict[str, Any]], Optional[str]]] = []
190
199
  pool_size = max(1, min(int(workers or DOWNLOAD_WORKERS), 8))
200
+ downloaded_bytes = 0
201
+ stopped = False
191
202
  with ThreadPoolExecutor(max_workers=pool_size) as pool:
192
- futures = [
193
- pool.submit(
194
- _download_one,
195
- index,
196
- slide,
197
- cookie,
198
- sub_id,
199
- target_dir,
200
- timeout,
201
- token,
202
- )
203
- for index, slide in indexed
204
- ]
205
- for future in as_completed(futures):
206
- results.append(future.result())
203
+ # Batch instead of submitting everything at once: the total-size cap
204
+ # has to stop **future** downloads, not just print a warning after the
205
+ # disk is already full.
206
+ for start in range(0, len(indexed), pool_size):
207
+ batch = indexed[start:start + pool_size]
208
+ futures = [
209
+ pool.submit(
210
+ _download_one,
211
+ index,
212
+ slide,
213
+ cookie,
214
+ sub_id,
215
+ target_dir,
216
+ timeout,
217
+ token,
218
+ diagnostics,
219
+ )
220
+ for index, slide in batch
221
+ ]
222
+ for future in as_completed(futures):
223
+ result = future.result()
224
+ results.append(result)
225
+ if result[1] is not None:
226
+ downloaded_bytes += int(result[1]["bytes"])
227
+ if downloaded_bytes >= MAX_TOTAL_BYTES:
228
+ remaining = len(indexed) - len(results)
229
+ _record(
230
+ diagnostics,
231
+ f"截图总大小达到 {MAX_TOTAL_BYTES // (1024 * 1024)} MiB 上限,"
232
+ f"已下载 {len(results)} 张,停止后续 {remaining} 张",
233
+ )
234
+ stopped = True
235
+ break
207
236
  results.sort(key=lambda item: item[0])
208
237
 
209
238
  failures: List[str] = []
@@ -235,12 +264,8 @@ def download_slides(
235
264
  _record(diagnostics, f"另有 {len(failures) - 5} 张截图下载失败")
236
265
  if skipped:
237
266
  _record(diagnostics, f"{skipped} 页没有截图地址(只有文字或空记录)")
238
- if total_bytes > MAX_TOTAL_BYTES:
239
- _record(
240
- diagnostics,
241
- f"截图总大小 {total_bytes // (1024 * 1024)} MiB 超过 "
242
- f"{MAX_TOTAL_BYTES // (1024 * 1024)} MiB,PDF 可能很大",
243
- )
267
+ if stopped and downloaded == 0:
268
+ _record(diagnostics, "截图总大小达到上限且没有成功落盘任何截图")
244
269
 
245
270
  kept: List[Dict[str, Any]] = []
246
271
  duplicates = 0
@@ -392,12 +417,18 @@ def _png_decode(data: bytes) -> Tuple[int, int, bytes, int]:
392
417
  if width * height * channels > 256 * 1024 * 1024:
393
418
  raise SlideError("PNG 解码后超过 256 MiB 上限")
394
419
 
420
+ stride = width * channels
421
+ expected = height * (stride + 1)
422
+ # zlib.decompress() 会先把整个输出物化到内存;用 decompressobj 限制输出,
423
+ # 超出像素数据应有长度就立刻停,而不是等 OOM。
424
+ decompressor = zlib.decompressobj()
395
425
  try:
396
- raw = zlib.decompress(bytes(idat))
426
+ raw = decompressor.decompress(bytes(idat), expected + 1)
397
427
  except zlib.error as error:
398
428
  raise SlideError(f"PNG 解压失败: {error}") from error
429
+ if len(raw) > expected or decompressor.unconsumed_tail:
430
+ raise SlideError("PNG 解压后超过声明的像素数据长度")
399
431
 
400
- stride = width * channels
401
432
  previous = bytearray(stride)
402
433
  samples = bytearray()
403
434
  cursor = 0
@@ -461,9 +492,14 @@ def _page_size(width: int, height: int) -> Tuple[float, float]:
461
492
 
462
493
 
463
494
  def _write_pdf(images: List[Dict[str, Any]], path: str) -> None:
464
- part = path + ".part"
495
+ part = ""
465
496
  try:
466
- with open(part, "wb") as handle:
497
+ descriptor, part = tempfile.mkstemp(
498
+ dir=os.path.dirname(os.path.abspath(path)) or ".",
499
+ prefix=".pdf-",
500
+ suffix=".part",
501
+ )
502
+ with os.fdopen(descriptor, "wb") as handle:
467
503
  count = len(images)
468
504
  total_objects = 2 + count * 3
469
505
  offsets = [0] * (total_objects + 1)
@@ -545,11 +581,13 @@ def _write_pdf(images: List[Dict[str, Any]], path: str) -> None:
545
581
  ).encode("ascii")
546
582
  )
547
583
  os.replace(part, path)
584
+ part = ""
548
585
  except Exception:
549
- try:
550
- os.unlink(part)
551
- except OSError:
552
- pass
586
+ if part:
587
+ try:
588
+ os.unlink(part)
589
+ except OSError:
590
+ pass
553
591
  raise
554
592
 
555
593
 
@@ -387,10 +387,21 @@ _LATEX_SYMBOLS: Dict[str, str] = {
387
387
  "sup": '"sup"', "inf": '"inf"', "Pr": '"Pr"',
388
388
  # 省略号 / 竖排省略号(Typst 的符号名与 LaTeX 不同,这里直接给字符)
389
389
  "cdots": "dots", "vdots": "⋮", "ddots": "⋱",
390
- # 绝对值 / 范数 / 集合分隔
390
+ # 绝对值 / 范数 / 集合分隔。amsmath 的 `\lVert` / `\rVert` 与 `\|` 是范数
391
+ # 竖线,早先漏映射:`\lVert x \rVert` 直接印成 `lVert x rVert`,
392
+ # `\left\lVert … \right\rVert` 更惨,被 `\left` 分支整段吞掉(竖线消失)。
391
393
  "lvert": "|", "rvert": "|", "vert": "|", "mid": "|", "Vert": "‖",
394
+ "lVert": "‖", "rVert": "‖", "|": "‖",
392
395
  # 花括号本身在 Typst 数学里就是字面量,直接放行
393
396
  "{": "{", "}": "}",
397
+ # 定界符尺寸命令只是排版开关,后面的括号由正常流程输出;
398
+ # 不映射的话 `\big(` 会印出单词 `big`。
399
+ "big": "", "Big": "", "bigg": "", "Bigg": "",
400
+ "bigl": "", "bigr": "", "Bigl": "", "Bigr": "",
401
+ "biggl": "", "biggr": "", "Biggl": "", "Biggr": "",
402
+ "middle": "",
403
+ # 百分号:Typst 数学里 `%` 是合法符号,映射一下免得 note_lint 误报「未映射」
404
+ "%": "%",
394
405
  # 反斜杠 + 空格:LaTeX 的显式空格(`0,\ 1,\ 2`)
395
406
  " ": " ",
396
407
  # 长箭头
@@ -470,7 +481,7 @@ _TYPST_BARE_NAMES = (
470
481
  "mat", "cases", "quad", "wide", "thin", "med", "slash",
471
482
  "product", "integral", "sum", "dots",
472
483
  "overbrace", "underbrace", "overline", "underline",
473
- "hat", "tilde", "bar", "vec", "dot", "ddot", "compose",
484
+ "hat", "tilde", "bar", "vec", "dot", "ddot", "compose", "degree",
474
485
  })
475
486
  )
476
487
 
@@ -547,18 +558,41 @@ def _typst_script(content: str) -> str:
547
558
 
548
559
  内容先递归转换一遍:``a_{n=-\\infty}`` 里的 ``\\infty`` 不转换的话,
549
560
  到 Typst 那里就是一个不认识的变量名。
561
+
562
+ **逐字母拆词只针对「还没转换过的裸字母串」。** 转换器自己会产出
563
+ ``alpha`` / ``theta`` / ``compose`` 这类 Typst 名字,它们本身就是**一个**
564
+ 记号;早先不加区分地按 ``[A-Za-z]{2,}`` 拆,于是 ``29^{\\circ}`` 排成
565
+ ``(c o m p o s e)``、``x^{\\alpha}`` 排成 ``(a l p h a)`` —— PDF 的右上角
566
+ 直接印出单词(实地会话 session-42baa52c 的 ``sin 29^{compose}``)。
567
+ 判据就是 :data:`_TYPST_BARE_NAMES`:能裸写的名字不拆,其余照旧拆。
550
568
  """
551
569
  text, _ = latex_to_typst(content)
552
570
  text = text.strip()
553
571
  if not text:
554
572
  return "()"
555
- if re.fullmatch(r"[A-Za-z]{2,}", text):
573
+ if text == "compose":
574
+ # LaTeX 把 ``29^{\\circ}`` 当角度写,``\\circ`` 在上下标里就是度数符号。
575
+ # Typst 的 ``compose`` 是数学轴上的 ∘,``degree`` 才是 °。
576
+ text = "degree"
577
+ if re.fullmatch(r"[A-Za-z]{2,}", text) and text not in _TYPST_BARE_NAMES:
556
578
  return "(" + " ".join(text) + ")"
557
579
  # `=` 在上下标里补空格:Typst 对关系符号更宽容,但补上更稳。
558
580
  text = re.sub(r"\s*=\s*", " = ", text)
559
581
  return "(" + text + ")"
560
582
 
561
583
 
584
+ def _read_script_command(text: str, index: int) -> Tuple[Optional[str], int]:
585
+ """从 ``index`` 处读一个**不带花括号**的上下标记号(只认反斜杠命令)。
586
+
587
+ ``29^\\circ`` / ``\\sum_{n=1}^\\infty`` 里的记号没有花括号,Typst 侧要补一层
588
+ ``(...)`` 才不会被后面紧跟的字母粘住。返回 ``(记号的原文, 结束后的下标)``。
589
+ """
590
+ match = _LATEX_COMMAND_RE.match(text, index)
591
+ if not match:
592
+ return None, index
593
+ return text[index:match.end()], match.end()
594
+
595
+
562
596
  def _read_environment(
563
597
  text: str, index: int, name: str
564
598
  ) -> Tuple[Optional[str], int]:
@@ -805,17 +839,28 @@ def latex_to_typst(expression: str, inline: bool = False) -> Tuple[str, List[str
805
839
  continue
806
840
 
807
841
  if command in ("left", "right"):
808
- # `\left\{` / `\right\}` 是花括号字面量,必须保留转义。
842
+ # `\left⟨分隔符⟩ … \right⟨分隔符⟩` 里**分隔符本身要留下来**。
843
+ # 早先只认 `\{` / `\}`,其余分两种坏法:`\left\lvert`、
844
+ # `\left\|`、`\left\lVert` 被整段吞掉(绝对值 / 范数竖线消失),
845
+ # `\left.` 又把那个点的字面量印进 PDF。这里按符号表落字符,
846
+ # `\left.` / `\right.` 是不可见分隔符,直接跳过。
809
847
  if index < length and expression[index] == "\\":
810
848
  nxt = _LATEX_COMMAND_RE.match(expression, index)
811
849
  if nxt:
812
- if nxt.group(1) == "{":
813
- out.append("\\{")
814
- elif nxt.group(1) == "}":
815
- out.append("\\}")
850
+ name = nxt.group(1)
816
851
  index = nxt.end()
817
- else:
818
- index += 1
852
+ if name == ".":
853
+ continue
854
+ if name in ("{", "}"):
855
+ out.append("\\" + name)
856
+ continue
857
+ _emit(_LATEX_SYMBOLS.get(name, name), index)
858
+ continue
859
+ index += 1
860
+ continue
861
+ if index < length and expression[index] == ".":
862
+ index += 1
863
+ continue
819
864
  continue
820
865
 
821
866
  if command in _LATEX_FRACTIONS:
@@ -1074,6 +1119,19 @@ def latex_to_typst(expression: str, inline: bool = False) -> Tuple[str, List[str
1074
1119
  out.append(char + _typst_script(content))
1075
1120
  index = next_index
1076
1121
  continue
1122
+ # 不带花括号的命令:`29^\circ`、`x^\alpha`、`\sum_{n=1}^\infty`。
1123
+ # 只有反斜杠命令需要补括号;裸字母/数字(`x_1`、`a_n`)在 Typst 里
1124
+ # 本来就是一个记号,动了反而破坏既有输出、也会破坏幂等。
1125
+ if index + 1 < length and expression[index + 1] == "\\":
1126
+ token, after = _read_script_command(expression, index + 1)
1127
+ if token is not None:
1128
+ converted = latex_to_typst(token)[0].strip()
1129
+ if converted:
1130
+ if converted == "compose":
1131
+ converted = "degree"
1132
+ out.append(char + "(" + converted + ")")
1133
+ index = after
1134
+ continue
1077
1135
  out.append(char)
1078
1136
  index += 1
1079
1137
  continue
@@ -1161,7 +1219,7 @@ def typst_string(value: str) -> str:
1161
1219
  return '"' + str(value).replace("\\", "\\\\").replace('"', '\\"') + '"'
1162
1220
 
1163
1221
 
1164
- def escape_typst(text: str, known_labels: Optional[Sequence[str]] = None) -> str:
1222
+ def escape_typst_text(text: str, known_labels: Optional[Sequence[str]] = None) -> str:
1165
1223
  """把一段 Markdown 文本转成可以直接放进 Typst markup 的形式。
1166
1224
 
1167
1225
  Typst 的 markup 有几个会咬人的地方,这里逐个处理:
@@ -1223,6 +1281,35 @@ def escape_typst(text: str, known_labels: Optional[Sequence[str]] = None) -> str
1223
1281
  return restored
1224
1282
 
1225
1283
 
1284
+ #: 正文转义的旧名字;保留给调用方与既有测试。
1285
+ escape_typst = escape_typst_text
1286
+
1287
+
1288
+ def escape_typst_string(value: str) -> str:
1289
+ """Typst 字符串字面量内部转义(不含外层引号)。
1290
+
1291
+ ``escape_typst_text`` 是给 markup 用的,不转义双引号——把它塞进
1292
+ ``"…"`` 里,一个 ``"`` 就能闭合字符串并注入 ``#read(...)``。
1293
+ 这里按 Typst 的字符串语法转义 ``\\``、``"``、换行与制表符,并剥掉
1294
+ 裸 ``\\r``(Typst 只认 ``\\n``)。
1295
+ """
1296
+ text = str(value if value is not None else "").replace("\r\n", "\n")
1297
+ text = text.replace("\r", "")
1298
+ out: List[str] = []
1299
+ for char in text:
1300
+ if char == "\\":
1301
+ out.append("\\\\")
1302
+ elif char == '"':
1303
+ out.append('\\"')
1304
+ elif char == "\n":
1305
+ out.append("\\n")
1306
+ elif char == "\t":
1307
+ out.append("\\t")
1308
+ else:
1309
+ out.append(char)
1310
+ return "".join(out)
1311
+
1312
+
1226
1313
  # --------------------------------------------------------------------- 结果类型
1227
1314
 
1228
1315
 
@@ -1645,7 +1732,7 @@ _TYPST_SAFE_WORDS = (
1645
1732
  "frac", "sqrt", "root", "mat", "cases", "cal", "frak", "bold",
1646
1733
  "upright", "op", "compose", "norm", "abs", "floor", "ceil", "round",
1647
1734
  "diag", "rank", "Res", "tr", "det", "lim", "max", "min", "sup", "inf",
1648
- "wide", "thin", "med", "slash",
1735
+ "wide", "thin", "med", "slash", "degree",
1649
1736
  })
1650
1737
  )
1651
1738
 
@@ -2179,12 +2266,15 @@ def _render_cover(draft_text: str) -> str:
2179
2266
  if not fields:
2180
2267
  return ""
2181
2268
 
2182
- arguments = [f'"{escape_typst(fields["title"])}"'] if fields.get("title") else ['""']
2269
+ # 全部走命名参数,值按字符串字面量转义;位置参数一旦被注入的引号打断,
2270
+ # 后面的 `#read(...)` 就会变成可执行代码。
2271
+ title = fields.get("title") or ""
2272
+ arguments = [f'title: "{escape_typst_string(title)}"']
2183
2273
  for key in ("subtitle", "author", "date", "kicker"):
2184
2274
  value = fields.get(key)
2185
2275
  if value:
2186
- arguments.append(f'{key}: "{escape_typst(value)}"')
2187
- return "#cover(" + ", ".join(arguments) + ")"
2276
+ arguments.append(f'{key}: "{escape_typst_string(value)}"')
2277
+ return "#scholia-cover(" + ", ".join(arguments) + ")"
2188
2278
 
2189
2279
 
2190
2280
  # ----------------------------------------------------------------- 讲义 → 底稿