xmlcst 0.1.0__py3-none-any.whl

xmlcst/__init__.py

@@ -0,0 +1,42 @@
+"""Full-fidelity XML concrete syntax tree -- parse, edit, and serialize with zero formatting loss."""
+
+from ._api import parse, parse_bytes, parse_file
+from ._errors import ParseError
+from ._nodes import (
+    Attribute,
+    AttributeList,
+    CData,
+    Comment,
+    Doctype,
+    Document,
+    Element,
+    Node,
+    ProcessingInstruction,
+    SerializationMode,
+    Text,
+    Whitespace,
+    XmlDeclaration,
+)
+from ._tokens import Token, TokenType
+
+__all__ = [
+    "parse",
+    "parse_bytes",
+    "parse_file",
+    "ParseError",
+    "Attribute",
+    "AttributeList",
+    "CData",
+    "Comment",
+    "Doctype",
+    "Document",
+    "Element",
+    "Node",
+    "ProcessingInstruction",
+    "SerializationMode",
+    "Text",
+    "Token",
+    "TokenType",
+    "Whitespace",
+    "XmlDeclaration",
+]

xmlcst/_api.py

@@ -0,0 +1,47 @@
+from __future__ import annotations
+
+from pathlib import Path
+
+from ._builder import build_tree
+from ._nodes import Document
+from ._tokenizer import tokenize
+
+_UTF8_BOM = b"\xef\xbb\xbf"
+
+
+def parse(text: str) -> Document:
+    """Parse an XML string into a Document.
+
+    Raises:
+        ParseError: If the input is not well-formed XML.
+    """
+    tokens = tokenize(text)
+    return build_tree(tokens)
+
+
+def parse_bytes(data: bytes) -> Document:
+    """Parse UTF-8 encoded XML bytes into a Document.
+
+    A leading UTF-8 BOM is detected and preserved on round-trip.
+
+    Raises:
+        ParseError: If the input is not well-formed XML.
+    """
+    bom = data.startswith(_UTF8_BOM)
+    if bom:
+        data = data[3:]
+    text = data.decode("utf-8")
+    tokens = tokenize(text)
+    doc = build_tree(tokens)
+    doc.bom = bom
+    return doc
+
+
+def parse_file(path: str | Path) -> Document:
+    """Read a file and parse its contents as XML.
+
+    Raises:
+        ParseError: If the file contents are not well-formed XML.
+    """
+    data = Path(path).read_bytes()
+    return parse_bytes(data)

xmlcst/_builder.py

