justhtml 0.6.0__py3-none-any.whl

justhtml/treebuilder_utils.py

@@ -0,0 +1,86 @@
+import enum
+
+from .constants import (
+    HTML4_PUBLIC_PREFIXES,
+    LIMITED_QUIRKY_PUBLIC_PREFIXES,
+    QUIRKY_PUBLIC_MATCHES,
+    QUIRKY_PUBLIC_PREFIXES,
+    QUIRKY_SYSTEM_MATCHES,
+)
+
+
+class InsertionMode(enum.IntEnum):
+    INITIAL = 0
+    BEFORE_HTML = 1
+    BEFORE_HEAD = 2
+    IN_HEAD = 3
+    IN_HEAD_NOSCRIPT = 4
+    AFTER_HEAD = 5
+    TEXT = 6
+    IN_BODY = 7
+    AFTER_BODY = 8
+    AFTER_AFTER_BODY = 9
+    IN_TABLE = 10
+    IN_TABLE_TEXT = 11
+    IN_CAPTION = 12
+    IN_COLUMN_GROUP = 13
+    IN_TABLE_BODY = 14
+    IN_ROW = 15
+    IN_CELL = 16
+    IN_FRAMESET = 17
+    AFTER_FRAMESET = 18
+    AFTER_AFTER_FRAMESET = 19
+    IN_SELECT = 20
+    IN_TEMPLATE = 21
+
+
+def is_all_whitespace(text):
+    return text.strip("\t\n\f\r ") == ""
+
+
+def contains_prefix(haystack, needle):
+    return any(needle.startswith(prefix) for prefix in haystack)
+
+
+def doctype_error_and_quirks(doctype, iframe_srcdoc=False):
+    name = doctype.name.lower() if doctype.name else None
+    public_id = doctype.public_id
+    system_id = doctype.system_id
+
+    acceptable = (
+        ("html", None, None),
+        ("html", None, "about:legacy-compat"),
+        ("html", "-//W3C//DTD HTML 4.0//EN", None),
+        ("html", "-//W3C//DTD HTML 4.0//EN", "http://www.w3.org/TR/REC-html40/strict.dtd"),
+        ("html", "-//W3C//DTD HTML 4.01//EN", None),
+        ("html", "-//W3C//DTD HTML 4.01//EN", "http://www.w3.org/TR/html4/strict.dtd"),
+        ("html", "-//W3C//DTD XHTML 1.0 Strict//EN", "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd"),
+        ("html", "-//W3C//DTD XHTML 1.1//EN", "http://www.w3.org/TR/xhtml11/DTD/xhtml11.dtd"),
+    )
+
+    key = (name, public_id, system_id)
+    parse_error = key not in acceptable
+
+    public_lower = public_id.lower() if public_id else None
+    system_lower = system_id.lower() if system_id else None
+
+    if doctype.force_quirks:
+        quirks_mode = "quirks"
+    elif iframe_srcdoc:
+        quirks_mode = "no-quirks"
+    elif name != "html":
+        quirks_mode = "quirks"
+    elif public_lower in QUIRKY_PUBLIC_MATCHES:
+        quirks_mode = "quirks"
+    elif system_lower in QUIRKY_SYSTEM_MATCHES:
+        quirks_mode = "quirks"
+    elif public_lower and contains_prefix(QUIRKY_PUBLIC_PREFIXES, public_lower):
+        quirks_mode = "quirks"
+    elif public_lower and contains_prefix(LIMITED_QUIRKY_PUBLIC_PREFIXES, public_lower):
+        quirks_mode = "limited-quirks"
+    elif public_lower and contains_prefix(HTML4_PUBLIC_PREFIXES, public_lower):
+        quirks_mode = "quirks" if system_lower is None else "limited-quirks"
+    else:
+        quirks_mode = "no-quirks"
+
+    return parse_error, quirks_mode

justhtml-0.6.0.dist-info/METADATA

