SF.net SVN: docutils:[9918] trunk/docutils/docutils

Revision: 9918
          http://sourceforge.net/p/docutils/code/9918
Author:   milde
Date:     2024-09-04 06:16:29 +0000 (Wed, 04 Sep 2024)
Log Message:
-----------
Fixes for `nodes.Node` and `_html_base.SimpleListChecker`

Ensure that all methods and attributes that are common to `nodes.Element`
and `nodes.Text` are also defined in the abstract base class `nodes.Node`.

Rename the node validation hook `check_position()` to `validate_position()`
to indicate its relation to element validation.

Define `_html_base.SimpleListChecker.default_departure`
(as required per documentation in `nodes.GenericNodeVisitor`).

Fixup for [r9901]

Modified Paths:
--------------
    trunk/docutils/docutils/nodes.py
    trunk/docutils/docutils/writers/_html_base.py

Modified: trunk/docutils/docutils/nodes.py
===================================================================
--- trunk/docutils/docutils/nodes.py	2024-09-03 09:35:59 UTC (rev 9917)
+++ trunk/docutils/docutils/nodes.py	2024-09-04 06:16:29 UTC (rev 9918)
@@ -71,7 +71,7 @@
 class Node:
     """Abstract base class of nodes in a document tree."""
 
-    parent: Node = None
+    parent: Element | None = None
     """Back-reference to the Node immediately containing this Node."""
 
     children: Sequence[Node] = ()
@@ -398,7 +398,16 @@
         Override in subclasses that define validity constraints.
         """
 
+    def validate_position(self) -> None:
+        """Hook for additional checks of the parent's content model.
 
+        Raise ValidationError, if `self` is at an invalid position.
+
+        Override in subclasses with complex validity constraints. See
+        `subtitle.validate_position()` and `transition.validate_position()`.
+        """
+
+
 class Text(Node, str):  # NoQA: SLOT000 (Node doesn't define __slots__)
     """
     Instances are terminal nodes (leaves) containing text only; no child
@@ -1120,10 +1129,7 @@
     def clear(self) -> None:
         self.children = []
 
-    def replace(self,
-                old: Node,
-                new: Node | Iterable[Node],
-                ) -> None:
+    def replace(self, old: Node, new: Node | Iterable[Node]) -> None:
         """Replace one child `Node` with another child or children."""
         index = self.index(old)
         if isinstance(new, Node):
@@ -1318,10 +1324,7 @@
                     continue  # try same child with next part of content model
             else:
                 # Check additional placement constraints (if applicable):
-                try:
-                    child.check_position()
-                except AttributeError:
-                    pass
+                child.validate_position()
             # advance:
             if quantifier in ('.', '?'):  # go to next element
                 child = next(ichildren, None)
@@ -1330,7 +1333,7 @@
                     if not isinstance(child, category):
                         break
                     try:
-                        child.check_position()
+                        child.validate_position()
                     except AttributeError:
                         pass
                 else:
@@ -1355,13 +1358,6 @@
         return (f'{msg}  Expecting child of type <{_type}>, '
                 f'not {child.starttag()}.')
 
-    def check_position(self) -> None:
-        """Hook for additional checks of the parent's content model.
-
-        Raise ValidationError, if `self` is at an invalid position.
-        See `subtitle.check_position()` and `transition.check_position()`.
-        """
-
     def validate(self, recursive: bool = True) -> None:
         """Validate Docutils Document Tree element ("doctree").
 
@@ -1601,7 +1597,7 @@
 class subtitle(Titular, PreBibliographic, SubStructural, TextElement):
     """Sub-title of `document`, `section` and `sidebar`."""
 
-    def check_position(self) -> None:
+    def validate_position(self) -> None:
         """Check position of subtitle: must follow a title."""
         if self.parent and self.parent.index(self) == 0:
             raise ValidationError(f'Element {self.parent.starttag()} invalid:'
@@ -1645,7 +1641,7 @@
     __ https://docutils.sourceforge.io/docs/ref/doctree.html#transition
     """
 
-    def check_position(self) -> None:
+    def validate_position(self) -> None:
         """Check additional constraints on `transition` placement.
 
         A transition may not begin or end a section or document,
@@ -1697,7 +1693,7 @@
                             ((topic, Body), '+'),
                             )
     # ((title, subtitle?)?, (%body.elements; | topic)+)
-    # "subtitle only after title" is ensured in `subtitle.check_position()`.
+    # "subtitle only after title" is ensured in `subtitle.validate_position()`.
 
 
 class section(Structural, Element):
@@ -1714,7 +1710,7 @@
                          ((section, transition), '*'),
                          )
 # (title, subtitle?, %structure.model;)
-# Correct transition placement is ensured in `transition.check_position()`.
+# Correct transition placement is ensured in `transition.validate_position()`.
 
 
 # Root Element
@@ -1743,7 +1739,7 @@
     #    (docinfo, transition?)?,
     #    %structure.model; )
     # Additional restrictions for `subtitle` and `transition` are tested
-    # with the respective `check_position()` methods.
+    # with the respective `validate_position()` methods.
 
     def __init__(self,
                  settings: Values,

Modified: trunk/docutils/docutils/writers/_html_base.py
===================================================================
--- trunk/docutils/docutils/writers/_html_base.py	2024-09-03 09:35:59 UTC (rev 9917)
+++ trunk/docutils/docutils/writers/_html_base.py	2024-09-04 06:16:29 UTC (rev 9918)
@@ -1831,6 +1831,9 @@
     def default_visit(self, node):
         raise nodes.NodeFound
 
+    def default_departure(self, node):
+        pass
+
     def visit_list_item(self, node):
         children = [child for child in node.children
                     if not isinstance(child, nodes.Invisible)]

This was sent by the SourceForge.net collaborative development platform, the world's largest Open Source development site.