@@ -0,0 +1,319 @@
+from __future__ import annotations
+
+import re
+
+from ._errors import ParseError
+from ._nodes import (
+    Attribute,
+    CData,
+    Comment,
+    Doctype,
+    Document,
+    Element,
+    Node,
+    ProcessingInstruction,
+    Text,
+    Whitespace,
+    XmlDeclaration,
+)
+from ._tokens import Token, TokenType
+
+_XMLDECL_RE = re.compile(
+    r"""
+    \s+version\s*=\s*(['"])(?P<version>[^'"]*)\1
+    (?:\s+encoding\s*=\s*(['"])(?P<encoding>[^'"]*)\3)?
+    (?:\s+standalone\s*=\s*(['"])(?P<standalone>[^'"]*)\5)?
+    \s*
+    """,
+    re.VERBOSE,
+)
+
+
+def build_tree(tokens: list[Token]) -> Document:
+    pos = 0
+    length = len(tokens)
+
+    def _cur() -> Token:
+        return tokens[pos]
+
+    def _at_end() -> bool:
+        return pos >= length
+
+    def _build_children(_parent_tag: str | None) -> tuple[list[Node], int]:
+        nonlocal pos
+        children: list[Node] = []
+        while not _at_end():
+            tt = _cur().type
+            if tt == TokenType.EndTag:
+                break
+            node, _end_pos = _build_node()
+            if node is not None:
+                children.append(node)
+        return children, pos
+
+    def _build_node() -> tuple[Node | None, int]:
+        nonlocal pos
+        tok = _cur()
+        tt = tok.type
+
+        if tt == TokenType.XmlDeclOpen:
+            return _build_xml_decl()
+        if tt == TokenType.Doctype:
+            return _build_doctype()
+        if tt == TokenType.CommentOpen:
+            return _build_comment()
+        if tt == TokenType.PiOpen:
+            return _build_pi()
+        if tt == TokenType.CDataOpen:
+            return _build_cdata()
+        if tt == TokenType.StartTagOpen:
+            return _build_element()
+        if tt == TokenType.Whitespace:
+            return _build_whitespace()
+        if tt in (TokenType.Text, TokenType.EntityRef, TokenType.CharRef):
+            return _build_text()
+        raise ParseError(f"unexpected token {tt.value}", 1, 1, tok.offset)
+
+    def _build_xml_decl() -> tuple[XmlDeclaration, int]:
+        nonlocal pos
+        start = pos
+        pos += 1
+
+        ws_content = ""
+        if not _at_end() and _cur().type == TokenType.Whitespace:
+            ws_content = _cur().text
+            pos += 1
+
+        if _at_end() or _cur().type != TokenType.XmlDeclClose:
+            raise ParseError("unterminated XML declaration", 1, 1, tokens[start].offset)
+        pos += 1
+
+        raw_text = "".join(t.text for t in tokens[start:pos])
+
+        version = "1.0"
+        encoding = None
+        standalone = None
+
+        m = _XMLDECL_RE.match(ws_content)
+        if m:
+            version = m.group("version")
+            encoding = m.group("encoding")
+            standalone = m.group("standalone")
+
+        node = XmlDeclaration(
+            version=version,
+            encoding=encoding,
+            standalone=standalone,
+            raw_text=raw_text,
+            token_span=(start, pos),
+            tokens_ref=tokens,
+        )
+        return node, pos
+
+    def _build_doctype() -> tuple[Doctype, int]:
+        nonlocal pos
+        start = pos
+        raw_text = _cur().text
+        pos += 1
+        node = Doctype(raw_text=raw_text, token_span=(start, pos), tokens_ref=tokens)
+        return node, pos
+
+    def _build_comment() -> tuple[Comment, int]:
+        nonlocal pos
+        start = pos
+        pos += 1
+        content = ""
+        if not _at_end() and _cur().type == TokenType.CommentContent:
+            content = _cur().text
+            pos += 1
+        if _at_end() or _cur().type != TokenType.CommentClose:
+            raise ParseError("unterminated comment", 1, 1, tokens[start].offset)
+        pos += 1
+        node = Comment(content=content, token_span=(start, pos), tokens_ref=tokens)
+        return node, pos
+
+    def _build_pi() -> tuple[ProcessingInstruction, int]:
+        nonlocal pos
+        start = pos
+        open_text = _cur().text
+        target = open_text[2:]
+        pos += 1
+        content = ""
+        if not _at_end() and _cur().type == TokenType.PiContent:
+            content = _cur().text
+            pos += 1
+        if _at_end() or _cur().type != TokenType.PiClose:
+            raise ParseError("unterminated PI", 1, 1, tokens[start].offset)
+        pos += 1
+        node = ProcessingInstruction(
+            target=target, content=content, token_span=(start, pos), tokens_ref=tokens
+        )
+        return node, pos
+
+    def _build_cdata() -> tuple[CData, int]:
+        nonlocal pos
+        start = pos
+        pos += 1
+        content = ""
+        if not _at_end() and _cur().type == TokenType.CDataContent:
+            content = _cur().text
+            pos += 1
+        if _at_end() or _cur().type != TokenType.CDataClose:
+            raise ParseError("unterminated CDATA", 1, 1, tokens[start].offset)
+        pos += 1
+        node = CData(content=content, token_span=(start, pos), tokens_ref=tokens)
+        return node, pos
+
+    def _build_whitespace() -> tuple[Whitespace, int]:
+        nonlocal pos
+        start = pos
+        content = _cur().text
+        pos += 1
+        node = Whitespace(content=content, token_span=(start, pos), tokens_ref=tokens)
+        return node, pos
+
+    def _build_text() -> tuple[Text, int]:
+        nonlocal pos
+        start = pos
+        parts: list[str] = []
+        while not _at_end() and _cur().type in (
+            TokenType.Text,
+            TokenType.EntityRef,
+            TokenType.CharRef,
+        ):
+            parts.append(_cur().text)
+            pos += 1
+        content = "".join(parts)
+        node = Text(content=content, token_span=(start, pos), tokens_ref=tokens)
+        return node, pos
+
+    def _build_element() -> tuple[Element, int]:
+        nonlocal pos
+        start = pos
+        open_tok = _cur()
+        tag = open_tok.text[1:]
+        pos += 1
+
+        attrs: list[Attribute] = []
+        self_closing = False
+        empty_close_text = "/>"
+        trailing_ws = ""
+
+        while not _at_end():
+            tt = _cur().type
+            if tt == TokenType.StartTagClose:
+                pos += 1
+                break
+            if tt == TokenType.EmptyTagClose:
+                self_closing = True
+                empty_close_text = trailing_ws + _cur().text
+                pos += 1
+                break
+            if tt == TokenType.Whitespace:
+                ws_text = _cur().text
+                pos += 1
+                if not _at_end() and _cur().type == TokenType.AttrName:
+                    attr = _build_attribute(ws_text)
+                    attrs.append(attr)
+                    trailing_ws = ""
+                else:
+                    trailing_ws = ws_text
+                continue
+            if tt == TokenType.AttrName:
+                attr = _build_attribute("")
+                attrs.append(attr)
+                trailing_ws = ""
+                continue
+            raise ParseError(
+                f"unexpected token in start tag: {tt.value}",
+                1,
+                1,
+                _cur().offset,
+            )
+
+        elem = Element(tag=tag, token_span=(start, -1), tokens_ref=tokens)
+        elem._self_closing = self_closing
+        elem._empty_close_text = empty_close_text
+        for attr in attrs:
+            elem._attributes._append_parsed(attr)
+
+        if not self_closing:
+            children, _ = _build_children(tag)
+            elem._children = children
+
+            if _at_end() or _cur().type != TokenType.EndTag:
+                raise ParseError(
+                    f"missing end tag for <{tag}>", 1, 1, tokens[start].offset
+                )
+
+            end_tok = _cur()
+            end_tag_name = end_tok.text[2:-1].strip()
+            if end_tag_name != tag:
+                raise ParseError(
+                    f"mismatched tags: <{tag}> and </{end_tag_name}>",
+                    1,
+                    1,
+                    end_tok.offset,
+                )
+            elem._end_tag_text = end_tok.text
+            pos += 1
+
+        elem._token_span = (start, pos)
+        elem._dirty = False
+        return elem, pos
+
+    def _build_attribute(leading_ws: str) -> Attribute:
+        nonlocal pos
+        name = _cur().text
+        pos += 1
+
+        if _at_end() or _cur().type != TokenType.AttrEq:
+            raise ParseError(
+                f"expected '=' after attribute {name!r}", 1, 1, tokens[pos - 1].offset
+            )
+
+        eq_text = _cur().text
+        pos += 1
+        idx = eq_text.index("=")
+        before_eq = eq_text[:idx]
+        after_eq = eq_text[idx + 1 :]
+        eq_whitespace = (before_eq, after_eq)
+
+        if _at_end() or _cur().type != TokenType.AttrValueOpen:
+            raise ParseError(
+                f"expected quote for attribute {name!r}", 1, 1, tokens[pos - 1].offset
+            )
+        quote = _cur().text
+        pos += 1
+
+        value_parts: list[str] = []
+        while not _at_end() and _cur().type != TokenType.AttrValueClose:
+            value_parts.append(_cur().text)
+            pos += 1
+
+        if _at_end():
+            raise ParseError(
+                f"unterminated attribute value for {name!r}",
+                1,
+                1,
+                tokens[pos - 1].offset,
+            )
+        pos += 1
+
+        raw_value = "".join(value_parts)
+
+        return Attribute(
+            name=name,
+            raw_value=raw_value,
+            quote=quote,
+            leading_whitespace=leading_ws,
+            eq_whitespace=eq_whitespace,
+        )
+
+    children: list[Node] = []
+    while not _at_end():
+        node, _ = _build_node()
+        if node is not None:
+            children.append(node)
+
+    return Document(children=children, bom=False, tokens=tokens)

