justhtml 0.12.0__py3-none-any.whl

justhtml/treebuilder_utils.py

@@ -0,0 +1,93 @@
+from __future__ import annotations
+
+import enum
+from typing import TYPE_CHECKING
+
+from .constants import (
+    HTML4_PUBLIC_PREFIXES,
+    LIMITED_QUIRKY_PUBLIC_PREFIXES,
+    QUIRKY_PUBLIC_MATCHES,
+    QUIRKY_PUBLIC_PREFIXES,
+    QUIRKY_SYSTEM_MATCHES,
+)
+
+if TYPE_CHECKING:
+    from .tokens import Doctype
+
+
+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: str) -> bool:
+    return text.strip("\t\n\f\r ") == ""
+
+
+def contains_prefix(haystack: tuple[str, ...], needle: str) -> bool:
+    return any(needle.startswith(prefix) for prefix in haystack)
+
+
+def doctype_error_and_quirks(doctype: Doctype, iframe_srcdoc: bool = False) -> tuple[bool, str]:
+    name = doctype.name.lower() if doctype.name else None
+    public_id = doctype.public_id
+    system_id = doctype.system_id
+
+    acceptable: tuple[tuple[str | None, str | None, str | None], ...] = (
+        ("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
+
+    quirks_mode: str
+    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.12.0.dist-info/METADATA

@@ -0,0 +1,164 @@
+Metadata-Version: 2.4
+Name: justhtml
+Version: 0.12.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: mypy>=1.0; (platform_python_implementation != 'PyPy') and 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 9k+ 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 6 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
+
+If you installed JustHTML (for example with `pip install justhtml` or `pip install -e .`), you can use the `justhtml` command.
+If you don't have it available, use the equivalent `python -m justhtml ...` form instead.
+
+```bash
+# Pretty-print an HTML file
+justhtml index.html
+
+# Parse from stdin
+curl -s https://example.com | justhtml -
+
+# Select nodes and output text
+justhtml index.html --selector "main p" --format text
+
+# Select nodes and output Markdown (subset of GFM)
+justhtml index.html --selector "article" --format markdown
+
+# Select nodes and output HTML
+justhtml index.html --selector "a" --format html
+```
+
+```bash
+# Example: extract Markdown from GitHub README HTML
+curl -s https://github.com/EmilStenstrom/justhtml/ | justhtml - --selector '.markdown-body' --format markdown | head -n 15
+```
+
+Output:
+
+```text
+# JustHTML
+
+[](#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](/EmilStenstrom/justhtml/blob/main/docs/index.md)**
+
+## Why use JustHTML?
+
+[](#why-use-justhtml)
+
+### 1. Just... Correct ✅
+
+[](#1-just-correct-)
+```
+
+## 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.12.0.dist-info/RECORD

@@ -0,0 +1,23 @@
+justhtml/__init__.py,sha256=rsc4X1uTsJziqKtZxWQsIqwuC5DI0cvfYw5q_FtEOCo,375
+justhtml/__main__.py,sha256=o-ur6qdyt8EmYDKjCP3waHjuvmD38j6mpAx-CJZtAXs,3876
+justhtml/constants.py,sha256=-UATvXXQ7ueFWxJHW79c2eMmMWaSKoqwwcNIGesTAj0,11603
+justhtml/context.py,sha256=Ac4mV-a3ZgJILQbstFu-EB6bRA5oYlSkHqpTxMlMfk0,293
+justhtml/encoding.py,sha256=9mscoXtBb57zehG_BxzN6aTTJHaNfywk5gwxrnH92K8,11310
+justhtml/entities.py,sha256=qLijZDS2n6Cc8UqbVZYNv2XzKVahysFBlAbyHkerD7c,9808
+justhtml/errors.py,sha256=kt8uA9pH43PEiL2ccrV6zJMXK5iZvbtDtIhIWIzS8FU,10004
+justhtml/node.py,sha256=NEDQzD7VBuch-BIZixNIUyZNCHydnThF_eSwXeA5OuA,19056
+justhtml/parser.py,sha256=S_mbXd3YcNGJSZYR_34wkI1mW6SZNQw5d0_LOtjHCRM,4628
+justhtml/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+justhtml/selector.py,sha256=_L9XmJTVJVuAZF12B_nex9iytR4a_xlkIePwUVVvHUk,32884
+justhtml/serialize.py,sha256=Cezl3KVy9RT4sPFr6QJmtWiVjwAvwZSuBoRUP-E3yKM,8606
+justhtml/stream.py,sha256=n8pKtVAivG0VerCWEcXSEBwzj8Tm1ltEAL7F46RGUVM,3431
+justhtml/tokenizer.py,sha256=auDP8svHMlB0PxohVcq3VxhN3WjXUs2A8ckHN78SjKc,100623
+justhtml/tokens.py,sha256=WNGpQ6nHQECY7J8jBvs3XAP2Lxy_xExxRMlqBn_MexI,6836
+justhtml/treebuilder.py,sha256=Mjhyp3Ral5ACCGDi4GL-clHeg65TUrQdoiW2ZunZqNY,55606
+justhtml/treebuilder_modes.py,sha256=VVAbHWbLq1DP3KxNYQa2m2DjJ5jEVxBufV7eSTE_gfA,94040
+justhtml/treebuilder_utils.py,sha256=LjK9tg9sNYR-sJdXKemJCzzzgh6lQW1KBqyvhpWtaoQ,2912
+justhtml-0.12.0.dist-info/METADATA,sha256=8Ex7MpHIhbJaGJvyOvIkEvMBS48K4z4zTlm7_nRTPkk,6922
+justhtml-0.12.0.dist-info/WHEEL,sha256=WLgqFyCfm_KASv4WHyYy0P3pM_m7J5L9k2skdKLirC8,87
+justhtml-0.12.0.dist-info/entry_points.txt,sha256=UN06mPn7J0cBM1dqyf245FvmU9mF3ivgplSr5ppdp6g,52
+justhtml-0.12.0.dist-info/licenses/LICENSE,sha256=jM1KAJ1VQZAo7SCGVK1jtVj11zgIc5_BxZAUhXq01V8,1072
+justhtml-0.12.0.dist-info/RECORD,,

justhtml-0.12.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.12.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+justhtml = justhtml.__main__:main

justhtml-0.12.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.