python-hwpx 7.0.0__py3-none-any.whl → 7.0.1__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.
hwpx/capabilities.py CHANGED
@@ -39,13 +39,21 @@ _DIST_NAME = "python-hwpx"
39
39
 
40
40
  #: extras 이름 → 그 extra가 끄는 런타임 모듈들. ``visual``은 5.0부터, ``xlsx``·``preview``는
41
41
  #: 7.0부터(메일 머지·미리보기가 python-hwpx-automation으로 옮겨 갔다) 의도적으로 빈
42
- #: extra(설치 호환 유지용)라 백킹 모듈이 없고, 프로브는 공허하게 참이다.
42
+ #: extra(설치 호환 유지용)라 백킹 모듈이 없다. 아무것도 끌어오지 않으니 보고는 거짓이다
43
+ #: (6.x~7.0.0은 "백킹 모듈이 없으니 공허하게 참"으로 보고해, 맨 설치에서도 설치된 것으로 읽혔다).
43
44
  _EXTRA_MODULES: dict[str, tuple[str, ...]] = {
44
45
  "visual": (),
45
46
  "xlsx": (),
46
47
  "preview": (),
47
48
  }
48
49
 
50
+ #: ``extras`` 옆에 싣는 설명. 값이 모두 거짓인 까닭과 그 기능이 있는 곳.
51
+ _EXTRAS_NOTE = (
52
+ "visual·xlsx·preview 는 예전 설치 명령(pip install \"python-hwpx[visual]\" 등)이 깨지지 "
53
+ "않도록 이름만 남긴 빈 extra입니다. 설치해도 core에 더해지는 것이 없어 false 로 보고합니다. "
54
+ "그 기능(렌더·시각 검증, xlsx 메일 머지, 미리보기)은 python-hwpx-automation 에 있습니다."
55
+ )
56
+
49
57
  #: 능력 영역 레지스트리. ``matrix_row``는 ``docs/support-matrix.md`` 표 1열
50
58
  #: 제목과 **정확히** 일치해야 한다(가드 테스트가 집합 대조). ``entry_points``는
51
59
  #: ``"모듈:이름"`` — 전부 import 가능해야 한다(가드 테스트가 해석).
@@ -508,15 +516,16 @@ _LEGACY_REMOVED_IN = "7.0"
508
516
 
509
517
 
510
518
  def _extra_installed(extra: str) -> bool:
511
- """extra 설치 여부.
519
+ """그 extra가 이 설치에 기능을 더했는지.
512
520
 
513
521
  7.0의 extras는 전부 의도적으로 빈 extra다(설치 호환 유지 — ``visual``은 5.0부터,
514
- ``xlsx``·``preview``는 7.0부터). 백킹 모듈이 없으니 공허하게 참이다. 동적 프로브
515
- (find_spec/import_module)는 쓰지 않는다 — core의 importlib 표면은 boundary ratchet상
516
- ``from importlib import resources`` 한 형태뿐이다.
522
+ ``xlsx``·``preview``는 7.0부터). 끌어오는 모듈이 없으니 설치했든 안 했든 core에
523
+ 더해지는 것이 없다: 거짓이다(:data:`_EXTRAS_NOTE`). 백킹 모듈이 있는 extra는 지금
524
+ 없고, 생기더라도 동적 프로브(find_spec/import_module)는 쓰지 않는다 — core의 importlib
525
+ 표면은 boundary ratchet상 ``from importlib import resources`` 한 형태뿐이다.
517
526
  """
518
527
 
519
- return not _EXTRA_MODULES.get(extra, ())
528
+ return False
520
529
 
521
530
 
522
531
  def _package_version() -> str:
@@ -533,7 +542,8 @@ def _package_version() -> str:
533
542
  def describe_capabilities() -> dict[str, Any]:
534
543
  """설치된 core의 기계가독 자기서술 — ``hwpx.capabilities/v1``.
535
544
 
536
- 전부 실측이다: 버전은 배포 메타데이터, extras는 import 프로브, 표면 목록은
545
+ 전부 실측이다: 버전은 배포 메타데이터, extras는 그 extra가 끌어오는 것(빈 extra는
546
+ 거짓, 까닭은 ``extrasNote``), 표면 목록은
537
547
  라이브 ``__all__``, op 어휘는 실행기 디스패치와 같은 표. 렌더 오라클은
