leptris 1.2.0__tar.gz

leptris-1.2.0/PKG-INFO

@@ -0,0 +1,95 @@
+Metadata-Version: 2.4
+Name: leptris
+Version: 1.2.0
+Summary: Python bindings for libleptris — fast XML 1.0 parsing and XPath 1.0
+Author: Ribose
+License: MIT
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+Requires-Dist: cffi
+Provides-Extra: test
+Requires-Dist: pytest; extra == "test"
+
+# leptris (Python) — bindings for libleptris
+
+`leptris` wraps the [libleptris](https://github.com/leptris/leptris)
+C API (XML 1.0 parsing, XPath 1.0) using `cffi` in ABI mode — the
+`cdef` in `leptris/_ffi.py` mirrors libleptris's public headers.
+
+The pinned libleptris version lives in `libleptris-version.txt`
+(lockstep releases); CI builds it from the release tarball. The
+binding loads the shared library from `LEPTRIS_LIB_PATH` or the
+loader path.
+
+## Requirements
+
+- Python 3.8+
+- `cffi` (`pip install cffi`)
+- libleptris as a shared library (`libleptris.dylib` / `libleptris.so`)
+  on the loader path, or pointed to by `LEPTRIS_LIB_PATH`. For a
+  development checkout:
+
+```bash
+cmake -B build -S . -DLEPTRIS_BUILD_SHARED=ON
+cmake --build build --target leptris_shared
+export LEPTRIS_LIB_PATH=$PWD/build/src/libleptris.dylib
+```
+
+## Quick start
+
+```python
+from leptris import Document
+
+doc = Document.parse("<library><book id='1'>Ulysses</book></library>")
+
+doc.root.name                     # "library"
+book = doc.root.first_child_element
+book.name                         # "book"
+book.attribute("id")              # "1"
+book.text                         # "Ulysses"
+
+doc.xpath("count(//book)")        # 1.0
+[e.text for e in doc.xpath("//book")]   # ["Ulysses"]
+
+doc.close()   # or: with Document.parse(xml) as doc: ...
+```
+
+## Layout
+
+- `leptris/_ffi.py` — cdef + shared-library loading (single source
+  of the C surface, mirroring the Ruby binding's `lib/leptris.rb`)
+- `leptris/document.py`, `element.py`, `node.py`, `xpath.py`,
+  `error.py` — typed wrappers
+- `tests/` — pytest suite (run: `pytest` with `LEPTRIS_LIB_PATH` set)
+
+## Memory model
+
+The `Document` owns the whole tree and its pool. Accessor strings
+are copied into Python `str` at the boundary, so nothing depends on
+document lifetime after a call returns. Elements keep a reference to
+their `Document`, so the pool cannot be freed while any wrapper is
+alive. Prefer explicit `close()` / the context manager; `__del__` is
+a refcounting safety net, not a contract.
+
+## Versioning
+
+The package version tracks libleptris (lockstep): library 1.1.0 ↔
+leptris 1.1.0.
+
+## Publishing
+
+Releases publish to PyPI via `.github/workflows/release.yml`,
+using PyPI **trusted publishing** (no stored credentials). The
+workflow runs on manual dispatch (ships the version in
+`pyproject.toml`) and is called by the libleptris release flow
+(`publish: true`), so every libleptris release ships the wheel.
+
+## Local development
+
+```bash
+python3 -m venv .venv
+./.venv/bin/pip install --upgrade build setuptools wheel pytest cffi
+./.venv/bin/python -m build
+LEPTRIS_LIB_PATH=../../build-shared/src/libleptris.dylib \
+  ./.venv/bin/python -m pytest tests/ -q
+```

leptris-1.2.0/README.md

@@ -0,0 +1,83 @@
+# leptris (Python) — bindings for libleptris
+
+`leptris` wraps the [libleptris](https://github.com/leptris/leptris)
+C API (XML 1.0 parsing, XPath 1.0) using `cffi` in ABI mode — the
+`cdef` in `leptris/_ffi.py` mirrors libleptris's public headers.
+
+The pinned libleptris version lives in `libleptris-version.txt`
+(lockstep releases); CI builds it from the release tarball. The
+binding loads the shared library from `LEPTRIS_LIB_PATH` or the
+loader path.
+
+## Requirements
+
+- Python 3.8+
+- `cffi` (`pip install cffi`)
+- libleptris as a shared library (`libleptris.dylib` / `libleptris.so`)
+  on the loader path, or pointed to by `LEPTRIS_LIB_PATH`. For a
+  development checkout:
+
+```bash
+cmake -B build -S . -DLEPTRIS_BUILD_SHARED=ON
+cmake --build build --target leptris_shared
+export LEPTRIS_LIB_PATH=$PWD/build/src/libleptris.dylib
+```
+
+## Quick start
+
+```python
+from leptris import Document
+
+doc = Document.parse("<library><book id='1'>Ulysses</book></library>")
+
+doc.root.name                     # "library"
+book = doc.root.first_child_element
+book.name                         # "book"
+book.attribute("id")              # "1"
+book.text                         # "Ulysses"
+
+doc.xpath("count(//book)")        # 1.0
+[e.text for e in doc.xpath("//book")]   # ["Ulysses"]
+
+doc.close()   # or: with Document.parse(xml) as doc: ...
+```
+
+## Layout
+
+- `leptris/_ffi.py` — cdef + shared-library loading (single source
+  of the C surface, mirroring the Ruby binding's `lib/leptris.rb`)
+- `leptris/document.py`, `element.py`, `node.py`, `xpath.py`,
+  `error.py` — typed wrappers
+- `tests/` — pytest suite (run: `pytest` with `LEPTRIS_LIB_PATH` set)
+
+## Memory model
+
+The `Document` owns the whole tree and its pool. Accessor strings
+are copied into Python `str` at the boundary, so nothing depends on
+document lifetime after a call returns. Elements keep a reference to
+their `Document`, so the pool cannot be freed while any wrapper is
+alive. Prefer explicit `close()` / the context manager; `__del__` is
+a refcounting safety net, not a contract.
+
+## Versioning
+
+The package version tracks libleptris (lockstep): library 1.1.0 ↔
+leptris 1.1.0.
+
+## Publishing
+
+Releases publish to PyPI via `.github/workflows/release.yml`,
+using PyPI **trusted publishing** (no stored credentials). The
+workflow runs on manual dispatch (ships the version in
+`pyproject.toml`) and is called by the libleptris release flow
+(`publish: true`), so every libleptris release ships the wheel.
+
+## Local development
+
+```bash
+python3 -m venv .venv
+./.venv/bin/pip install --upgrade build setuptools wheel pytest cffi
+./.venv/bin/python -m build
+LEPTRIS_LIB_PATH=../../build-shared/src/libleptris.dylib \
+  ./.venv/bin/python -m pytest tests/ -q
+```

leptris-1.2.0/leptris/__init__.py

@@ -0,0 +1,21 @@
+"""leptris — Python bindings for libleptris.
+
+Usage:
+
+    from leptris import Document
+
+    doc = Document.parse("<root><item>hi</item></root>")
+    print(doc.root.name)
+
+Requires libleptris on the library search path (or LEPTRIS_LIB_PATH).
+"""
+
+__version__ = "1.2.0"
+
+from .document import Document
+from .element import Element
+from .error import LeptrisError
+from .node import Node
+from .xpath import XPath
+
+__all__ = ["Document", "Element", "Node", "XPath", "LeptrisError"]

leptris-1.2.0/leptris/_ffi.py

@@ -0,0 +1,109 @@
+"""C bridge for leptris.
+
+cffi ABI mode: the cdef below mirrors the public headers
+(src/include/leptris/). All handles are opaque pointers; strings
+returned by accessors are document-owned and only valid until
+leptris_document_free — copy into Python str at the boundary.
+
+The library is resolved from LEPTRIS_LIB_PATH, then the usual
+install names, then the local build directory.
+"""
+
+import os
+
+from cffi import FFI
+
+ffi = FFI()
+
+ffi.cdef(
+    """
+    typedef struct leptris_document* LeptrisDocument;
+    typedef struct leptris_element*  LeptrisElement;
+    typedef struct leptris_node*     LeptrisNodeRef;
+    typedef struct leptris_attribute* LeptrisAttribute;
+    typedef struct leptris_xpath_result* LeptrisXPathResult;
+
+    LeptrisDocument leptris_parse_string(const char* xml, size_t len, int* status);
+    void           leptris_document_free(LeptrisDocument doc);
+    LeptrisElement  leptris_document_root(LeptrisDocument doc);
+    char*          leptris_document_serialize(LeptrisDocument doc, void* options);
+    int            leptris_xinclude_process(LeptrisDocument doc, const char* base_path);
+
+    int    leptris_node_get_type(LeptrisNodeRef node);
+    LeptrisNodeRef leptris_node_first_child(LeptrisNodeRef node);
+    LeptrisNodeRef leptris_node_next_sibling(LeptrisNodeRef node);
+    LeptrisNodeRef leptris_node_previous_sibling(LeptrisNodeRef node);
+    size_t leptris_node_child_count(LeptrisNodeRef node);
+    LeptrisElement  leptris_node_as_element(LeptrisNodeRef node);
+    LeptrisNodeRef  leptris_element_as_node(LeptrisElement elem);
+
+    const char* leptris_element_name(LeptrisElement elem);
+    const char* leptris_element_text(LeptrisElement elem);
+    LeptrisElement leptris_element_first_child_any(LeptrisElement elem);
+    LeptrisElement leptris_element_parent(LeptrisElement elem);
+    const char* leptris_element_attribute(LeptrisElement elem,
+                                         const char* name);
+    LeptrisElement leptris_element_next_sibling_any(LeptrisElement elem);
+    LeptrisAttribute leptris_element_first_attribute(LeptrisElement elem);
+    LeptrisAttribute leptris_attribute_next(LeptrisAttribute attr);
+    const char* leptris_attribute_get_name(LeptrisAttribute attr);
+    const char* leptris_attribute_get_value(LeptrisElement elem,
+                                            LeptrisAttribute attr);
+    size_t leptris_element_attribute_count(LeptrisElement elem);
+    size_t leptris_element_child_count(LeptrisElement elem);
+
+    const char* leptris_text_node_get_content(LeptrisNodeRef node);
+    const char* leptris_comment_node_get_content(LeptrisNodeRef node);
+    const char* leptris_cdata_node_get_content(LeptrisNodeRef node);
+    const char* leptris_pi_node_get_target(LeptrisNodeRef node);
+    const char* leptris_pi_node_get_data(LeptrisNodeRef node);
+
+    LeptrisXPathResult leptris_xpath_eval(LeptrisDocument doc,
+                                        LeptrisElement context,
+                                        const char* expression);
+    void     leptris_xpath_result_free(LeptrisXPathResult result);
+    int      leptris_xpath_result_type(LeptrisXPathResult result);
+    double   leptris_xpath_result_number(LeptrisXPathResult result);
+    int      leptris_xpath_result_boolean(LeptrisXPathResult result);
+    char*    leptris_xpath_result_string(LeptrisXPathResult result);
+    size_t   leptris_xpath_result_count(LeptrisXPathResult result);
+    LeptrisElement leptris_xpath_result_get(LeptrisXPathResult result, size_t index);
+
+    void leptris_free_string(char* str);
+    """
+)
+
+
+def _load():
+    candidates = []
+    if os.environ.get("LEPTRIS_LIB_PATH"):
+        candidates.append(os.environ["LEPTRIS_LIB_PATH"])
+    candidates += ["libleptris.dylib", "libleptris.so", "leptris.dll"]
+    here = os.path.dirname(__file__)
+    candidates += [
+        os.path.join(here, "..", "..", "..", "build", "src", "libleptris.dylib"),
+        os.path.join(here, "..", "..", "..", "build", "src", "libleptris.so"),
+    ]
+    for name in candidates:
+        try:
+            return ffi.dlopen(name)
+        except OSError:
+            continue
+    raise ImportError(
+        "libleptris not found; build it or set LEPTRIS_LIB_PATH"
+    )
+
+
+lib = _load()
+
+NODE_ELEMENT = 0
+NODE_TEXT = 1
+NODE_COMMENT = 2
+NODE_CDATA = 3
+NODE_PI = 4
+NODE_DOCTYPE = 5
+
+XPATH_NODESET = 0
+XPATH_BOOLEAN = 1
+XPATH_NUMBER = 2
+XPATH_STRING = 3

leptris-1.2.0/leptris/document.py

@@ -0,0 +1,79 @@
+"""Document — wraps LeptrisDocument.
+
+The document owns the entire DOM tree and memory pool. Release it
+with close() (or the context manager); __del__ is a last-resort
+safety net for CPython refcounting, not a contract.
+"""
+
+from . import _ffi
+from .error import LeptrisError
+
+
+class Document:
+    def __init__(self, _ptr):
+        self._ptr = _ptr
+        self._freed = False
+
+    @classmethod
+    def parse(cls, xml):
+        if isinstance(xml, str):
+            xml = xml.encode("utf-8")
+        if not isinstance(xml, (bytes, bytearray, memoryview)):
+            raise TypeError("xml must be str or bytes")
+        xml = bytes(xml)
+        status = _ffi.ffi.new("int*")
+        ptr = _ffi.lib.leptris_parse_string(xml, len(xml), status)
+        if ptr == _ffi.ffi.NULL:
+            raise LeptrisError(f"parse failed (status={status[0]})")
+        return cls(ptr)
+
+    @property
+    def root(self):
+        ptr = _ffi.lib.leptris_document_root(self._ptr)
+        if ptr == _ffi.ffi.NULL:
+            return None
+        from .element import Element
+
+        return Element(ptr, self)
+
+    def serialize(self) -> str:
+        result = _ffi.lib.leptris_document_serialize(self._ptr, _ffi.ffi.NULL)
+        if result == _ffi.ffi.NULL:
+            return ""
+        value = _ffi.ffi.string(result).decode("utf-8")
+        _ffi.lib.leptris_free_string(result)
+        return value
+
+    def process_xinclude(self, base_url=None):
+        base = base_url.encode("utf-8") if base_url is not None else _ffi.ffi.NULL
+        rc = _ffi.lib.leptris_xinclude_process(self._ptr, base)
+        if rc != 0:
+            raise LeptrisError("XInclude processing failed")
+        return self
+
+    def xpath(self, expression, context=None):
+        from .xpath import XPath
+
+        return XPath.evaluate(self, context, expression)
+
+    def close(self):
+        if not self._freed:
+            _ffi.lib.leptris_document_free(self._ptr)
+            self._freed = True
+            self._ptr = _ffi.ffi.NULL
+
+    @property
+    def closed(self) -> bool:
+        return self._freed
+
+    def __enter__(self):
+        return self
+
+    def __exit__(self, exc_type, exc_val, exc_tb):
+        self.close()
+
+    def __del__(self):
+        try:
+            self.close()
+        except Exception:
+            pass

leptris-1.2.0/leptris/element.py

@@ -0,0 +1,109 @@
+"""Element — wraps LeptrisElement.
+
+Elements are owned by their parent Document; they are never freed
+directly. Element objects keep a reference to the Document so the
+tree cannot outlive its pool.
+"""
+
+from . import _ffi
+
+
+class Element:
+    def __init__(self, _ptr, document):
+        self._ptr = _ptr
+        self._document = document
+
+    @property
+    def document(self):
+        return self._document
+
+    @property
+    def name(self) -> str:
+        value = _ffi.lib.leptris_element_name(self._ptr)
+        return _ffi.ffi.string(value).decode("utf-8") if value != _ffi.ffi.NULL else ""
+
+    @property
+    def text(self) -> str:
+        value = _ffi.lib.leptris_element_text(self._ptr)
+        return _ffi.ffi.string(value).decode("utf-8") if value != _ffi.ffi.NULL else ""
+
+    def attribute(self, name: str, default=None):
+        value = _ffi.lib.leptris_element_attribute(
+            self._ptr, name.encode("utf-8")
+        )
+        if value == _ffi.ffi.NULL:
+            return default
+        return _ffi.ffi.string(value).decode("utf-8")
+
+    __getitem__ = attribute
+
+    def attributes(self):
+        """Yield (name, value) for every attribute in document order.
+
+        Handle-based iteration — O(n) total where index-based access
+        re-walks the list per call.
+        """
+        attr = _ffi.lib.leptris_element_first_attribute(self._ptr)
+        while attr != _ffi.ffi.NULL:
+            name = _ffi.ffi.string(
+                _ffi.lib.leptris_attribute_get_name(attr)
+            ).decode("utf-8")
+            value = _ffi.ffi.string(
+                _ffi.lib.leptris_attribute_get_value(self._ptr, attr)
+            ).decode("utf-8")
+            yield (name, value)
+            attr = _ffi.lib.leptris_attribute_next(attr)
+
+    @property
+    def attribute_count(self) -> int:
+        return _ffi.lib.leptris_element_attribute_count(self._ptr)
+
+    @property
+    def child_count(self) -> int:
+        return _ffi.lib.leptris_element_child_count(self._ptr)
+
+    @property
+    def parent(self):
+        ptr = _ffi.lib.leptris_element_parent(self._ptr)
+        if ptr == _ffi.ffi.NULL:
+            return None
+        return Element(ptr, self._document)
+
+    @property
+    def first_child_element(self):
+        ptr = _ffi.lib.leptris_element_first_child_any(self._ptr)
+        if ptr == _ffi.ffi.NULL:
+            return None
+        return Element(ptr, self._document)
+
+    @property
+    def next_sibling_element(self):
+        # The node-level sibling chain interleaves text nodes, so
+        # walk until the next element (or the end of the chain).
+        node = _ffi.lib.leptris_node_next_sibling(_ffi.lib.leptris_element_as_node(self._ptr))
+        while node != _ffi.ffi.NULL:
+            elem = _ffi.lib.leptris_node_as_element(node)
+            if elem != _ffi.ffi.NULL:
+                return Element(elem, self._document)
+            node = _ffi.lib.leptris_node_next_sibling(node)
+        return None
+
+    def child_elements(self):
+        child = self.first_child_element
+        while child is not None:
+            yield child
+            child = child.next_sibling_element
+
+    def to_node(self):
+        from .node import Node
+
+        return Node(_ffi.lib.leptris_element_as_node(self._ptr), self._document)
+
+    def xpath(self, expression):
+        return self._document.xpath(expression, context=self)
+
+    def __iter__(self):
+        return self.child_elements()
+
+    def __repr__(self):
+        return f"<leptris.Element {self.name!r}>"

leptris-1.2.0/leptris/error.py

@@ -0,0 +1,5 @@
+"""Error type for leptris."""
+
+
+class LeptrisError(Exception):
+    """Raised when a libleptris call fails (parse, XPath, XInclude)."""

leptris-1.2.0/leptris/node.py

@@ -0,0 +1,84 @@
+"""Node — wraps LeptrisNodeRef for generic tree traversal.
+
+Covers every node type (element, text, comment, CDATA, PI, doctype);
+Element is the typed view for element nodes.
+"""
+
+from . import _ffi
+
+
+class Node:
+    def __init__(self, _ptr, document):
+        self._ptr = _ptr
+        self._document = document
+
+    @property
+    def type(self) -> int:
+        return _ffi.lib.leptris_node_get_type(self._ptr)
+
+    def is_element(self) -> bool:
+        return self.type == _ffi.NODE_ELEMENT
+
+    def is_text(self) -> bool:
+        return self.type == _ffi.NODE_TEXT
+
+    def is_comment(self) -> bool:
+        return self.type == _ffi.NODE_COMMENT
+
+    def is_cdata(self) -> bool:
+        return self.type == _ffi.NODE_CDATA
+
+    def is_pi(self) -> bool:
+        return self.type == _ffi.NODE_PI
+
+    @property
+    def content(self):
+        t = self.type
+        if t == _ffi.NODE_TEXT:
+            getter = _ffi.lib.leptris_text_node_get_content
+        elif t == _ffi.NODE_COMMENT:
+            getter = _ffi.lib.leptris_comment_node_get_content
+        elif t == _ffi.NODE_CDATA:
+            getter = _ffi.lib.leptris_cdata_node_get_content
+        else:
+            return None
+        value = getter(self._ptr)
+        return _ffi.ffi.string(value).decode("utf-8") if value != _ffi.ffi.NULL else ""
+
+    @property
+    def first_child(self):
+        ptr = _ffi.lib.leptris_node_first_child(self._ptr)
+        if ptr == _ffi.ffi.NULL:
+            return None
+        return Node(ptr, self._document)
+
+    @property
+    def next_sibling(self):
+        ptr = _ffi.lib.leptris_node_next_sibling(self._ptr)
+        if ptr == _ffi.ffi.NULL:
+            return None
+        return Node(ptr, self._document)
+
+    @property
+    def previous_sibling(self):
+        ptr = _ffi.lib.leptris_node_previous_sibling(self._ptr)
+        if ptr == _ffi.ffi.NULL:
+            return None
+        return Node(ptr, self._document)
+
+    @property
+    def child_count(self) -> int:
+        return _ffi.lib.leptris_node_child_count(self._ptr)
+
+    def as_element(self):
+        if not self.is_element():
+            return None
+        ptr = _ffi.lib.leptris_node_as_element(self._ptr)
+        if ptr == _ffi.ffi.NULL:
+            return None
+        from .element import Element
+
+        return Element(ptr, self._document)
+
+    def __repr__(self):
+        return f"<leptris.Node type={self.type}>"

leptris-1.2.0/leptris/xpath.py

@@ -0,0 +1,42 @@
+"""XPath — evaluates XPath 1.0 expressions.
+
+Results are typed: nodeset results yield Element lists; scalar
+results convert to native Python types.
+"""
+
+from . import _ffi
+from .error import LeptrisError
+
+
+class XPath:
+    @staticmethod
+    def evaluate(document, context_element, expression):
+        ctx = context_element._ptr if context_element is not None else _ffi.ffi.NULL
+        result = _ffi.lib.leptris_xpath_eval(document._ptr, ctx, expression.encode("utf-8"))
+        if result == _ffi.ffi.NULL:
+            raise LeptrisError(f"XPath evaluation failed: {expression!r}")
+
+        try:
+            result_type = _ffi.lib.leptris_xpath_result_type(result)
+            if result_type == _ffi.XPATH_NODESET:
+                count = _ffi.lib.leptris_xpath_result_count(result)
+                from .element import Element
+
+                return [
+                    Element(_ffi.lib.leptris_xpath_result_get(result, i), document)
+                    for i in range(count)
+                ]
+            if result_type == _ffi.XPATH_NUMBER:
+                return _ffi.lib.leptris_xpath_result_number(result)
+            if result_type == _ffi.XPATH_STRING:
+                ptr = _ffi.lib.leptris_xpath_result_string(result)
+                if ptr == _ffi.ffi.NULL:
+                    return ""
+                value = _ffi.ffi.string(ptr).decode("utf-8")
+                _ffi.lib.leptris_free_string(ptr)
+                return value
+            if result_type == _ffi.XPATH_BOOLEAN:
+                return bool(_ffi.lib.leptris_xpath_result_boolean(result))
+            return None
+        finally:
+            _ffi.lib.leptris_xpath_result_free(result)

leptris-1.2.0/leptris.egg-info/PKG-INFO

@@ -0,0 +1,95 @@
+Metadata-Version: 2.4
+Name: leptris
+Version: 1.2.0
+Summary: Python bindings for libleptris — fast XML 1.0 parsing and XPath 1.0
+Author: Ribose
+License: MIT
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+Requires-Dist: cffi
+Provides-Extra: test
+Requires-Dist: pytest; extra == "test"
+
+# leptris (Python) — bindings for libleptris
+
+`leptris` wraps the [libleptris](https://github.com/leptris/leptris)
+C API (XML 1.0 parsing, XPath 1.0) using `cffi` in ABI mode — the
+`cdef` in `leptris/_ffi.py` mirrors libleptris's public headers.
+
+The pinned libleptris version lives in `libleptris-version.txt`
+(lockstep releases); CI builds it from the release tarball. The
+binding loads the shared library from `LEPTRIS_LIB_PATH` or the
+loader path.
+
+## Requirements
+
+- Python 3.8+
+- `cffi` (`pip install cffi`)
+- libleptris as a shared library (`libleptris.dylib` / `libleptris.so`)
+  on the loader path, or pointed to by `LEPTRIS_LIB_PATH`. For a
+  development checkout:
+
+```bash
+cmake -B build -S . -DLEPTRIS_BUILD_SHARED=ON
+cmake --build build --target leptris_shared
+export LEPTRIS_LIB_PATH=$PWD/build/src/libleptris.dylib
+```
+
+## Quick start
+
+```python
+from leptris import Document
+
+doc = Document.parse("<library><book id='1'>Ulysses</book></library>")
+
+doc.root.name                     # "library"
+book = doc.root.first_child_element
+book.name                         # "book"
+book.attribute("id")              # "1"
+book.text                         # "Ulysses"
+
+doc.xpath("count(//book)")        # 1.0
+[e.text for e in doc.xpath("//book")]   # ["Ulysses"]
+
+doc.close()   # or: with Document.parse(xml) as doc: ...
+```
+
+## Layout
+
+- `leptris/_ffi.py` — cdef + shared-library loading (single source
+  of the C surface, mirroring the Ruby binding's `lib/leptris.rb`)
+- `leptris/document.py`, `element.py`, `node.py`, `xpath.py`,
+  `error.py` — typed wrappers
+- `tests/` — pytest suite (run: `pytest` with `LEPTRIS_LIB_PATH` set)
+
+## Memory model
+
+The `Document` owns the whole tree and its pool. Accessor strings
+are copied into Python `str` at the boundary, so nothing depends on
+document lifetime after a call returns. Elements keep a reference to
+their `Document`, so the pool cannot be freed while any wrapper is
+alive. Prefer explicit `close()` / the context manager; `__del__` is
+a refcounting safety net, not a contract.
+
+## Versioning
+
+The package version tracks libleptris (lockstep): library 1.1.0 ↔
+leptris 1.1.0.
+
+## Publishing
+
+Releases publish to PyPI via `.github/workflows/release.yml`,
+using PyPI **trusted publishing** (no stored credentials). The
+workflow runs on manual dispatch (ships the version in
+`pyproject.toml`) and is called by the libleptris release flow
+(`publish: true`), so every libleptris release ships the wheel.
+
+## Local development
+
+```bash
+python3 -m venv .venv
+./.venv/bin/pip install --upgrade build setuptools wheel pytest cffi
+./.venv/bin/python -m build
+LEPTRIS_LIB_PATH=../../build-shared/src/libleptris.dylib \
+  ./.venv/bin/python -m pytest tests/ -q
+```

leptris-1.2.0/leptris.egg-info/SOURCES.txt

@@ -0,0 +1,15 @@
+README.md
+pyproject.toml
+leptris/__init__.py
+leptris/_ffi.py
+leptris/document.py
+leptris/element.py
+leptris/error.py
+leptris/node.py
+leptris/xpath.py
+leptris.egg-info/PKG-INFO
+leptris.egg-info/SOURCES.txt
+leptris.egg-info/dependency_links.txt
+leptris.egg-info/requires.txt
+leptris.egg-info/top_level.txt
+tests/test_binding.py

leptris-1.2.0/leptris.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

leptris-1.2.0/leptris.egg-info/requires.txt

@@ -0,0 +1,4 @@
+cffi
+
+[test]
+pytest

leptris-1.2.0/leptris.egg-info/top_level.txt

@@ -0,0 +1 @@
+leptris

leptris-1.2.0/pyproject.toml

@@ -0,0 +1,19 @@
+[build-system]
+requires = ["setuptools", "cffi"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "leptris"
+version = "1.2.0"
+description = "Python bindings for libleptris — fast XML 1.0 parsing and XPath 1.0"
+readme = "README.md"
+requires-python = ">=3.8"
+license = { text = "MIT" }
+authors = [{ name = "Ribose" }]
+dependencies = ["cffi"]
+
+[project.optional-dependencies]
+test = ["pytest"]
+
+[tool.setuptools]
+packages = ["leptris"]

leptris-1.2.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

leptris-1.2.0/tests/test_binding.py

@@ -0,0 +1,147 @@
+import pytest
+
+from leptris import Document, LeptrisError
+
+XML = """<?xml version="1.0"?>
+<library>
+  <book id="1" lang="en">Ulysses</book>
+  <book id="2" lang="fr">L'Etranger</book>
+  <!-- a comment -->
+</library>"""
+
+
+@pytest.fixture()
+def doc():
+    with Document.parse(XML) as doc:
+        yield doc
+
+
+class TestParse:
+    def test_root_name(self, doc):
+        assert doc.root.name == "library"
+
+    def test_root_is_element(self, doc):
+        assert doc.root.to_node().is_element()
+
+    def test_parse_error_raises(self):
+        with pytest.raises(LeptrisError):
+            Document.parse("<unclosed>")
+
+    def test_bytes_input(self):
+        with Document.parse(b"<r/>") as doc:
+            assert doc.root.name == "r"
+
+    def test_type_error_on_non_string(self):
+        with pytest.raises(TypeError):
+            Document.parse(123)
+
+    def test_close_is_idempotent(self):
+        doc = Document.parse("<r/>")
+        doc.close()
+        doc.close()
+        assert doc.closed
+
+
+class TestElement:
+    def test_child_iteration(self, doc):
+        books = list(doc.root)
+        assert [b.name for b in books] == ["book", "book"]
+
+    def test_attribute(self, doc):
+        book = doc.root.first_child_element
+        assert book.attribute("id") == "1"
+        assert book.attribute("lang") == "en"
+
+    def test_attribute_default(self, doc):
+        book = doc.root.first_child_element
+        assert book.attribute("nope") is None
+        assert book.attribute("nope", "x") == "x"
+
+    def test_attributes_iteration(self, doc):
+        book = doc.root.first_child_element
+        pairs = list(book.attributes())
+        assert pairs == [("id", "1"), ("lang", "en")]
+        assert book.attribute_count == 2
+
+    def test_attributes_entity_expansion_and_empty(self):
+        with Document.parse('<e t="a &amp; b"/>') as doc:
+            assert list(doc.root.attributes()) == [("t", "a & b")]
+        with Document.parse("<e/>") as doc:
+            assert list(doc.root.attributes()) == []
+            assert doc.root.attribute_count == 0
+
+    def test_text(self, doc):
+        book = doc.root.first_child_element
+        assert book.text == "Ulysses"
+
+    def test_parent(self, doc):
+        book = doc.root.first_child_element
+        assert book.parent is not None
+        assert book.parent.name == "library"
+
+    def test_next_sibling(self, doc):
+        first = doc.root.first_child_element
+        second = first.next_sibling_element
+        assert second is not None
+        assert second.attribute("id") == "2"
+
+
+class TestNode:
+    def test_node_types(self, doc):
+        node = doc.root.to_node()
+        types = set()
+        child = node.first_child
+        while child is not None:
+            types.add(child.type)
+            child = child.next_sibling
+        assert 1 in types  # text
+        assert 2 in types  # comment
+
+    def test_comment_content(self, doc):
+        node = doc.root.to_node().first_child
+        comments = []
+        while node is not None:
+            if node.is_comment():
+                comments.append(node.content)
+            node = node.next_sibling
+        # Comment content is the exact inner text, whitespace included.
+        assert comments == [" a comment "]
+
+    def test_child_count_counts_elements(self, doc):
+        # child_count is elements-only: root has 2 books plus
+        # interleaved text nodes that are not counted.
+        assert doc.root.to_node().child_count == 2
+
+
+class TestXPath:
+    def test_count(self, doc):
+        assert doc.xpath("count(//book)") == 2.0
+
+    def test_nodeset(self, doc):
+        books = doc.xpath("//book")
+        assert len(books) == 2
+        assert books[0].text == "Ulysses"
+
+    def test_string(self, doc):
+        assert doc.xpath("string(//book[@id='2'])") == "L'Etranger"
+
+    def test_boolean(self, doc):
+        assert doc.xpath("count(//book) = 2") is True
+        assert doc.xpath("count(//book) = 5") is False
+
+    def test_element_context(self, doc):
+        book = doc.root.first_child_element
+        assert book.xpath("string(@id)") == "1"
+
+    def test_error_raises(self, doc):
+        with pytest.raises(LeptrisError):
+            doc.xpath("///[")
+
+
+class TestSerialize:
+    def test_round_trip(self, doc):
+        out = doc.serialize()
+        assert "<library>" in out
+        reparsed = Document.parse(out)
+        assert reparsed.xpath("count(//book)") == 2.0
+        reparsed.close()