Pre-cached iterator, lazy ElementList, O(1) sibling lookup

#1 Iterator pre-caching: ElementIterator pre-builds all (tag_idx,
   cached_tag) pairs in a single Document borrow at creation time.
   __next__ no longer borrows Document — just clone_ref on pre-cached
   values.

#2 Lazy ElementList: Element.xpath() and CompiledXPath.eval() now
   return ElementList — holds one Py<Document> + Vec<usize> of tag
   indices. Elements created on demand via __getitem__/__iter__.
   compiled.eval() for 100K results: 4ms -> 0.07ms (57x faster).
   Supports __len__, __getitem__, __iter__, __bool__, __eq__ (with
   list comparison).

#7 O(1) sibling lookup: child_positions[i] stored in IndexWithMeta
   at parse time. getnext/getprevious use direct index instead of
   linear scan over siblings. O(1) instead of O(siblings).

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

Author: cigrainger

python/simdxml/__init__.py

@@ -34,6 +34,7 @@
     CompiledXPath,
     Document,
     Element,
+    ElementList,
     compile,
     parse,
 )
@@ -42,6 +43,7 @@
     "CompiledXPath",
     "Document",
     "Element",
+    "ElementList",
     "compile",
     "parse",
 ]

python/simdxml/_core.pyi

@@ -94,10 +94,10 @@ class Element:
     def text_content(self) -> str:
         """All descendant text concatenated into a single string."""
         ...
-    def xpath(self, expr: str) -> list[Element]:
+    def xpath(self, expr: str) -> ElementList:
         """Evaluate an XPath 1.0 expression with this element as context.
 
-        Returns a list of matching Element objects.
+        Returns an ElementList of matching elements (lazy — created on access).
         """
         ...
     def xpath_text(self, expr: str) -> list[str]:
@@ -143,6 +143,18 @@ class Element:
     def __eq__(self, other: object) -> bool: ...
     def __hash__(self) -> int: ...
 
+class ElementList:
+    """A lazy sequence of elements from an XPath query.
+
+    Elements are created on demand when accessed by index or iteration.
+    Holds a single Document reference regardless of result size.
+    """
+
+    def __len__(self) -> int: ...
+    def __getitem__(self, index: int) -> Element: ...
+    def __iter__(self) -> Iterator[Element]: ...
+    def __bool__(self) -> bool: ...
+
 class CompiledXPath:
     """A compiled XPath expression for repeated use.
 
@@ -153,8 +165,8 @@ class CompiledXPath:
     def eval_text(self, doc: Document) -> list[str]:
         """Evaluate and return text content of matching nodes."""
         ...
-    def eval(self, doc: Document) -> list[Element]:
-        """Evaluate and return matching Element objects."""
+    def eval(self, doc: Document) -> ElementList:
+        """Evaluate and return matching elements as an ElementList (lazy)."""
         ...
     def eval_exists(self, doc: Document) -> bool:
         """Check whether any nodes match the expression."""

python/simdxml/etree/ElementTree.py

@@ -167,6 +167,6 @@ def _findall(
     """Find all matching subelements."""
     xpath = _path_to_xpath(path)
     try:
-        return element.xpath(xpath)
+        return list(element.xpath(xpath))
     except ValueError:
         return []