xmlcst/_entities.py

@@ -0,0 +1,41 @@
+from __future__ import annotations
+
+import re
+
+_BUILTIN_ENTITIES: dict[str, str] = {
+    "amp": "&",
+    "lt": "<",
+    "gt": ">",
+    "apos": "'",
+    "quot": '"',
+}
+
+_REF_RE = re.compile(r"&(?:#x([0-9a-fA-F]+)|#([0-9]+)|([a-zA-Z_][\w.-]*));")
+
+
+def decode_references(raw: str) -> str:
+    def _replace(m: re.Match[str]) -> str:
+        if m.group(1) is not None:
+            return chr(int(m.group(1), 16))
+        if m.group(2) is not None:
+            return chr(int(m.group(2)))
+        name = m.group(3)
+        return _BUILTIN_ENTITIES.get(name, m.group(0))
+
+    return _REF_RE.sub(_replace, raw)
+
+
+def escape_for_attr(decoded: str, quote: str) -> str:
+    result = decoded.replace("&", "&amp;")
+    result = result.replace("<", "&lt;")
+    if quote == '"':
+        result = result.replace('"', "&quot;")
+    elif quote == "'":
+        result = result.replace("'", "&apos;")
+    return result
+
+
+def escape_for_text(decoded: str) -> str:
+    result = decoded.replace("&", "&amp;")
+    result = result.replace("<", "&lt;")
+    return result

xmlcst/_errors.py

@@ -0,0 +1,19 @@
+from __future__ import annotations
+
+
+class ParseError(Exception):
+    """Raised when the XML source is malformed.
+
+    Attributes:
+        message: Human-readable description of the error.
+        line: 1-based line number where the error was detected.
+        column: 1-based column number where the error was detected.
+        offset: 0-based character offset from the start of the source.
+    """
+
+    def __init__(self, message: str, line: int, column: int, offset: int) -> None:
+        self.message = message
+        self.line = line
+        self.column = column
+        self.offset = offset
+        super().__init__(f"{message} at line {line}, column {column}")