txt2epub-cli 0.1.0__py3-none-any.whl

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.
@@ -0,0 +1,10 @@
1
+ """txt2epub: an auditable Chinese TXT to EPUB 3 converter."""
2
+
3
+ from __future__ import annotations
4
+
5
+ from importlib.metadata import PackageNotFoundError, version
6
+
7
+ try:
8
+ __version__ = version("txt2epub-cli")
9
+ except PackageNotFoundError: # pragma: no cover - source tree without metadata
10
+ __version__ = "0.0.0"
@@ -0,0 +1,7 @@
1
+ # PYTHON_ARGCOMPLETE_OK
2
+ from __future__ import annotations
3
+
4
+ from txt2epub_cli.cli import main
5
+
6
+ if __name__ == "__main__":
7
+ raise SystemExit(main())
@@ -0,0 +1,523 @@
1
+ """Deterministic heading-candidate detection.
2
+
3
+ A candidate is *not* a heading yet: it is a single-line observation that the
4
+ parser can accept, defer (indented lines) or reject. Keeping detection and
5
+ acceptance apart makes inspect reports honest and testable.
6
+ """
7
+
8
+ from __future__ import annotations
9
+
10
+ import re
11
+ from dataclasses import dataclass, field
12
+
13
+ from .model import HeadingKind, Issue, SourceLine
14
+ from .normalize import normalize_for_match, strip_heading_decoration
15
+ from .rules import NUM, RuleSet
16
+
17
+ _VOLUME_SEPARATORS = " \t\u3000::、,,.-—"
18
+ _SPECIAL_PREFIX_SEPARATORS = " \u3000::,,"
19
+ _FOREIGN_SENTENCE_PUNCTUATION = "。!?;,、:“”‘’…"
20
+
21
+
22
+ @dataclass(slots=True)
23
+ class Candidate:
24
+ raw: str
25
+ normalized: str
26
+ line_no: int
27
+ kind: HeadingKind
28
+ family: str
29
+ number: str | None
30
+ title: str
31
+ separator: str
32
+ indent: str
33
+ confidence: float
34
+ issues: list[Issue] = field(default_factory=list)
35
+ deferred: bool = False
36
+ detail: dict = field(default_factory=dict)
37
+
38
+
39
+ def _group(match: re.Match[str], name: str) -> str:
40
+ value = match.groupdict().get(name)
41
+ return value or ""
42
+
43
+
44
+ def _title_of(match: re.Match[str]) -> str:
45
+ return _group(match, "title").strip()
46
+
47
+
48
+ def _unit_after(text: str, index: int) -> str:
49
+ if 0 <= index < len(text):
50
+ return text[index]
51
+ return ""
52
+
53
+
54
+ def _between_unit_and_title(text: str, unit_index: int, title: str) -> str:
55
+ remainder = text[unit_index + 1 :]
56
+ if title and remainder.endswith(title):
57
+ between = remainder[: len(remainder) - len(title)]
58
+ else:
59
+ between = remainder[:3]
60
+ return between[:3]
61
+
62
+
63
+ def _apply_length_limit(candidate: Candidate, text: str, rules: RuleSet) -> Candidate:
64
+ if len(text) > rules.max_heading_length:
65
+ candidate.confidence = 0.2
66
+ candidate.issues.append(
67
+ Issue(
68
+ severity="warning",
69
+ code="too_long",
70
+ line_no=candidate.line_no,
71
+ message=(
72
+ f"heading candidate is too long ({len(text)} > {rules.max_heading_length})"
73
+ ),
74
+ detail={"length": len(text), "limit": rules.max_heading_length},
75
+ )
76
+ )
77
+ return candidate
78
+
79
+
80
+ def _build(
81
+ line: SourceLine,
82
+ text: str,
83
+ *,
84
+ kind: HeadingKind,
85
+ family: str,
86
+ number: str | None,
87
+ title: str,
88
+ separator: str,
89
+ confidence: float,
90
+ detail: dict | None = None,
91
+ ) -> Candidate:
92
+ candidate = Candidate(
93
+ raw=line.raw,
94
+ normalized=normalize_for_match(text),
95
+ line_no=line.line_no,
96
+ kind=kind,
97
+ family=family,
98
+ number=number,
99
+ title=title,
100
+ separator=separator,
101
+ indent=line.indent,
102
+ confidence=confidence,
103
+ deferred=bool(line.indent),
104
+ detail=detail or {},
105
+ )
106
+ if line.indent:
107
+ candidate.detail["indented"] = True
108
+ return candidate
109
+
110
+
111
+ def _volume_components(volume_text: str, rules: RuleSet) -> tuple[str, str, str, str]:
112
+ """Return (number, title, unit, separator) for a volume prefix."""
113
+ for pattern in rules.volume_patterns:
114
+ match = pattern.match(volume_text)
115
+ if not match:
116
+ continue
117
+ number = _group(match, "num")
118
+ number_end = match.end("num")
119
+ unit_index = (
120
+ match.start("num") - 1 if volume_text.startswith("卷") else number_end
121
+ )
122
+ unit = _unit_after(volume_text, unit_index)
123
+ title = _title_of(match)
124
+ separator = _between_unit_and_title(volume_text, number_end, title)
125
+ return number, title, unit, separator
126
+
127
+ match = re.match(rf"^(?:第)?(?P<num>[{NUM}]+)[卷部篇册](?P<rest>.*)$", volume_text)
128
+ if match:
129
+ number = match.group("num")
130
+ unit = _unit_after(volume_text, match.end("num"))
131
+ rest = match.group("rest").lstrip(_VOLUME_SEPARATORS)
132
+ return number, rest, unit, ""
133
+ return "", "", "", ""
134
+
135
+
136
+ def _chapter_components(
137
+ chapter_text: str, rules: RuleSet
138
+ ) -> tuple[str, str | None, str, str, str]:
139
+ """Return (number, number2, title, unit, separator) for chapter text."""
140
+ span_patterns = [
141
+ pattern for pattern in rules.chapter_patterns if "num2" in pattern.groupindex
142
+ ]
143
+ for pattern in span_patterns:
144
+ match = pattern.match(chapter_text)
145
+ if not match:
146
+ continue
147
+ number = _group(match, "num")
148
+ number2 = _group(match, "num2")
149
+ title = _title_of(match)
150
+ unit_index = match.end("num2")
151
+ unit = _unit_after(chapter_text, unit_index)
152
+ separator = _between_unit_and_title(chapter_text, unit_index, title)
153
+ return number, number2, title, unit, separator
154
+
155
+ for pattern in rules.chapter_patterns:
156
+ if "num2" in pattern.groupindex:
157
+ continue
158
+ match = pattern.match(chapter_text)
159
+ if not match:
160
+ continue
161
+ number = _group(match, "num")
162
+ title = _title_of(match)
163
+ unit_index = match.end("num")
164
+ unit = _unit_after(chapter_text, unit_index)
165
+ separator = _between_unit_and_title(chapter_text, unit_index, title)
166
+ return number, None, title, unit, separator
167
+
168
+ fallback = re.match(
169
+ rf"^第(?P<num>[{NUM}]+)[章节回集幕](?:[\s\u3000::]*(?P<title>.*))?$",
170
+ chapter_text,
171
+ )
172
+ if fallback:
173
+ number = _group(fallback, "num")
174
+ title = _title_of(fallback)
175
+ unit_index = fallback.end("num")
176
+ unit = _unit_after(chapter_text, unit_index)
177
+ separator = _between_unit_and_title(chapter_text, unit_index, title)
178
+ return number, None, title, unit, separator
179
+
180
+ return "", None, chapter_text, "", ""
181
+
182
+
183
+ def _record_decorated(candidate: Candidate, decorated: bool) -> Candidate:
184
+ if decorated:
185
+ candidate.detail["decorated"] = True
186
+ return candidate
187
+
188
+
189
+ def _is_volume_false_positive(text: str, match: re.Match[str], rules: RuleSet) -> bool:
190
+ number_end = match.end("num")
191
+ unit = _unit_after(text, number_end)
192
+ if unit not in {"部", "篇", "册"}:
193
+ return False
194
+ rest = text[number_end + 1 :]
195
+ return bool(rest) and rest[0] in rules.invalid_volume_suffixes
196
+
197
+
198
+ def _is_chapter_false_positive(text: str, match: re.Match[str], rules: RuleSet) -> bool:
199
+ number_end = match.end("num")
200
+ unit = _unit_after(text, number_end)
201
+ if unit != "回":
202
+ return False
203
+ after_number = text[number_end:]
204
+ after_unit = text[number_end + 1 :]
205
+ return any(
206
+ after_number.startswith(suffix) or after_unit.startswith(suffix)
207
+ for suffix in rules.invalid_chapter_suffixes
208
+ )
209
+
210
+
211
+ def _detect_combined(line: SourceLine, text: str, rules: RuleSet) -> Candidate | None:
212
+ for pattern in rules.combined_patterns:
213
+ match = pattern.match(text)
214
+ if not match:
215
+ continue
216
+ volume_raw = _group(match, "volume").strip()
217
+ volume_number, volume_title, volume_unit, _ = _volume_components(
218
+ volume_raw, rules
219
+ )
220
+ if not volume_number:
221
+ volume_number = _group(match, "vnum")
222
+ chapter_raw = _group(match, "chapter").strip()
223
+ _, _, chapter_title, chapter_unit, separator = _chapter_components(
224
+ chapter_raw, rules
225
+ )
226
+ number = _group(match, "cnum")
227
+ return _build(
228
+ line,
229
+ text,
230
+ kind=HeadingKind.CHAPTER,
231
+ family="combined_prefix",
232
+ number=number,
233
+ title=chapter_title,
234
+ separator=separator,
235
+ confidence=0.98,
236
+ detail={
237
+ "combined": True,
238
+ "volume_raw": volume_raw,
239
+ "volume_number": volume_number,
240
+ "volume_title": volume_title,
241
+ "volume_unit": volume_unit,
242
+ "chapter_unit": chapter_unit,
243
+ },
244
+ )
245
+ return None
246
+
247
+
248
+ def _detect_chapter_span(
249
+ line: SourceLine, text: str, rules: RuleSet
250
+ ) -> Candidate | None:
251
+ for pattern in rules.chapter_patterns:
252
+ if "num2" not in pattern.groupindex:
253
+ continue
254
+ match = pattern.match(text)
255
+ if not match:
256
+ continue
257
+ number = _group(match, "num")
258
+ number2 = _group(match, "num2")
259
+ title = _title_of(match)
260
+ unit_index = match.end("num2")
261
+ separator = _between_unit_and_title(text, unit_index, title)
262
+ return _build(
263
+ line,
264
+ text,
265
+ kind=HeadingKind.CHAPTER,
266
+ family="chapter_span",
267
+ number=number,
268
+ title=title,
269
+ separator=separator,
270
+ confidence=0.95,
271
+ detail={"number2": number2},
272
+ )
273
+ return None
274
+
275
+
276
+ def _detect_volume(line: SourceLine, text: str, rules: RuleSet) -> Candidate | None:
277
+ for pattern in rules.volume_patterns:
278
+ match = pattern.match(text)
279
+ if not match:
280
+ continue
281
+ if _is_volume_false_positive(text, match, rules):
282
+ return None
283
+ number = _group(match, "num")
284
+ number_end = match.end("num")
285
+ family = "volume_juan" if text.startswith("卷") else "volume_di"
286
+ unit_index = match.start("num") - 1 if family == "volume_juan" else number_end
287
+ unit = _unit_after(text, unit_index)
288
+ title = _title_of(match)
289
+ separator = _between_unit_and_title(text, number_end, title)
290
+ return _build(
291
+ line,
292
+ text,
293
+ kind=HeadingKind.VOLUME,
294
+ family=family,
295
+ number=number,
296
+ title=title,
297
+ separator=separator,
298
+ confidence=0.95 if family == "volume_di" else 0.9,
299
+ detail={"unit": unit},
300
+ )
301
+ return None
302
+
303
+
304
+ def _detect_chapter(line: SourceLine, text: str, rules: RuleSet) -> Candidate | None:
305
+ for pattern in rules.chapter_patterns:
306
+ if "num2" in pattern.groupindex:
307
+ continue
308
+ match = pattern.match(text)
309
+ if not match:
310
+ continue
311
+ number_end = match.end("num")
312
+ unit = _unit_after(text, number_end)
313
+ if unit == "节":
314
+ # Section patterns own this unit; leave it for the next detector.
315
+ continue
316
+ if _is_chapter_false_positive(text, match, rules):
317
+ return None
318
+ number = _group(match, "num")
319
+ title = _title_of(match)
320
+ separator = _between_unit_and_title(text, number_end, title)
321
+ if number.isdigit() and number.startswith("0") and len(number) > 1:
322
+ family = "chapter_zero_padded"
323
+ elif title and not separator:
324
+ family = "chapter_no_sep"
325
+ else:
326
+ family = "chapter_di"
327
+ confidence = 0.85 if family == "chapter_no_sep" else 0.95
328
+ return _build(
329
+ line,
330
+ text,
331
+ kind=HeadingKind.CHAPTER,
332
+ family=family,
333
+ number=number,
334
+ title=title,
335
+ separator=separator,
336
+ confidence=confidence,
337
+ detail={"unit": unit},
338
+ )
339
+ return None
340
+
341
+
342
+ def _detect_section(line: SourceLine, text: str, rules: RuleSet) -> Candidate | None:
343
+ for pattern in rules.section_patterns:
344
+ match = pattern.match(text)
345
+ if not match:
346
+ continue
347
+ number = _group(match, "num")
348
+ title = _title_of(match)
349
+ unit_index = match.end("num")
350
+ unit = _unit_after(text, unit_index)
351
+ separator = _between_unit_and_title(text, unit_index, title)
352
+ return _build(
353
+ line,
354
+ text,
355
+ kind=HeadingKind.SECTION,
356
+ family="section_di",
357
+ number=number,
358
+ title=title,
359
+ separator=separator,
360
+ confidence=0.9,
361
+ detail={"unit": unit},
362
+ )
363
+ return None
364
+
365
+
366
+ def _special_candidate_from_match(
367
+ line: SourceLine,
368
+ text: str,
369
+ match: re.Match[str],
370
+ separator: str = "",
371
+ *,
372
+ custom: bool,
373
+ ) -> Candidate:
374
+ title = _group(match, "title").strip()
375
+ if not title:
376
+ title = _group(match, "special").strip()
377
+ if not title:
378
+ title = text
379
+ detail = {"custom": True} if custom else {}
380
+ return _build(
381
+ line,
382
+ text,
383
+ kind=HeadingKind.SPECIAL,
384
+ family="special",
385
+ number=None,
386
+ title=title,
387
+ separator=separator,
388
+ confidence=0.9 if custom else 0.95,
389
+ detail=detail,
390
+ )
391
+
392
+
393
+ def _detect_special(line: SourceLine, text: str, rules: RuleSet) -> Candidate | None:
394
+ if text in rules.special_titles:
395
+ return _build(
396
+ line,
397
+ text,
398
+ kind=HeadingKind.SPECIAL,
399
+ family="special",
400
+ number=None,
401
+ title=text,
402
+ separator="",
403
+ confidence=0.95,
404
+ detail={"exact": True},
405
+ )
406
+
407
+ for special in sorted(rules.special_titles, key=len, reverse=True):
408
+ if not text.startswith(special):
409
+ continue
410
+ next_char = text[len(special) : len(special) + 1]
411
+ if not next_char or next_char not in _SPECIAL_PREFIX_SEPARATORS:
412
+ continue
413
+ remainder = text[len(special) + 1 :].strip()
414
+ return _build(
415
+ line,
416
+ text,
417
+ kind=HeadingKind.SPECIAL,
418
+ family="special",
419
+ number=None,
420
+ title=remainder or special,
421
+ separator="",
422
+ confidence=0.9,
423
+ detail={"prefix": special},
424
+ )
425
+
426
+ if text.endswith("完本感言") and len(text) <= 30:
427
+ return _build(
428
+ line,
429
+ text,
430
+ kind=HeadingKind.SPECIAL,
431
+ family="special",
432
+ number=None,
433
+ title=text,
434
+ separator="",
435
+ confidence=0.9,
436
+ detail={"suffix": "完本感言"},
437
+ )
438
+
439
+ if (
440
+ "外传" in text
441
+ and len(text) <= 30
442
+ and not any(char in text for char in _FOREIGN_SENTENCE_PUNCTUATION)
443
+ and (text.startswith("外传") or text.endswith("外传") or "外传·" in text)
444
+ ):
445
+ return _build(
446
+ line,
447
+ text,
448
+ kind=HeadingKind.SPECIAL,
449
+ family="special",
450
+ number=None,
451
+ title=text,
452
+ separator="",
453
+ confidence=0.85,
454
+ detail={"contains": "外传"},
455
+ )
456
+
457
+ for pattern in rules.special_patterns:
458
+ match = pattern.match(text)
459
+ if match:
460
+ return _special_candidate_from_match(line, text, match, custom=True)
461
+ return None
462
+
463
+
464
+ def _detect_pure_number(
465
+ line: SourceLine, text: str, rules: RuleSet
466
+ ) -> Candidate | None:
467
+ if not rules.pure_number_headings:
468
+ return None
469
+ for pattern in rules.pure_number_patterns:
470
+ match = pattern.match(text)
471
+ if not match:
472
+ continue
473
+ number = _group(match, "num")
474
+ title = _title_of(match)
475
+ unit_index = match.end("num")
476
+ separator = _between_unit_and_title(text, unit_index, title)
477
+ return _build(
478
+ line,
479
+ text,
480
+ kind=HeadingKind.CHAPTER,
481
+ family="pure_number",
482
+ number=number,
483
+ title=title,
484
+ separator=separator,
485
+ confidence=0.7,
486
+ )
487
+ return None
488
+
489
+
490
+ def detect_candidate(line: SourceLine, rules: RuleSet) -> Candidate | None:
491
+ """Detect one heading candidate on a single source line."""
492
+ if not line.stripped.strip():
493
+ return None
494
+
495
+ text = strip_heading_decoration(line.stripped).strip()
496
+ if not text:
497
+ return None
498
+ decorated = text != line.stripped
499
+
500
+ candidate = (
501
+ _detect_combined(line, text, rules)
502
+ or _detect_chapter_span(line, text, rules)
503
+ or _detect_volume(line, text, rules)
504
+ or _detect_chapter(line, text, rules)
505
+ or _detect_section(line, text, rules)
506
+ or _detect_special(line, text, rules)
507
+ or _detect_pure_number(line, text, rules)
508
+ )
509
+ if candidate is None:
510
+ return None
511
+
512
+ _record_decorated(candidate, decorated)
513
+ return _apply_length_limit(candidate, text, rules)
514
+
515
+
516
+ def detect_candidates(lines: list[SourceLine], rules: RuleSet) -> list[Candidate]:
517
+ """Return all candidates, preserving source line order."""
518
+ candidates: list[Candidate] = []
519
+ for line in lines:
520
+ candidate = detect_candidate(line, rules)
521
+ if candidate is not None:
522
+ candidates.append(candidate)
523
+ return candidates