dompy-parser 0.2.0__py3-none-any.whl

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
dompy/parser.py ADDED
@@ -0,0 +1,176 @@
1
+ """HTML5 document and contextual fragment parsing."""
2
+
3
+ from justhtml import Element as ParsedElement
4
+ from justhtml.parser.context import FragmentContext
5
+ from justhtml.parser.encoding import decode_html
6
+ from justhtml.parser.engine import ParseEngine, compile_raw_engine_plan
7
+
8
+ from .models import (
9
+ HTML_NAMESPACE,
10
+ MATHML_NAMESPACE,
11
+ SVG_NAMESPACE,
12
+ Comment,
13
+ DocumentFragment,
14
+ DocumentType,
15
+ Element,
16
+ Node,
17
+ ProcessingInstruction,
18
+ Text,
19
+ ascii_lower,
20
+ )
21
+
22
+ NAMESPACES = {"html": HTML_NAMESPACE, "svg": SVG_NAMESPACE, "math": MATHML_NAMESPACE}
23
+ PARSER_NAMESPACES = {uri: prefix for prefix, uri in NAMESPACES.items()}
24
+
25
+
26
+ class _TreeBuilder(ParseEngine):
27
+ """Seed contextual HTML parser state unavailable through JustHTML's public API."""
28
+
29
+ # The fragment context node is allocated just before the first token.
30
+ def _parse_range(self, pos, end):
31
+ if pos == 0 and self.context_encoding is not None:
32
+ self._fragment_context_node.attrs["encoding"] = self.context_encoding
33
+ return super()._parse_range(pos, end)
34
+
35
+
36
+ def _parse(
37
+ markup,
38
+ *,
39
+ scripting=False,
40
+ encoding=None,
41
+ context=None,
42
+ inside_form=False,
43
+ context_encoding=None,
44
+ document_mode=None,
45
+ ):
46
+ if isinstance(markup, (bytes, bytearray, memoryview)):
47
+ markup, _ = decode_html(bytes(markup), transport_encoding=encoding)
48
+ if not isinstance(markup, str):
49
+ raise TypeError("HTML input must be text or bytes")
50
+
51
+ html_context = context is not None and context.namespace == "html"
52
+ # Fragment parsing in an HTML root starts in the document's before-head
53
+ # insertion mode. Use the document shell and unwrap it after parsing.
54
+ html_shell = html_context and context.tag_name == "html"
55
+ fragment = context is not None and not html_shell
56
+ engine = _TreeBuilder(
57
+ markup,
58
+ fragment=fragment,
59
+ fragment_context=context if fragment else None,
60
+ scripting_enabled=scripting,
61
+ plan=compile_raw_engine_plan(fragment=fragment, scripting_enabled=scripting),
62
+ )
63
+ engine.context_encoding = context_encoding
64
+ if context is not None:
65
+ engine._quirks_mode = document_mode if document_mode else "no-quirks"
66
+ if html_context and context.tag_name == "template":
67
+ engine._enter_template_mode()
68
+ if inside_form:
69
+ engine._form_element = ParsedElement("form", {}, "html")
70
+ root = engine.parse()
71
+ if html_shell:
72
+ root.children = [
73
+ child
74
+ for node in root.children
75
+ for child in (node.children if node.name == "html" else [node])
76
+ ]
77
+ return root, engine._quirks_mode or "quirks"
78
+
79
+
80
+ def _convert(source, target):
81
+ """Copy the parsed tree without recursing into the Python call stack."""
82
+ stack = [(source, target)]
83
+ while stack:
84
+ parsed, parent = stack.pop()
85
+ owner = (
86
+ parent if parent.nodeType == Node.DOCUMENT_NODE else parent.ownerDocument
87
+ )
88
+ for child in parsed.children or ():
89
+ if child.name == "#text":
90
+ node = Text(child.data)
91
+ elif child.name == "#comment":
92
+ node = Comment(child.data)
93
+ elif child.name == "#processing-instruction":
94
+ target_name, _, data = child.data.partition(" ")
95
+ node = ProcessingInstruction(target_name, data)
96
+ elif child.name == "!doctype":
97
+ info = child.data
98
+ node = DocumentType(
99
+ info.name or "", info.public_id or "", info.system_id or ""
100
+ )
101
+ else:
102
+ attributes = {name: value or "" for name, value in child.attrs.items()}
103
+ node = Element(
104
+ child.name, attributes, namespace=NAMESPACES[child.namespace]
105
+ )
106
+ stack.append((child, node))
107
+ if node.templateContent is not None:
108
+ node.templateContent._document = (
109
+ owner._template_owner() if owner else None
110
+ )
111
+ stack.append((child.template_content, node.templateContent))
112
+ node._document = owner
113
+ parent._append(node)
114
+
115
+
116
+ class DompyParser:
117
+ @classmethod
118
+ def parse(cls, input, *, scripting=False, encoding=None) -> Element:
119
+ """Parse a document and return its HTML root element."""
120
+ from .document import Document
121
+
122
+ return Document.fromString(
123
+ input, scripting=scripting, encoding=encoding
124
+ ).documentElement
125
+
126
+ @classmethod
127
+ def parseFragment(
128
+ cls,
129
+ markup,
130
+ context: str | Element = "div",
131
+ *,
132
+ scripting: bool = False,
133
+ encoding: str | None = None,
134
+ ) -> DocumentFragment:
135
+ """Parse markup in an HTML, SVG, or MathML element context."""
136
+ if isinstance(context, Element):
137
+ tag = context.localName
138
+ namespace = PARSER_NAMESPACES.get(context.namespaceURI, "html")
139
+ owner = context.ownerDocument
140
+ context_encoding = (
141
+ context.getAttribute("encoding")
142
+ if tag == "annotation-xml" and namespace == "math"
143
+ else None
144
+ )
145
+ ancestor = context
146
+ while ancestor is not None:
147
+ if ancestor.tag == "form" and ancestor.namespaceURI == HTML_NAMESPACE:
148
+ break
149
+ ancestor = ancestor.parentElement
150
+ inside_form = ancestor is not None
151
+ elif isinstance(context, str) and context:
152
+ tag = ascii_lower(context)
153
+ namespace = "html"
154
+ owner = None
155
+ context_encoding = None
156
+ inside_form = tag == "form"
157
+ else:
158
+ raise TypeError("Fragment context must be a tag name or an Element")
159
+
160
+ # Both contexts use RCDATA. A fragment has no opening textarea token
161
+ # that would cause the parser to discard an initial line feed.
162
+ if tag == "textarea" and namespace == "html":
163
+ tag = "title"
164
+ source, _ = _parse(
165
+ markup,
166
+ context=FragmentContext(tag, namespace),
167
+ scripting=scripting,
168
+ encoding=encoding,
169
+ inside_form=inside_form,
170
+ context_encoding=context_encoding,
171
+ document_mode=owner._mode if owner is not None else None,
172
+ )
173
+ fragment = DocumentFragment()
174
+ fragment._document = owner
175
+ _convert(source, fragment)
176
+ return fragment
dompy/selectors.py ADDED
@@ -0,0 +1,100 @@
1
+ """Adapt the DOM tree for Soup Sieve's CSS selector engine."""
2
+
3
+ from bs4 import BeautifulSoup
4
+ from bs4 import Comment as SoupComment
5
+ from bs4 import ProcessingInstruction as SoupInstruction
6
+ from soupsieve import SelectorSyntaxError as SelectorError
7
+ from soupsieve import compile as compile_selector
8
+ from soupsieve.css_match import CSSMatch
9
+
10
+ from .models import Comment, Element, Node, ProcessingInstruction, Text, ascii_lower
11
+
12
+
13
+ class _DOMMatcher(CSSMatch):
14
+ def __init__(self, compiled, tag, scope, root):
15
+ super().__init__(compiled.selectors, tag, compiled.namespaces, compiled.flags)
16
+ if root.nodeType != Node.DOCUMENT_NODE:
17
+ self.root = None
18
+ if scope.nodeType == Node.DOCUMENT_FRAGMENT_NODE:
19
+ self.scope = None
20
+ document = root if root.nodeType == Node.DOCUMENT_NODE else root.ownerDocument
21
+ self.quirks = document is not None and document.compatMode == "BackCompat"
22
+
23
+ def match_id(self, el, ids):
24
+ if self.quirks:
25
+ value = ascii_lower(self.get_attribute_by_name(el, "id", ""))
26
+ return all(ascii_lower(identifier) == value for identifier in ids)
27
+ return super().match_id(el, ids)
28
+
29
+ def match_classes(self, el, classes):
30
+ if self.quirks:
31
+ values = {ascii_lower(value) for value in self.get_classes(el)}
32
+ return all(ascii_lower(token) in values for token in classes)
33
+ return super().match_classes(el, classes)
34
+
35
+
36
+ def _projection(scope):
37
+ # Match against the whole containing tree. The search scope limits which
38
+ # nodes are returned, while combinators can still inspect its ancestors.
39
+ soup = BeautifulSoup("", "html.parser")
40
+ root = scope.getRootNode()
41
+ element_by_tag = {}
42
+ scope_tag = soup
43
+ if isinstance(root, Element):
44
+ stack = [(root, soup)]
45
+ else:
46
+ stack = [(node, soup) for node in reversed(root._children)]
47
+
48
+ while stack:
49
+ node, parent = stack.pop()
50
+ if isinstance(node, Element):
51
+ tag = soup.new_tag(
52
+ node.localName, namespace=node.namespaceURI, attrs=node.attributes
53
+ )
54
+ parent.append(tag)
55
+ element_by_tag[id(tag)] = node
56
+ if node is scope:
57
+ scope_tag = tag
58
+ stack.extend((child, tag) for child in reversed(node._children))
59
+ elif isinstance(node, Text):
60
+ parent.append(soup.new_string(node.data))
61
+ elif isinstance(node, Comment):
62
+ parent.append(soup.new_string(node.data, SoupComment))
63
+ elif isinstance(node, ProcessingInstruction):
64
+ parent.append(soup.new_string(node.data, SoupInstruction))
65
+ return scope_tag, element_by_tag, root
66
+
67
+
68
+ def _compile(selector):
69
+ try:
70
+ return compile_selector(selector)
71
+ except NotImplementedError as error:
72
+ raise SelectorError(str(error)) from error
73
+
74
+
75
+ def _matcher(scope, selector):
76
+ compiled = _compile(selector)
77
+ tag, elements, root = _projection(scope)
78
+ return _DOMMatcher(compiled, tag, scope, root), elements
79
+
80
+
81
+ def select(scope, selector, *, first=False):
82
+ matcher, elements = _matcher(scope, selector)
83
+ if first:
84
+ match = next(matcher.select(limit=1), None)
85
+ return None if match is None else elements[id(match)]
86
+ return [elements[id(match)] for match in matcher.select()]
87
+
88
+
89
+ def match(element, selector):
90
+ matcher, _ = _matcher(element, selector)
91
+ return matcher.match(matcher.tag)
92
+
93
+
94
+ def closest(element, selector):
95
+ matcher, elements = _matcher(element, selector)
96
+ match = matcher.closest()
97
+ return None if match is None else elements[id(match)]
98
+
99
+
100
+ __all__ = ["SelectorError"]
dompy/serialization.py ADDED
@@ -0,0 +1,79 @@
1
+ """Compact HTML serialization of the current tree."""
2
+
3
+ from .models import (
4
+ HTML_NAMESPACE,
5
+ Comment,
6
+ DocumentType,
7
+ Element,
8
+ ProcessingInstruction,
9
+ Tags,
10
+ Text,
11
+ )
12
+
13
+ _RAW_TEXT = frozenset(
14
+ {"iframe", "noembed", "noframes", "plaintext", "script", "style", "xmp"}
15
+ )
16
+ _TEXT_ESCAPES = str.maketrans(
17
+ {"&": "&amp;", "\xa0": "&nbsp;", "<": "&lt;", ">": "&gt;"}
18
+ )
19
+ _ATTRIBUTE_ESCAPES = str.maketrans(
20
+ {"&": "&amp;", "\xa0": "&nbsp;", '"': "&quot;", "<": "&lt;", ">": "&gt;"}
21
+ )
22
+
23
+
24
+ def _markup_children(node):
25
+ if isinstance(node, Element) and node.templateContent is not None:
26
+ return node.templateContent._children
27
+ return node._children
28
+
29
+
30
+ def _raw_text(parent):
31
+ if not isinstance(parent, Element) or parent.namespaceURI != HTML_NAMESPACE:
32
+ return False
33
+ if parent.tag == "noscript":
34
+ return parent.ownerDocument is not None and parent.ownerDocument._scripting
35
+ return parent.tag in _RAW_TEXT
36
+
37
+
38
+ def _serialize_nodes(nodes):
39
+ parts = []
40
+ stack = list(reversed(nodes))
41
+ while stack:
42
+ node = stack.pop()
43
+ if isinstance(node, str):
44
+ parts.append(node)
45
+ elif isinstance(node, Element):
46
+ attributes = "".join(
47
+ f' {name}="{value.translate(_ATTRIBUTE_ESCAPES)}"'
48
+ for name, value in node.attributes.items()
49
+ )
50
+ parts.append(f"<{node.tag}{attributes}>")
51
+ if (
52
+ node.namespaceURI != HTML_NAMESPACE
53
+ or node.tag not in Tags.selfClosingTags
54
+ ):
55
+ stack.append(f"</{node.tag}>")
56
+ stack.extend(reversed(_markup_children(node)))
57
+ elif isinstance(node, Text):
58
+ parts.append(
59
+ node.data
60
+ if _raw_text(node.parentNode)
61
+ else node.data.translate(_TEXT_ESCAPES)
62
+ )
63
+ elif isinstance(node, Comment):
64
+ parts.append(f"<!--{node.data}-->")
65
+ elif isinstance(node, DocumentType):
66
+ parts.append(f"<!DOCTYPE {node.name}>")
67
+ elif isinstance(node, ProcessingInstruction):
68
+ parts.append(f"<?{node.target} {node.data}?>")
69
+ else:
70
+ stack.extend(reversed(node._children))
71
+ return "".join(parts)
72
+
73
+
74
+ def serialize(node):
75
+ return _serialize_nodes([node])
76
+
77
+
78
+ def serialize_children(node):
79
+ return _serialize_nodes(_markup_children(node))
dompy/uitils.py ADDED
@@ -0,0 +1,7 @@
1
+ """Legacy utility imports."""
2
+
3
+ from .models import Node
4
+
5
+
6
+ def hasChildren(node: Node) -> bool:
7
+ return node.hasChildNodes()
@@ -0,0 +1,98 @@
1
+ Metadata-Version: 2.4
2
+ Name: dompy-parser
3
+ Version: 0.2.0
4
+ Summary: HTML5 parsing and browser-style DOM APIs for Python
5
+ Author-email: Anikesh Patel <developeranikesh@gmail.com>
6
+ License-Expression: GPL-3.0-only
7
+ Project-URL: Repository, https://github.com/Anikeshpatel/dompy
8
+ Keywords: html,html5,dom,parser,web scraping
9
+ Classifier: Development Status :: 3 - Alpha
10
+ Classifier: Intended Audience :: Developers
11
+ Classifier: Programming Language :: Python :: 3
12
+ Requires-Python: >=3.10
13
+ Description-Content-Type: text/markdown
14
+ License-File: LICENSE
15
+ Requires-Dist: beautifulsoup4<5,>=4.14
16
+ Requires-Dist: justhtml<3.18,>=3.17.1
17
+ Requires-Dist: soupsieve<2.11,>=2.10
18
+ Provides-Extra: test
19
+ Requires-Dist: pytest<10,>=8; extra == "test"
20
+ Requires-Dist: pytest-cov<8,>=6; extra == "test"
21
+ Provides-Extra: browser
22
+ Requires-Dist: playwright<2,>=1.50; extra == "browser"
23
+ Dynamic: license-file
24
+
25
+ # Dompy
26
+
27
+ Dompy turns HTML into an editable Python tree with browser-style DOM methods. It handles malformed markup, contextual fragments, mixed text, HTML templates, and SVG and MathML. Parsing is inert. Dompy preserves scripts and event-handler attributes as data and never executes them.
28
+
29
+ ## Install
30
+
31
+ Dompy requires Python 3.10 or later.
32
+
33
+ ```bash
34
+ python -m pip install dompy-parser
35
+ ```
36
+
37
+ To install this checkout, run `python -m pip install .` from the project root.
38
+
39
+ ## Parse, query, and edit
40
+
41
+ ```python
42
+ from dompy import Document, DompyParser
43
+
44
+ document = Document.fromString("""
45
+ <!doctype html>
46
+ <title>Inventory</title>
47
+ <main id="inventory">
48
+ <table><tr><td>Apples<td>5</table>
49
+ </main>
50
+ """)
51
+
52
+ table = document.querySelector("#inventory > table")
53
+ print(document.title) # Inventory
54
+ print(table.querySelector("tbody > tr").textContent) # Apples5
55
+
56
+ rows = table.getElementsByTagName("tr")
57
+ fragment = DompyParser.parseFragment("<tr><td>Pears<td>8", context="tbody")
58
+ table.querySelector("tbody").appendChild(fragment)
59
+ assert len(rows) == 2
60
+
61
+ cell = rows[1].querySelector("td")
62
+ cell.classList.add("product")
63
+ cell.textContent = "Green pears"
64
+ assert cell.outerHTML == '<td class="product">Green pears</td>'
65
+ ```
66
+
67
+ - `Document.fromString(html)` accepts text or bytes. Byte input supports HTML charset sniffing and an optional `encoding`.
68
+ - `Document.fromFile(path_or_stream)` accepts paths and open binary or text streams. `Document.fromURL(url, timeout=30)` loads an HTTP(S) response and uses its declared charset when present. `Document.fromURI(uri)` also accepts local file URIs.
69
+ - `Document.documentElement` (also `root`), `head`, `body`, `doctype`, `title`, and `compatMode` describe the parsed document. Use `str(document)` to serialize it.
70
+ - `querySelector` and `querySelectorAll` accept CSS selectors, including combinators, attribute tests, `:scope`, `:is()`, and `:has()`. Queries return the first element or `None`, or a snapshot list in document order. Invalid or unsupported selectors raise `SelectorError`.
71
+ - `getElementById` matches exact IDs. `getElementsByTagName`, `getElementsByClassName`, `children`, and `childNodes` provide live sequences. `children` contains only elements. `childNodes` includes text and comments.
72
+ - Read markup with `innerHTML` and `outerHTML`, and read or write text with `textContent`. Assigning `innerHTML` parses markup in the target element's context. HTML template contents live in `template.content`, a separate `DocumentFragment`.
73
+ - Create and edit nodes with `createElement`, `createTextNode`, `createComment`, `createDocumentFragment`, `appendChild`, `insertBefore`, `replaceChild`, `removeChild`, and `cloneNode`. Elements also support `matches`, `closest`, and attribute and class operations.
74
+
75
+ `DompyParser.parse(html)` returns the root `Element`. The original `getElementsByTag` and `getElementsByClass` methods return Python lists. `Element.tag` exposes the local tag name, and `Element.content` returns `innerHTML` for regular elements.
76
+
77
+ Dompy implements a static HTML DOM. Layout, JavaScript execution, event dispatch, and resource loading from markup are outside its scope. `scripting=True` changes how the parser handles `<noscript>`. CSS matching uses Soup Sieve, with limited support for browser state and no pseudo-elements. Serialization preserves potentially active markup, so treat the output as unsanitized HTML.
78
+
79
+ ## Test
80
+
81
+ ```bash
82
+ python -m pip install -e '.[test]'
83
+ python -m pytest --cov=dompy
84
+ ```
85
+
86
+ The browser suite compares Python trees, serialization, CSS queries, and fragment edits with Chromium's `DOMParser`. It runs offline once Chromium is installed.
87
+
88
+ ```bash
89
+ python -m pip install -e '.[test,browser]'
90
+ python -m playwright install chromium
91
+ DOMPY_BROWSER=chromium python -m pytest
92
+ ```
93
+
94
+ Set `DOMPY_BROWSER=chrome` to use a local Google Chrome installation.
95
+
96
+ ## License
97
+
98
+ Dompy is licensed under the GNU GPL v3. See [LICENSE](LICENSE).
@@ -0,0 +1,13 @@
1
+ dompy/__init__.py,sha256=DjGAh2eTdZ9Jf5cgTQkfj2K1-7tY2iZbmCUNA4xQh4M,501
2
+ dompy/document.py,sha256=4zEgOx--PDBAI7kuvhTe4_7amkTTTRE20xKipHP95UU,5968
3
+ dompy/event.py,sha256=wBWVa8AdROwoPRdHn3s3Kps1-50teHrWeawqezFDZ1Q,1012
4
+ dompy/models.py,sha256=-Rn0vjkOHOLugiJgzVM613LVykWWySM_grME9q5MW7g,21474
5
+ dompy/parser.py,sha256=aNl49aPxBCs3QT0DmpqAReAllh9KgskaFsdFrlbeTSo,6496
6
+ dompy/selectors.py,sha256=rVHxvkideyzFAk7bY6HY6ymZ5dlA-IUUx3rOpEGrLRc,3641
7
+ dompy/serialization.py,sha256=ZyXSgp4NIW9IlO3TV6mNhaIfzHEEWDfqST1T3KF7PPo,2401
8
+ dompy/uitils.py,sha256=HkEIC65yROxAYchjMGMlGPdsQUdYZPeTyhwirjCiEXo,127
9
+ dompy_parser-0.2.0.dist-info/licenses/LICENSE,sha256=OXLcl0T2SZ8Pmy2_dmlvKuetivmyPd5m1q-Gyd-zaYY,35149
10
+ dompy_parser-0.2.0.dist-info/METADATA,sha256=nybScS3K_ghGicUqPjSveP7n2VEezGwL3LRtFaUly5s,4803
11
+ dompy_parser-0.2.0.dist-info/WHEEL,sha256=mOdXR9C3wMVov7cSY8PY-XCzo3SmmWCHvGQr5csJoao,91
12
+ dompy_parser-0.2.0.dist-info/top_level.txt,sha256=Bd1Smi1mCGxmM4seqkp8TUb9n0hwHRmhtgP8y1JZN4s,6
13
+ dompy_parser-0.2.0.dist-info/RECORD,,
@@ -0,0 +1,5 @@
1
+ Wheel-Version: 1.0
2
+ Generator: setuptools (84.2.1)
3
+ Root-Is-Purelib: true
4
+ Tag: py3-none-any
5
+