Coverage for /pythoncovmergedfiles/medio/medio/usr/local/lib/python3.11/site-packages/turbohtml/mutations.py: 100%

1""" 

2Synchronous DOM mutation observation. 

3 

4:class:`MutationObserver` watches a node for tree changes and records them the way the DOM 

5`MutationObserver <https://dom.spec.whatwg.org/#mutationobserver>`_ does. The DOM delivers records 

6on a microtask, so a callback never runs mid-edit; turbohtml has no event loop, so it keeps the same 

7record shape but delivers synchronously -- pull the batch with :meth:`~MutationObserver.take_records`, or 

8push it to the callback with :meth:`~MutationObserver.deliver`. Records still queue at mutation time and 

9reach Python only at a drain, so a callback never fires while the tree is half-linked. 

10 

11The observation engine lives in the C core (``turbohtml._html``); importing this module registers the 

12:class:`MutationRecord` type it builds each change into. 

13""" 

14 

15from __future__ import annotations 

16 

17from typing import NamedTuple 

18 

19from ._html import MutationObserver as MutationObserver # ruff:ignore[useless-import-alias] # re-export the C type 

20from ._html import Node, _register_mutation_record 

21 

22 

23class MutationRecord(NamedTuple): 

24 """One change delivered to an observer, mirroring the DOM MutationRecord.""" 

25 

26 type: str 

27 """``"childList"``, ``"attributes"``, or ``"characterData"``.""" 

28 target: Node 

29 """the node the change applies to: the parent for a childList change, else the changed node.""" 

30 added_nodes: tuple[Node, ...] 

31 """the nodes added, for a childList change (else empty).""" 

32 removed_nodes: tuple[Node, ...] 

33 """the nodes removed, for a childList change (else empty).""" 

34 previous_sibling: Node | None 

35 """the sibling before the added or removed nodes, or ``None``.""" 

36 next_sibling: Node | None 

37 """the sibling after the added or removed nodes, or ``None``.""" 

38 attribute_name: str | None 

39 """the changed attribute's name, for an attributes change (else ``None``).""" 

40 old_value: str | None 

41 """the previous value, when the registration asked for it (else ``None``).""" 

42 

43 

44_register_mutation_record(MutationRecord) 

45 

46__all__ = [ 

47 "MutationObserver", 

48 "MutationRecord", 

49]