ElementTree read-only drop-in compatibility

Element now has find(), findall(), iterfind(), findtext() — the core
ElementTree query API. Path syntax (tag, .//tag, *, .., [@attrib],
[tag='text']) is translated to XPath and evaluated by the SIMD engine.

Also adds:
- extend(), makeelement() on Element (raise TypeError)
- iter() now includes self (matching stdlib behavior)
- itertext() now yields text/tail in correct stdlib order
- ET module: fromstringlist, tostringlist, dump, iselement
- ET module: SubElement, Comment, PI, indent (raise TypeError)
- ET module: register_namespace (no-op), ElementTree.write (TypeError)
- ET module: ElementTree.iter, findtext, iterfind

131 new tests (322 total):
- 49 ET compat tests (parse, ElementTree class, find/findall, read-only)
- 82 exhaustive drop-in tests cross-validating every operation against
  stdlib xml.etree.ElementTree on 7 corpus types
- Property tests (Hypothesis) for iter, itertext, find, len, text/tail
- Adversarial: empty docs, deep nesting, entities, mixed content, CDATA

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Author: cigrainger

pyproject.toml

@@ -43,7 +43,7 @@ target-version = "py39"
 
 [tool.ruff.lint]
 select = ["E", "F", "I", "N", "W", "UP", "RUF", "B", "SIM", "PTH"]
-ignore = ["N999"]  # ElementTree.py is a stdlib-compat module name
+ignore = ["N999", "N802"]  # ElementTree.py has stdlib-compat names
 
 [tool.ruff.lint.per-file-ignores]
 "tests/*" = ["N817", "PTH123"]  # ET alias, open() in test helpers

python/simdxml/_core.pyi

@@ -103,6 +103,33 @@ class Element:
     def xpath_text(self, expr: str) -> list[str]:
         """Evaluate an XPath expression and return text content of matches."""
         ...
+    def find(
+        self, path: str, namespaces: dict[str, str] | None = None
+    ) -> Element | None:
+        """Find first matching subelement by path (ElementTree API).
+
+        Supports: ``tag``, ``{ns}tag``, ``*/tag``, ``.//tag``, ``..``,
+        ``[@attrib]``, ``[tag]``, ``[tag='text']``.
+        """
+        ...
+    def findall(
+        self, path: str, namespaces: dict[str, str] | None = None
+    ) -> ElementList:
+        """Find all matching subelements by path (ElementTree API)."""
+        ...
+    def iterfind(
+        self, path: str, namespaces: dict[str, str] | None = None
+    ) -> Iterator[Element]:
+        """Iterate over matching subelements by path (ElementTree API)."""
+        ...
+    def findtext(
+        self,
+        path: str,
+        default: str | None = None,
+        namespaces: dict[str, str] | None = None,
+    ) -> str | None:
+        """Find text of first matching subelement (ElementTree API)."""
+        ...
     def getparent(self) -> Element | None:
         """Parent element, or None if this is the root."""
         ...

python/simdxml/etree/ElementTree.py

@@ -1,7 +1,7 @@
 """Drop-in replacement for xml.etree.ElementTree (read-only).
 
-Provides the same API as xml.etree.ElementTree for parsing and querying XML,
-backed by simdxml's SIMD-accelerated structural index.
+Provides the same read-only API as xml.etree.ElementTree for parsing and
+querying XML, backed by simdxml's SIMD-accelerated structural index.
 
 Usage::
 
@@ -12,26 +12,25 @@
     titles = root.findall(".//title")
 
 Note: simdxml Elements are read-only. Mutation operations (append, remove,
-set, text assignment) raise TypeError.
+set, text assignment, SubElement, etc.) raise TypeError.
 """
 
 from __future__ import annotations
 
 import os
+import sys
 from collections.abc import Iterator
 from typing import IO
 
 import simdxml._core as _core
 
-# Re-export Element and Document
+# Re-export Element for isinstance checks and type annotations
 Element = _core.Element
+ElementList = _core.ElementList
 
 
 class ElementTree:
-    """An XML element hierarchy backed by simdxml.
-
-    This is a read-only wrapper matching the stdlib ElementTree API.
-    """
+    """An XML element hierarchy backed by simdxml (read-only)."""
 
     def __init__(
         self,
@@ -40,7 +39,6 @@ def __init__(
     ) -> None:
         if file is not None:
             if not isinstance(file, (str, os.PathLike)):
-                # File-like object
                 data: bytes = file.read()
             else:
                 from pathlib import Path
@@ -59,33 +57,53 @@ def __init__(
     def getroot(self) -> Element:
         """Return the root element."""
         if self._root is None:
-            raise ValueError("ElementTree has no root element")
+            msg = "ElementTree has no root element"
+            raise ValueError(msg)
         return self._root
 
     def find(
         self, path: str, namespaces: dict[str, str] | None = None
     ) -> Element | None:
         """Find first matching element by path."""
-        root = self.getroot()
-        return _find(root, path, namespaces)
+        return self.getroot().find(path, namespaces)
 
     def findall(
         self, path: str, namespaces: dict[str, str] | None = None
-    ) -> list[Element]:
+    ) -> ElementList:
         """Find all matching elements by path."""
-        root = self.getroot()
-        return _findall(root, path, namespaces)
+        return self.getroot().findall(path, namespaces)
+
+    def findtext(
+        self,
+        path: str,
+        default: str | None = None,
+        namespaces: dict[str, str] | None = None,
+    ) -> str | None:
+        """Find text of first matching element."""
+        return self.getroot().findtext(path, default, namespaces)
 
     def iterfind(
         self, path: str, namespaces: dict[str, str] | None = None
     ) -> Iterator[Element]:
         """Iterate over matching elements."""
-        return iter(self.findall(path, namespaces))
+        return self.getroot().iterfind(path, namespaces)
+
+    def iter(self, tag: str | None = None) -> Iterator[Element]:
+        """Iterate over all elements in the tree."""
+        return self.getroot().iter(tag)
+
+    def write(self, *_args: object, **_kwargs: object) -> None:
+        """Not supported (read-only)."""
+        msg = "simdxml ElementTree is read-only"
+        raise TypeError(msg)
+
+
+# ---------------------------------------------------------------------------
+# Module-level functions matching xml.etree.ElementTree
+# ---------------------------------------------------------------------------
 
 
-def parse(
-    source: str | os.PathLike[str] | IO[bytes],
-) -> ElementTree:
+def parse(source: str | os.PathLike[str] | IO[bytes]) -> ElementTree:
     """Parse an XML file into an ElementTree."""
     return ElementTree(file=source)
 
@@ -95,14 +113,24 @@ def fromstring(text: str | bytes) -> Element:
     doc = _core.parse(text)
     root = doc.root
     if root is None:
-        raise ValueError("no root element found")
+        msg = "no root element found"
+        raise ValueError(msg)
     return root
 
 
+def fromstringlist(sequence: list[str | bytes], parser: object = None) -> Element:
+    """Parse XML from a sequence of strings."""
+    text = b"".join(s.encode() if isinstance(s, str) else s for s in sequence)
+    return fromstring(text)
+
+
 def tostring(
     element: Element,
     encoding: str | None = None,
     method: str | None = None,
+    *,
+    short_empty_elements: bool = True,
+    xml_declaration: bool | None = None,
 ) -> bytes | str:
     """Serialize an Element to XML.
 
@@ -115,58 +143,72 @@ def tostring(
     return raw.encode(enc)
 
 
+def tostringlist(
+    element: Element,
+    encoding: str | None = None,
+    method: str | None = None,
+    *,
+    short_empty_elements: bool = True,
+    xml_declaration: bool | None = None,
+) -> list[bytes | str]:
+    """Serialize an Element to a list of strings."""
+    return [tostring(element, encoding, method)]
+
+
+def dump(elem: Element) -> None:
+    """Write element tree or element to sys.stdout."""
+    sys.stdout.write(elem.tostring())
+    sys.stdout.write("\n")
+
+
+def iselement(element: object) -> bool:
+    """Check if an object is an Element."""
+    return isinstance(element, _core.Element)
+
+
 # ---------------------------------------------------------------------------
-# ET path → XPath translation for find/findall
+# Read-only stubs for write/construction APIs
 # ---------------------------------------------------------------------------
 
+_READONLY_MSG = "simdxml is read-only. Use xml.etree.ElementTree for XML construction."
 
-def _path_to_xpath(path: str) -> str:
-    """Convert ET path syntax to XPath.
 
-    ET paths are a subset of XPath with some differences:
-    - {ns}tag → namespace handling (we pass through as-is for now)
-    - .  → self
-    - .. → parent
-    - // → descendant-or-self
-    - * → wildcard
-    - [tag] → child element predicate
-    - [@attrib] → attribute exists
-    - [tag='text'] → child text match
-    - [@attrib='value'] → attribute value match
-    """
-    # If it already looks like XPath, pass through
-    if path.startswith("/") or path.startswith("("):
-        return path
+def SubElement(
+    parent: Element,
+    tag: str,
+    attrib: dict[str, str] | None = None,
+    **extra: str,
+) -> Element:
+    """Not supported (read-only). Raises TypeError."""
+    raise TypeError(_READONLY_MSG)
 
-    # Ensure relative paths start with ./ for XPath context
-    if not path.startswith("."):
-        path = "./" + path
 
-    return path
+def Comment(text: str | None = None) -> Element:
+    """Not supported (read-only). Raises TypeError."""
+    raise TypeError(_READONLY_MSG)
 
 
-def _find(
-    element: Element,
-    path: str,
-    namespaces: dict[str, str] | None = None,
-) -> Element | None:
-    """Find first matching subelement."""
-    xpath = _path_to_xpath(path)
-    try:
-        results = element.xpath(xpath)
-        return results[0] if results else None
-    except ValueError:
-        return None
-
-
-def _findall(
-    element: Element,
-    path: str,
-    namespaces: dict[str, str] | None = None,
-) -> list[Element]:
-    """Find all matching subelements."""
-    xpath = _path_to_xpath(path)
-    try:
-        return list(element.xpath(xpath))
-    except ValueError:
-        return []
+def ProcessingInstruction(target: str, text: str | None = None) -> Element:
+    """Not supported (read-only). Raises TypeError."""
+    raise TypeError(_READONLY_MSG)
+
+
+PI = ProcessingInstruction
+
+
+def indent(
+    tree: Element | ElementTree,
+    space: str = "  ",
+    level: int = 0,
+) -> None:
+    """Not supported (read-only, modifies tree). Raises TypeError."""
+    raise TypeError(_READONLY_MSG)
+
+
+# Namespace registry (no-op for compatibility)
+_namespace_map: dict[str, str] = {}
+
+
+def register_namespace(prefix: str, uri: str) -> None:
+    """Register a namespace prefix (stored but not used for queries)."""
+    _namespace_map[prefix] = uri