538
548
  core에 없다는 사실 자체를 보고한다(측정 없는 가용성 주장 금지).
539
549
  """
@@ -547,6 +557,7 @@ def describe_capabilities() -> dict[str, Any]:
547
557
  "package": {"name": _DIST_NAME, "version": _package_version()},
548
558
  "python": platform.python_version(),
549
559
  "extras": {name: _extra_installed(name) for name in _EXTRA_MODULES},
560
+ "extrasNote": _EXTRAS_NOTE,
550
561
  "renderOracle": {
551
562
  "bundled": "none",
552
563
  "note": (
@@ -777,6 +788,7 @@ def _capabilities_json_schema() -> dict[str, Any]:
777
788
  "type": "object",
778
789
  "additionalProperties": {"type": "boolean"},
779
790
  },
791
+ "extrasNote": {"type": "string"},
780
792
  "renderOracle": {
781
793
  "type": "object",
782
794
  "required": ["bundled", "note"],
@@ -0,0 +1,494 @@
1
+ # SPDX-License-Identifier: Apache-2.0
2
+ """Tell a line cache that outlived the paragraph content it was computed for.
3
+
4
+ Hancom trusts the line count of a cached ``hp:linesegarray`` and presses the
5
+ text into it, so a cache left on a paragraph whose content changed is worse
6
+ than no cache. The editing APIs clear the cache of the paragraph they change;
7
+ this is the net under them, for an API that forgets to. It needs no estimate
8
+ of text widths: a cache is kept only on the content it came with.
9
+
10
+ A section keeps hold of the cache elements its part was read with
11
+ (:class:`TrackedCaches`). At the save of an edited section, and before and
12
+ after a table's structure edit (which builds the table's rows and cells again,
13
+ as new elements the save could no longer pair with what was read), each of
14
+ them that is still in the tree is compared with the part as it was read: when
15
+ the content of its paragraph differs, the cache goes. A cache made or
16
+ rewritten since (a cleared one written again on purpose, a copied
17
+ paragraph's) is not what the part was read with and is left alone.
18
+
19
+ Every judgement looks at every cache of the section, so a caller can rely on
20
+ any cache it finds after one. What keeps that from costing a digest of each
21
+ paragraph each time is in the class below: a paragraph of the section's body
22
+ that is, at this judgement, what it was at the last one holds nothing to judge
23
+ again. Nothing is taken on trust between two judgements -- what an edit, a
24
+ ``mark_dirty()`` or anything else did to the tree in between shows in what is
25
+ compared, or the block is judged cache by cache.
26
+ """
27
+
28
+ from __future__ import annotations
29
+
30
+ import hashlib
31
+ import re
32
+ from typing import Any
33
+
34
+ from lxml import etree as LET # type: ignore[reportAttributeAccessIssue] # lxml has no complete bundled typing
35
+
36
+ __all__ = ["TrackedCaches", "cache_elements"]
37
+
38
+ _CACHE_BYTES_RE = re.compile(
39
+ rb"<(?P<ns>(?:[A-Za-z_][\w.-]*:)?)linesegarray\b(?:[^>]*?/>|[^>]*>.*?</(?P=ns)linesegarray>)",
40
+ re.DOTALL | re.IGNORECASE,
41
+ )
42
+
43
+ #: A watched cache element, the digest of the content its paragraph had with it, and the cache as it was.
44
+ _Watched = tuple[Any, bytes, bytes]
45
+ #: What a block is, as far as any digest or cache comparison inside it can tell (:func:`_block_state`).
46
+ _State = tuple[bytes, Any, tuple[Any, ...]]
47
+ #: A child of the section's root that holds caches, its state when every cache in it was last judged (``None``:
48
+ #: one of them went then, so the next judgement looks at each again), and the caches left in it.
49
+ _Block = tuple[Any, "_State | None", tuple[Any, ...]]
50
+
51
+
52
+ def _entry(table: dict[int, Any], element: Any) -> Any:
53
+ """What *table* holds for *element*, or ``None``. Every table is keyed by ``id()`` and each entry starts
54
+ with the element it was made for: an entry counts only when that is *element* itself. While an entry
55
+ holds its element, lxml keeps that element's proxy and no other element can take its id -- but a copy
56
+ of the tables (``copy.deepcopy`` of a document) keeps the ids of the elements it was copied from,
57
+ which elements of the copy can be given once those are gone."""
58
+
59
+ found = table.get(id(element))
60
+ return found if found is not None and found[0] is element else None
61
+
62
+
63
+ def _local(node: Any) -> str:
64
+ tag = node.tag
65
+ return tag.rpartition("}")[2] if isinstance(tag, str) else ""
66
+
67
+
68
+ def _is_cache(tag: Any) -> bool:
69
+ return isinstance(tag, str) and tag.rpartition("}")[2].lower() == "linesegarray"
70
+
71
+
72
+ def cache_elements(root: Any) -> list[Any]:
73
+ """The line caches under *root* that sit directly in a paragraph, in document order."""
74
+
75
+ found = []
76
+ cache_tags: dict[Any, bool] = {} # a part has a handful of tags and tens of thousands of nodes
77
+ for node in root.iter():
78
+ tag = node.tag
79
+ is_cache = cache_tags.get(tag)
80
+ if is_cache is None:
81
+ is_cache = cache_tags[tag] = _is_cache(tag)
82
+ if is_cache:
83
+ parent = node.getparent()
84
+ if parent is not None and _local(parent) == "p":
85
+ found.append(node)
86
+ return found
87
+
88
+
89
+ def _content_digest(paragraph: Any) -> bytes:
90
+ """A digest of everything in *paragraph* but line caches (its own and those of paragraphs inside it)."""
91
+
92
+ content = _CACHE_BYTES_RE.sub(b"", LET.tostring(paragraph, with_tail=False))
93
+ return hashlib.blake2b(content, digest_size=16).digest()
94
+
95
+
96
+ def _whole_bytes(block: Any) -> bytes:
97
+ """Everything in *block*, line caches too, as it serialises."""
98
+
99
+ return LET.tostring(block, with_tail=False) # type: ignore[no-any-return]
100
+
101
+
102
+ def _declared_on(element: Any) -> tuple[Any, ...]:
103
+ """The namespace declarations *element* itself carries, in order (prefix, URI)."""
104
+
105
+ found = []
106
+ # lxml reports an element's own declarations as the events before the element's start
107
+ for event, value in LET.iterwalk(element, events=("start-ns", "start")):
108
+ if event != "start-ns":
109
+ break
110
+ found.append(value)
111
+ return tuple(found)
112
+
113
+
114
+ def _names_above(node: Any, block: Any, known: dict[int, tuple[Any, tuple[Any, ...]]]) -> tuple[Any, ...]:
115
+ """The qualified names of the elements above *node* up to *block*, nearest first.
116
+
117
+ *known* holds what was found for an element already, with the element so that its id stays its own.
118
+ Built going up and without recursion: a tree made in code may hold a paragraph any depth down."""
119
+
120
+ climbed = []
121
+ current = node
122
+ names: tuple[Any, ...] = ()
123
+ while current is not block:
124
+ found = known.get(id(current))
125
+ if found is not None and found[0] is current:
126
+ names = found[1]
127
+ break
128
+ climbed.append(current)
129
+ current = current.getparent()
130
+ for element in reversed(climbed): # nearest the block first, each from the one above it
131
+ names = (element.getparent().tag, *names)
132
+ known[id(element)] = (element, names)
133
+ return names
134
+
135
+
136
+ def _block_state(block: Any, caches: list[Any], data: bytes) -> _State:
137
+ """Everything that goes into the digest of a paragraph in *block* and into the bytes of a cache in it.
138
+
139
+ Both are serialisations of an element inside the block. lxml writes such an element as a copy
140
+ of its start tag followed by the element's content as it stands in the tree. The content is
141
+ in *data*, the block's own serialisation, byte for byte. The copy's start tag is put together
142
+ from more than the element's own, and this is the whole of it (libxml2's ``xmlStaticCopyNode``
143
+ and ``xmlSearchNs``, lxml's ``_copyParentNamespaces``):
144
+
145
+ 1. the element's own declarations;
146
+ 2. a declaration for the prefix of its name, when it carries none: the namespace found by going
147
+ up from the element, at each element above taking a declaration of that prefix it carries or
148
+ else, where its own name is written with that prefix, the namespace its name is in;
149
+ 3. the same for each attribute's prefix -- and where the copy already has that prefix for
150
+ another namespace than the attribute's, a prefix made up for the attribute's namespace;
151
+ 4. every declaration carried by the elements above, nearest first, one per prefix.
152
+
153
+ What that reads and *data* does not hold: which declarations the block itself carries (its
154
+ start tag in *data* is such a copy, own and inherited alike) and which each element over it
155
+ does, in what order; the namespace each element above the one serialised is in, and its
156
+ attributes' namespaces (an element is written with its prefix, whatever a nearer declaration
157
+ makes of that prefix -- lxml leaves elements bound past such a declaration when it takes in
158
+ a subtree -- and an element without a prefix may be in the default namespace or in none).
159
+
160
+ So with the digest of *data* the state holds: the declarations carried by the block and by
161
+ each element over it, with that element's prefix and qualified name; and for each cache the
162
+ qualified names of the cache, of the paragraph holding it, of their attributes and of every
163
+ element between the paragraph and the block.
164
+ """
165
+
166
+ known: dict[int, tuple[Any, tuple[Any, ...]]] = {}
167
+ names = []
168
+ for cache in caches:
169
+ paragraph = cache.getparent()
170
+ names.append(
171
+ (
172
+ cache.tag,
173
+ tuple(cache.keys()),
174
+ paragraph.tag,
175
+ tuple(paragraph.keys()),
176
+ _names_above(paragraph, block, known),
177
+ )
178
+ )
179
+ over = tuple((_declared_on(node), node.prefix, node.tag) for node in block.iterancestors())
180
+ return hashlib.blake2b(data, digest_size=16).digest(), (_declared_on(block), over), tuple(names)
181
+
182
+
183
+ _STATES_DECIDE: bool | None = None
184
+
185
+
186
+ def _states_decide() -> bool:
187
+ """Whether this lxml gives :func:`_block_state` what it takes it to, checked once on small trees.
188
+
189
+ An element's own declarations must be reported as they are. A tree parsed twice must give one
190
+ state and the same serialisations inside. And three pairs of blocks alike in every byte, in
191
+ which elements inside serialise differently, must differ in state where they do: declarations
192
+ in another order over the block; an element above a paragraph bound past a nearer declaration
193
+ of its prefix; a block that carries a declaration against one that inherits it. Where any of
194
+ it does not hold, no block is taken as unchanged: each cache is judged with its own digest
195
+ every time, as before."""
196
+
197
+ global _STATES_DECIDE
198
+ if _STATES_DECIDE is None:
199
+ declared = LET.fromstring('<r xmlns:a="u:a"><w xmlns:b="u:b" xmlns:a="u:a" xmlns="u:d"><a:p/></w></r>')
200
+ inside = '<a:p b:k="1"><c/><d xmlns="u:d"/><a:linesegarray/></a:p>'
201
+ plain = f'<r xmlns:a="u:a" xmlns:b="u:b"><w>{inside}</w></r>'
202
+
203
+ def taking_in(root: str, subtree: str) -> Any:
204
+ # a subtree whose top declares the root's namespace again as z: lxml strips that and
205
+ # binds what used it to the root's declaration, past whatever declares the prefix between
206
+ top = LET.fromstring(root)
207
+ top.append(LET.fromstring(subtree))
208
+ return top.find(".//*[@id='b']")
209
+
210
+ held = "<a:p><a:linesegarray/></a:p>"
211
+ hidden = taking_in('<r xmlns:a="u:a"/>', f'<z:e xmlns:z="u:a" id="b"><a:m xmlns:a="u:x"><z:d>{held}</z:d></a:m></z:e>')
212
+ carried = taking_in('<r xmlns:a="u:a"/>', f'<z:e xmlns:z="u:a"><z:k xmlns:a="u:x" id="b">{held}</z:k></z:e>')
213
+ inherited = taking_in('<r xmlns:a="u:a"/>', f'<z:e xmlns:z="u:a" xmlns:a="u:x"><z:k id="b">{held}</z:k></z:e>')
214
+ trees = [
215
+ LET.fromstring(plain)[0][0],
216
+ LET.fromstring(plain)[0][0],
217
+ LET.fromstring(f'<r xmlns:b="u:b" xmlns:a="u:a"><w>{inside}</w></r>')[0][0],
218
+ hidden,
219
+ LET.fromstring(LET.tostring(hidden.getparent())).find(".//*[@id='b']"),
220
+ carried,
221
+ inherited,
222
+ ]
223
+ states = [_block_state(block, cache_elements(block), _whole_bytes(block)) for block in trees]
224
+ parts = [[LET.tostring(node, with_tail=False) for node in block.iter()] for block in trees]
225
+ _STATES_DECIDE = (
226
+ [_declared_on(node) for node in declared.iter()]
227
+ == [(("a", "u:a"),), (("b", "u:b"), ("a", "u:a"), ("", "u:d")), ()]
228
+ and states[0] == states[1]
229
+ and parts[0] == parts[1]
230
+ and all(states[one] != states[other] or parts[one] == parts[other] for one, other in ((0, 2), (3, 4), (5, 6)))
231
+ )
232
+ return _STATES_DECIDE
233
+
234
+
235
+ def _as_it_is(cache: Any) -> _Watched:
236
+ return cache, _content_digest(cache.getparent()), LET.tostring(cache, with_tail=False)
237
+
238
+
239
+ def _block_of(root: Any, element: Any) -> Any:
240
+ """The child of *root* that *element* is in (or is), or ``None`` when it is not under *root*."""
241
+
242
+ node = element
243
+ while node is not None:
244
+ parent = node.getparent()
245
+ if parent is root:
246
+ return node
247
+ node = parent
248
+ return None
249
+
250
+
251
+ class TrackedCaches:
252
+ """The line caches a section watches, each with the content its paragraph had when it was last judged.
253
+
254
+ The rule (:meth:`_judge`) is the one a judgement has always applied to each cache in the tree, in
255
+ document order: a watched cache that is still the bytes it was while its paragraph's content is not
256
+ goes, and every other cache is watched from then on with the content its paragraph has now. A
257
+ judgement (:meth:`judge_all`) leaves exactly what applying that rule to every cache of the section
258
+ leaves. It spends less than a digest of every paragraph by two things, each checked at the judgement
259
+ itself against the tree as it is then:
260
+
261
+ * **A block that is what it was is not judged again.** A block is a child of the section's root
262
+ (a body paragraph, with whatever tables it holds). Every judgement takes the state
263
+ (:func:`_block_state`) of every block that holds a cache. When that is the state the block had
264
+ at the last judgement, the block holds the same cache elements in the same order, and no cache
265
+ of it went at that judgement, then each paragraph in it has the content, and each cache the
266
+ bytes, its entry was made with, so the rule keeps every one with the same entry. A block in
267
+ which the rule dropped a cache is judged cache by cache the next time: the paragraphs around
268
+ the dropped cache were digested before it went, and it may have taken text after it along.
269
+ * **What the part was read with is not digested until it differs.** The caches as read
270
+ (*caches*, with the part's bytes *source_xml*) start out watched "as read". The first judgement
271
+ parses the part again, as it always did, and a block in the state of the block it was read as,
272
+ with the caches read in it, keeps them "as read": their entries are what a digest of the parsed
273
+ part gives, and what a digest of the tree gives. When such a block differs at a later
274
+ judgement, the part is parsed once more for all that are left and its bytes go.
275
+
276
+ When the parsed part does not line up with *caches*, nothing is judged from then on.
277
+ """
278
+
279
+ def __init__(self, caches: list[Any], source_xml: bytes) -> None:
280
+ # by id(): the entries hold the elements, so lxml keeps their proxies and the ids stay theirs
281
+ self._watched: dict[int, _Watched] = {}
282
+ #: the caches watched as read, each with its place among the part's caches
283
+ self._as_read: dict[int, tuple[Any, int]] = {id(cache): (cache, place) for place, cache in enumerate(caches)}
284
+ self._as_read_count = len(caches)
285
+ self._source_xml: bytes | None = source_xml
286
+ self._blocks: dict[int, _Block] = {}
287
+ self._judged_once = False
288
+ self._judges = True
289
+ #: the part's caches parsed again, while a judgement needs them
290
+ self._originals: list[Any] | None = None
291
+
292
+ # -- the part as read ------------------------------------------------------------------------
293
+
294
+ def _stop(self) -> None:
295
+ self._judges = False
296
+ self._watched, self._as_read, self._blocks = {}, {}, {}
297
+ self._source_xml = self._originals = None
298
+
299
+ def _parse_part(self) -> list[tuple[Any, list[Any]]] | None:
300
+ """The part parsed again: each child of its root that holds caches, with them. ``None`` (and
301
+ nothing is judged any more) when it cannot be parsed or its caches do not line up."""
302
+
303
+ from ..opc.xml_utils import parse_xml
304
+
305
+ blocks: list[tuple[Any, list[Any]]] = []
306
+ source = self._source_xml
307
+ if source is None: # its bytes went with the last cache watched as read
308
+ self._stop()
309
+ return None
310
+ try:
311
+ for block in parse_xml(source):
312
+ caches = cache_elements(block)
313
+ if caches:
314
+ blocks.append((block, caches))
315
+ except Exception: # the part was read once already; without it nothing is judged
316
+ self._stop()
317
+ return None
318
+ originals = [cache for _block, caches in blocks for cache in caches]
319
+ if len(originals) != self._as_read_count:
320
+ self._stop()
321
+ return None
322
+ self._originals = originals
323
+ return blocks
324
+
325
+ def _part_blocks(self) -> dict[int, tuple[Any, list[Any]]] | None:
326
+ """The parsed part's blocks with their caches, by the place of the first cache in each. ``None``
327
+ when the part does not line up (nothing is judged)."""
328
+
329
+ parsed = self._parse_part()
330
+ if parsed is None:
331
+ return None
332
+ found: dict[int, tuple[Any, list[Any]]] = {}
333
+ place = 0
334
+ for block, caches in parsed:
335
+ found[place] = (block, caches)
336
+ place += len(caches)
337
+ return found
338
+
339
+ def _expected(self, cache: Any) -> tuple[bytes, bytes] | None:
340
+ """What *cache* is watched with: its paragraph's content digest and the cache's bytes."""
341
+
342
+ watched = _entry(self._watched, cache)
343
+ if watched is not None:
344
+ return watched[1], watched[2]
345
+ as_read = _entry(self._as_read, cache)
346
+ if as_read is None:
347
+ return None
348
+ if self._originals is None and self._parse_part() is None:
349
+ return None
350
+ assert self._originals is not None
351
+ return _as_it_is(self._originals[as_read[1]])[1:]
352
+
353
+ def _let_the_part_go(self, as_read: dict[int, tuple[Any, int]], watched: dict[int, _Watched]) -> None:
354
+ """After the part was parsed a second time: watch everything still *as_read* with what the part
355
+ holds for it (into *watched*), so that the part's bytes are not needed again."""
356
+
357
+ if self._originals is not None and self._judges:
358
+ for cache, place in as_read.values():
359
+ watched[id(cache)] = (cache, *_as_it_is(self._originals[place])[1:])
360
+ as_read.clear()
361
+ self._originals = None
362
+ if not as_read:
363
+ self._source_xml = None
364
+
365
+ # -- the rule --------------------------------------------------------------------------------
366
+
367
+ def _judge(self, caches: list[Any], watched: dict[int, _Watched], as_read: dict[int, tuple[Any, int]]) -> int:
368
+ """Drop each of *caches* whose paragraph no longer has the content it was watched with, and put
369
+ the others into *watched* with the content their paragraph has now (none of them stays in
370
+ *as_read*). Returns how many went."""
371
+
372
+ removed = 0
373
+ for cache in caches:
374
+ paragraph = cache.getparent()
375
+ digest = _content_digest(paragraph)
376
+ now = LET.tostring(cache, with_tail=False)
377
+ expected = self._expected(cache)
378
+ if not self._judges: # the part did not line up: nothing was to be judged
379
+ return 0
380
+ as_read.pop(id(cache), None)
381
+ if expected is not None and expected[0] != digest and expected[1] == now:
382
+ paragraph.remove(cache) # the content changed under the cache it was read with
383
+ watched.pop(id(cache), None)
384
+ removed += 1
385
+ else:
386
+ watched[id(cache)] = (cache, digest, now)
387
+ return removed
388
+
389
+ # -- judgements ------------------------------------------------------------------------------
390
+
391
+ def judge_all(self, root: Any, *, about_to_rebuild: Any = None) -> int:
392
+ """Drop from *root* each watched cache whose paragraph no longer has the content it came with.
393
+
394
+ Returns how many were dropped. What is watched from here on: every cache now in the tree,
395
+ with its paragraph's content as it is now. *about_to_rebuild* (a table whose rows and cells a
396
+ structure edit is about to build again) changes no answer: the caches of the block holding it
397
+ that are watched "as read" are watched with digests instead (of the tree, which in an unchanged
398
+ block is the part), so that the judgement after the edit, which finds that block changed, does
399
+ not have to parse the part for them.
400
+ """
401
+
402
+ if not self._judges:
403
+ return 0
404
+ first = not self._judged_once
405
+ as_read_blocks = self._part_blocks() if first else {}
406
+ if as_read_blocks is None:
407
+ return 0
408
+ self._judged_once = True
409
+ rebuilding = _block_of(root, about_to_rebuild) if about_to_rebuild is not None else None
410
+ removed = 0
411
+ watched: dict[int, _Watched] = {}
412
+ as_read: dict[int, tuple[Any, int]] = {}
413
+ blocks: dict[int, _Block] = {}
414
+ for block in root:
415
+ gone = self._judge_block(block, block is rebuilding, as_read_blocks, watched, as_read, blocks)
416
+ if gone is None:
417
+ return 0
418
+ removed += gone
419
+ if not first:
420
+ self._let_the_part_go(as_read, watched)
421
+ self._originals = None
422
+ if not as_read:
423
+ self._source_xml = None
424
+ self._watched, self._as_read, self._blocks = watched, as_read, blocks
425
+ return removed
426
+
427
+ def _judge_block(
428
+ self,
429
+ block: Any,
430
+ rebuilding: bool,
431
+ as_read_blocks: dict[int, tuple[Any, list[Any]]],
432
+ watched: dict[int, _Watched],
433
+ as_read: dict[int, tuple[Any, int]],
434
+ blocks: dict[int, _Block],
435
+ ) -> int | None:
436
+ """Judge the caches in *block* into *watched*, *as_read* and *blocks*. Returns how many went
437
+ (``None``: the part did not line up, and nothing is judged)."""
438
+
439
+ caches = cache_elements(block)
440
+ if not caches:
441
+ return 0
442
+ state = _block_state(block, caches, _whole_bytes(block))
443
+ was = _entry(self._blocks, block)
444
+ if _states_decide() and (
445
+ (
446
+ was is not None
447
+ and was[1] == state
448
+ and len(was[2]) == len(caches)
449
+ and all(held is cache for held, cache in zip(was[2], caches))
450
+ and all(
451
+ _entry(self._watched, cache) is not None or _entry(self._as_read, cache) is not None
452
+ for cache in caches
453
+ )
454
+ )
455
+ or (as_read_blocks and self._is_as_read(caches, state, as_read_blocks))
456
+ ):
457
+ # Nothing in the block changed since its caches were last judged (or read): the rule keeps
458
+ # each of them with the entry it has.
459
+ for cache in caches:
460
+ entry = _entry(self._watched, cache)
461
+ if entry is None:
462
+ unread = None if rebuilding else _entry(self._as_read, cache)
463
+ if unread is not None:
464
+ as_read[id(cache)] = unread
465
+ continue
466
+ entry = _as_it_is(cache) # as read, and the block is what it was read as
467
+ watched[id(cache)] = entry
468
+ blocks[id(block)] = (block, state, tuple(caches))
469
+ return 0
470
+ gone = self._judge(caches, watched, as_read)
471
+ if not self._judges:
472
+ return None
473
+ # With a cache gone the block is no longer in the state taken above, and the digests of the
474
+ # paragraphs around the cache were taken before it went (with the text after it, which went
475
+ # along): judge each again the next time, as a look at every cache would.
476
+ blocks[id(block)] = (block, None if gone else state, tuple(cache for cache in caches if id(cache) in watched))
477
+ return gone
478
+
479
+ def _is_as_read(
480
+ self, caches: list[Any], state: _State, as_read_blocks: dict[int, tuple[Any, list[Any]]]
481
+ ) -> bool:
482
+ """Whether a block of the tree (its *caches* and *state*) is one of the parsed part's blocks,
483
+ unchanged: the caches read in it, in their places, and the same state."""
484
+
485
+ places = []
486
+ for cache in caches:
487
+ found = _entry(self._as_read, cache)
488
+ if found is None:
489
+ return False
490
+ places.append(found[1])
491
+ source = as_read_blocks.get(places[0])
492
+ if source is None or places != list(range(places[0], places[0] + len(source[1]))):
493
+ return False
494
+ return _block_state(source[0], source[1], _whole_bytes(source[0])) == state