@@ -0,0 +1,126 @@
+Metadata-Version: 2.4
+Name: justhtml
+Version: 0.6.0
+Summary: A pure Python HTML5 parser that just works.
+Project-URL: Homepage, https://github.com/emilstenstrom/justhtml
+Project-URL: Issues, https://github.com/emilstenstrom/justhtml/issues
+Author-email: Emil Stenström <emil@emilstenstrom.se>
+License-File: LICENSE
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Requires-Python: >=3.10
+Provides-Extra: benchmark
+Requires-Dist: beautifulsoup4; extra == 'benchmark'
+Requires-Dist: html5-parser; extra == 'benchmark'
+Requires-Dist: html5lib; extra == 'benchmark'
+Requires-Dist: lxml; extra == 'benchmark'
+Requires-Dist: psutil; extra == 'benchmark'
+Requires-Dist: selectolax; extra == 'benchmark'
+Requires-Dist: zstandard; extra == 'benchmark'
+Provides-Extra: dev
+Requires-Dist: build; extra == 'dev'
+Requires-Dist: coverage; extra == 'dev'
+Requires-Dist: pre-commit; extra == 'dev'
+Requires-Dist: ruff==0.14.7; extra == 'dev'
+Requires-Dist: twine; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# JustHTML
+
+A pure Python HTML5 parser that just works. No C extensions to compile. No system dependencies to install. No complex API to learn.
+
+**[📖 Read the full documentation here](docs/index.md)**
+
+## Why use JustHTML?
+
+### 1. Just... Correct ✅
+It implements the official WHATWG HTML5 specification exactly. If a browser can parse it, JustHTML can parse it. It handles all the complex error-handling rules that browsers use.
+
+- **Verified Compliance**: Passes all 8,500+ tests in the official [html5lib-tests](https://github.com/html5lib/html5lib-tests) suite (used by browser vendors).
+- **100% Coverage**: Every line and branch of code is covered by integration tests.
+- **Fuzz Tested**: Has parsed 3 million randomized broken HTML documents to ensure it never crashes or hangs (see benchmarks/fuzz.py).
+- **Living Standard**: It tracks the living standard, not a snapshot from 2012.
+
+### 2. Just... Python 🐍
+JustHTML has **zero dependencies**. It's pure Python.
+
+- **Just Install**: No C extensions to compile, no system libraries (like libxml2) required. Works on PyPy, WASM (Pyodide) (yes, it's in the test matrix), and anywhere Python runs.
+- **No dependency upgrade hassle**: Some libraries depend on a large set of libraries, all which require upgrades to avoid security issues.
+- **Debuggable**: It's just Python code. You can step through it with a debugger to understand exactly how your HTML is being parsed.
+- **Returns plain python objects**: Other parsers return lxml or etree trees which means you have another API to learn. JustHTML returns a set of nested objects you can iterate over. Simple.
+
+### 3. Just... Query 🔍
+Find elements with CSS selectors. Just one method to learn - `query()` - and it uses CSS syntax you already know.
+
+```python
+doc.query("div.container > p.intro")  # Familiar CSS syntax
+doc.query("#main, .sidebar")          # Selector groups
+doc.query("li:nth-child(2n+1)")       # Pseudo-classes
+```
+
+### 4. Just... Fast Enough ⚡
+
+If you need to parse terabytes of data, use a C or Rust parser (like `html5ever`). They are 10x-20x faster.
+
+But for most use cases, JustHTML is **fast enough**. It parses the Wikipedia homepage in ~0.1s. It is the fastest pure-Python HTML5 parser available, outperforming `html5lib` and `BeautifulSoup`.
+
+## Comparison to other parsers
+
+| Parser | HTML5 Compliance | Pure Python? | Speed | Query API | Notes |
+|--------|:----------------:|:------------:|-------|-----------|-------|
+| **JustHTML** | ✅ **100%** | ✅ Yes | ⚡ Fast | ✅ CSS selectors | It just works. Correct, easy to install, and fast enough. |
+| `html5lib` | 🟡 88% | ✅ Yes | 🐢 Slow | ❌ None | The reference implementation. Very correct but quite slow. |
+| `html5_parser` | 🟡 84% | ❌ No | 🚀 Very Fast | 🟡 XPath (lxml) | C-based (Gumbo). Fast and mostly correct. |
+| `selectolax` | 🟡 68% | ❌ No | 🚀 Very Fast | ✅ CSS selectors | C-based (Lexbor). Very fast but less compliant. |
+| `BeautifulSoup` | 🔴 4% | ✅ Yes | 🐢 Slow | 🟡 Custom API | Wrapper around `html.parser`. Not spec compliant. |
+| `html.parser` | 🔴 4% | ✅ Yes | ⚡ Fast | ❌ None | Standard library. Chokes on malformed HTML. |
+| `lxml` | 🔴 1% | ❌ No | 🚀 Very Fast | 🟡 XPath | C-based (libxml2). Fast but not HTML5 compliant. |
+
+*Compliance scores from running the [html5lib-tests](https://github.com/html5lib/html5lib-tests) suite (1,743 tree-construction tests). See `benchmarks/correctness.py`.*
+
+## Installation
+
+Requires Python 3.10 or later.
+
+```bash
+pip install justhtml
+```
+
+## Quick Example
+
+```python
+from justhtml import JustHTML
+
+doc = JustHTML("<html><body><p class='intro'>Hello!</p></body></html>")
+
+# Query with CSS selectors
+for p in doc.query("p.intro"):
+    print(p.name)        # "p"
+    print(p.attrs)       # {"class": "intro"}
+    print(p.to_html())   # <p class="intro">Hello!</p>
+```
+
+See the **[Quickstart Guide](docs/quickstart.md)** for more examples including tree traversal, streaming, and strict mode.
+
+## Command Line
+
+```bash
+# Pretty-print an HTML file
+python -m justhtml index.html
+
+# Parse from stdin
+curl -s https://example.com | python -m justhtml -
+```
+
+## Contributing
+
+See [CONTRIBUTING.md](CONTRIBUTING.md) for development setup and guidelines.
+
+## Acknowledgments
+
+JustHTML started as a Python port of [html5ever](https://github.com/servo/html5ever), the HTML5 parser from Mozilla's Servo browser engine. While the codebase has since evolved significantly, html5ever's clean architecture and spec-compliant approach were invaluable as a starting point. Thank you to the Servo team for their excellent work.
+
+## License
+
+MIT. Free to use both for commercial and non-commercial use.

justhtml-0.6.0.dist-info/RECORD

@@ -0,0 +1,20 @@
+justhtml/__init__.py,sha256=rsc4X1uTsJziqKtZxWQsIqwuC5DI0cvfYw5q_FtEOCo,375
+justhtml/__main__.py,sha256=VEaIacoiUvKNXA1HxePLsKaSEP44x7fCdTFJ8wKwnG4,577
+justhtml/constants.py,sha256=gmQ2Jtujtj06oivuJ_K_JyqFWRNWsaT-izvPTuA5B2U,11526
+justhtml/context.py,sha256=tiR5UKj1VUuq5_1W_CRAVGl06QNlh_ecy4GejG58IFo,184
+justhtml/entities.py,sha256=g26GxmmS7BHhogkskzTlSIihKrutlMu_SX1EdE2yvJY,9644
+justhtml/errors.py,sha256=_ITld5kWoedZPZ7sPqogJwSVW6d_pdXSmkEMhZlUMVg,9942
+justhtml/node.py,sha256=_QmkO4UveAu_PtbxX4TIPxsF6zo5aOwXD34yqqr64YQ,6026
+justhtml/parser.py,sha256=W1CduxrWYUgoS-HgJOwRdAar_hsV9NvtMbP76hDO4Sk,3110
+justhtml/selector.py,sha256=E7ZOBiVHWdmSDQG64-c2SOzDtmMOijlN8tIisZWChs4,30896
+justhtml/serialize.py,sha256=GSmevQjm2GIECYgcUCx7Ki0LrtNaV4l8p9DgD_Jdv_Y,6489
+justhtml/stream.py,sha256=jB5cNNS4J2463E9aAvpKfaZwv8wmzghrrvjoMsSUMGY,2764
+justhtml/tokenizer.py,sha256=1q7vXaJ1_Wf48b3Mc23WC3-2KfDlmXRk1iBFwDMKqCs,97728
+justhtml/tokens.py,sha256=gqoMAFlti-P0mhuHORwDsiWYi3VTHCdLexlUGY6At3E,5872
+justhtml/treebuilder.py,sha256=WFriVhIPngpUcg4zQcmXztkl74jjkbr-7renrcLRiqI,52365
+justhtml/treebuilder_modes.py,sha256=H1TRl6qTEk-N5IzbSH-ExZcp_MlH2O_LBrzcWa30Z8k,93009
+justhtml/treebuilder_utils.py,sha256=O-uGSNhz2M1oxTMu3I8rPtVaZlU1zc9veqbMbioiqmk,2636
+justhtml-0.6.0.dist-info/METADATA,sha256=Xk0gTzxQCaIpaXaBlW2ZlWZVjOYIN9rfxAM7vLyvnNE,5802
+justhtml-0.6.0.dist-info/WHEEL,sha256=WLgqFyCfm_KASv4WHyYy0P3pM_m7J5L9k2skdKLirC8,87
+justhtml-0.6.0.dist-info/licenses/LICENSE,sha256=jM1KAJ1VQZAo7SCGVK1jtVj11zgIc5_BxZAUhXq01V8,1072
+justhtml-0.6.0.dist-info/RECORD,,

justhtml-0.6.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.28.0
+Root-Is-Purelib: true
+Tag: py3-none-any

justhtml-0.6.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Emil Stenström
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.