justhtml 0.1.0__tar.gz

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.

Potentially problematic release.

This version of justhtml might be problematic. Click here for more details.

Files changed (30) hide show
  1. justhtml-0.1.0/.github/copilot-instructions.md +82 -0
  2. justhtml-0.1.0/.github/workflows/publish.yml +33 -0
  3. justhtml-0.1.0/.gitignore +174 -0
  4. justhtml-0.1.0/LICENSE +21 -0
  5. justhtml-0.1.0/PKG-INFO +144 -0
  6. justhtml-0.1.0/README.md +122 -0
  7. justhtml-0.1.0/benchmark.py +713 -0
  8. justhtml-0.1.0/fuzz.py +1944 -0
  9. justhtml-0.1.0/profile_real.py +72 -0
  10. justhtml-0.1.0/pyproject.toml +69 -0
  11. justhtml-0.1.0/run_tests.py +1009 -0
  12. justhtml-0.1.0/src/justhtml/__init__.py +3 -0
  13. justhtml-0.1.0/src/justhtml/__main__.py +26 -0
  14. justhtml-0.1.0/src/justhtml/constants.py +453 -0
  15. justhtml-0.1.0/src/justhtml/context.py +6 -0
  16. justhtml-0.1.0/src/justhtml/entities.py +257 -0
  17. justhtml-0.1.0/src/justhtml/parser.py +37 -0
  18. justhtml-0.1.0/src/justhtml/serialize.py +94 -0
  19. justhtml-0.1.0/src/justhtml/tokenizer.py +2516 -0
  20. justhtml-0.1.0/src/justhtml/tokens.py +54 -0
  21. justhtml-0.1.0/src/justhtml/treebuilder.py +3246 -0
  22. justhtml-0.1.0/test-summary.txt +81 -0
  23. justhtml-0.1.0/tests/justhtml-tests/empty_stack_edge_cases.dat +48 -0
  24. justhtml-0.1.0/tests/justhtml-tests/iframe_srcdoc.dat +11 -0
  25. justhtml-0.1.0/tests/justhtml-tests/tokenizer_edge_cases.test +199 -0
  26. justhtml-0.1.0/tests/justhtml-tests/treebuilder_coverage.dat +162 -0
  27. justhtml-0.1.0/tests/justhtml-tests/xml_coercion.dat +45 -0
  28. justhtml-0.1.0/tests/justhtml-tests/xml_coercion_coverage.test +14 -0
  29. justhtml-0.1.0/tests/test_format.py +122 -0
  30. justhtml-0.1.0/watch_tests.sh +11 -0
justhtml-0.1.0/.github/copilot-instructions.md ADDED
@@ -0,0 +1,82 @@
1
+ ## JustHTML – Agent instructions
2
+
3
+ # Decision & Clarification Policy (Overrides)
4
+
5
+ - Replace "propose a follow-up" with "propose **and execute** the best alternative by default; ask only for destructive/irreversible choices."
6
+ - Keep preambles to a single declarative sentence ("I'm scanning the repo and then drafting a minimal fix.") β€” no approval requests.
7
+
8
+ ### Architecture Snapshot
9
+ - Tokenizer (`tokenizer.py`): HTML5 spec state machine (~60 states). Handles RCDATA, RAWTEXT, CDATA, script escaping, comments, DOCTYPE, etc.
10
+ - Tree builder (`treebuilder.py`): Token sink that constructs DOM tree following HTML5 construction rules.
11
+ - Node tree (`node.py`): DOM-like structure. Always use `append_child()` / `insert_before()` for tree operations.
12
+ - Entities (`entities.py`): HTML5 character reference decoding (named & numeric entities).
13
+ - Constants (`constants.py`): HTML5 element categories, void elements, formatting elements, etc.
14
+
15
+ ### Golden Rules
16
+ 1. **Spec compliance first**: Follow WHATWG HTML5 spec exactly. No heuristics, no shortcuts.
17
+ 2. **No exceptions in hot paths**: Use deterministic control flow, not try/except for branching.
18
+ 3. **No reflective probing**: No `hasattr`, `getattr`, or `delattr` - all data structures used are deterministic.
19
+ 4. **Minimal allocations**: Reuse buffers, avoid per-token object creation in tokenizer.
20
+ 5. **No typing annotations**: Keep code clean and fast.
21
+ 6. **Token reuse**: Create new token objects when emitting (don't reuse references).
22
+ 7. **State machine purity**: Tokenizer state transitions follow spec state machine exactly.
23
+ 8. **No test-specific code**: No references to test files in comments or code.
24
+
25
+ ### Testing Workflow
26
+ 1. **Target failures**: Use `--test-specs file:indices` to run specific tests
27
+ ```bash
28
+ python run_tests.py --test-specs test2.test:5,10 -v
29
+ ```
30
+
31
+ 2. **Check test output**: Use `-v` for diffs, `-vv` for debug output
32
+ ```bash
33
+ python run_tests.py --test-specs test3.test -vv
34
+ ```
35
+
36
+ 3. **Run full suite**: Always check for regressions
37
+ ```bash
38
+ python run_tests.py -q # Quick overview
39
+ python run_tests.py --regressions # Check for new failures vs baseline
40
+ ```
41
+
42
+ 4. **Quick iteration**: Test snippet without full suite (full suite runs in ~1s)
43
+ ```bash
44
+ python -c 'from justhtml import JustHTML; print(JustHTML("<html>").root.to_test_format())'
45
+ ```
46
+
47
+ 5. **Benchmark performance**: After changes, verify speed impact
48
+ ```bash
49
+ python benchmark.py --iterations 1 --parser justhtml --no-mem
50
+ ```
51
+
52
+ 6. **Profile hotspots**: For performance optimization
53
+ ```bash
54
+ python profile_real.py # Profiles on web100k dataset
55
+ ```
56
+
57
+ ### Test Runner Flags
58
+ - `--test-specs FILE[:INDICES]`: Run specific test(s), e.g., `test2.test:5,10` or `tests1.dat`
59
+ - `-v, -vv, -vvv`: Verbosity (diffs, debug output, full debug)
60
+ - `-q, --quiet`: Summary only
61
+ - `-x, --fail-fast`: Stop on first failure
62
+ - `--regressions`: Compare against HEAD baseline
63
+ - `--exclude-files`, `--exclude-errors`, `--exclude-html`: Skip tests matching patterns
64
+ - `--filter-errors`, `--filter-html`: Only run tests matching patterns
65
+
66
+ ### Benchmark Flags (benchmark.py)
67
+ - `--iterations 1`: Single run (default: 5 for averaging)
68
+ - `--parser justhtml`: Benchmark only JustHTML (default: all parsers)
69
+ - `--no-mem`: Disable memory profiling (faster)
70
+ - `--limit N`: Test on N files (default: 100)
71
+
72
+ ### Logging & Comments
73
+ - Comments explain **why** (spec rationale), not **what** (code is self-documenting)
74
+ - Cite spec sections when relevant (e.g., "Per Β§13.2.5.72")
75
+ - No historical notes ("Previously", "Fixed", "Changed") - prefer removing old code
76
+ - Debug calls: `self.debug()` / `parser.debug()` - no gating needed
77
+
78
+ ### Performance Mindset
79
+ - Tokenizer is hot path: minimize allocations, avoid string slicing
80
+ - Use `str.find()` for scanning, not regex when possible
81
+ - Reuse buffers: `text_buffer`, `current_tag_name`, etc.
82
+ - Infer state from structure (stacks, tree) instead of storing flags
justhtml-0.1.0/.github/workflows/publish.yml ADDED
@@ -0,0 +1,33 @@
1
+ name: Publish to PyPI
2
+
3
+ on:
4
+ release:
5
+ types: [published]
6
+
7
+ jobs:
8
+ pypi-publish:
9
+ name: Upload release to PyPI
10
+ runs-on: ubuntu-latest
11
+ environment:
12
+ name: pypi
13
+ url: https://pypi.org/p/justhtml
14
+ permissions:
15
+ id-token: write # IMPORTANT: this permission is mandatory for trusted publishing
16
+ contents: read
17
+ steps:
18
+ - name: Checkout
19
+ uses: actions/checkout@v4
20
+
21
+ - name: Set up Python
22
+ uses: actions/setup-python@v5
23
+ with:
24
+ python-version: "3.x"
25
+
26
+ - name: Install build dependencies
27
+ run: python -m pip install build
28
+
29
+ - name: Build package
30
+ run: python -m build
31
+
32
+ - name: Publish package distributions to PyPI
33
+ uses: pypa/gh-action-pypi-publish@release/v1
justhtml-0.1.0/.gitignore ADDED
@@ -0,0 +1,174 @@
1
+ # Byte-compiled / optimized / DLL files
2
+ __pycache__/
3
+ *.py[cod]
4
+ *$py.class
5
+
6
+ # C extensions
7
+ *.so
8
+
9
+ # Distribution / packaging
10
+ .Python
11
+ build/
12
+ develop-eggs/
13
+ dist/
14
+ downloads/
15
+ eggs/
16
+ .eggs/
17
+ lib/
18
+ lib64/
19
+ parts/
20
+ sdist/
21
+ var/
22
+ wheels/
23
+ share/python-wheels/
24
+ *.egg-info/
25
+ .installed.cfg
26
+ *.egg
27
+ MANIFEST
28
+
29
+ # PyInstaller
30
+ # Usually these files are written by a python script from a template
31
+ # before PyInstaller builds the exe, so as to inject date/other infos into it.
32
+ *.manifest
33
+ *.spec
34
+
35
+ # Installer logs
36
+ pip-log.txt
37
+ pip-delete-this-directory.txt
38
+
39
+ # Unit test / coverage reports
40
+ htmlcov/
41
+ .tox/
42
+ .nox/
43
+ .coverage
44
+ .coverage.*
45
+ coverage.json
46
+ .cache
47
+ nosetests.xml
48
+ coverage.xml
49
+ *.cover
50
+ *.py,cover
51
+ .hypothesis/
52
+ .pytest_cache/
53
+ cover/
54
+
55
+ # Translations
56
+ *.mo
57
+ *.pot
58
+
59
+ # Django stuff:
60
+ *.log
61
+ local_settings.py
62
+ db.sqlite3
63
+ db.sqlite3-journal
64
+
65
+ # Flask stuff:
66
+ instance/
67
+ .webassets-cache
68
+
69
+ # Scrapy stuff:
70
+ .scrapy
71
+
72
+ # Sphinx documentation
73
+ docs/_build/
74
+
75
+ # PyBuilder
76
+ .pybuilder/
77
+ target/
78
+
79
+ # Jupyter Notebook
80
+ .ipynb_checkpoints
81
+
82
+ # IPython
83
+ profile_default/
84
+ ipython_config.py
85
+
86
+ # pyenv
87
+ # For a library or package, you might want to ignore these files since the code is
88
+ # intended to run in multiple environments; otherwise, check them in:
89
+ # .python-version
90
+
91
+ # pipenv
92
+ # According to pypa/pipenv#598, it is recommended to include Pipfile.lock in version control.
93
+ # However, in case of collaboration, if having platform-specific dependencies or dependencies
94
+ # having no cross-platform support, pipenv may install dependencies that don't work, or not
95
+ # install all needed dependencies.
96
+ #Pipfile.lock
97
+
98
+ # UV
99
+ # Similar to Pipfile.lock, it is generally recommended to include uv.lock in version control.
100
+ # This is especially recommended for binary packages to ensure reproducibility, and is more
101
+ # commonly ignored for libraries.
102
+ #uv.lock
103
+
104
+ # poetry
105
+ # Similar to Pipfile.lock, it is generally recommended to include poetry.lock in version control.
106
+ # This is especially recommended for binary packages to ensure reproducibility, and is more
107
+ # commonly ignored for libraries.
108
+ # https://python-poetry.org/docs/basic-usage/#commit-your-poetrylock-file-to-version-control
109
+ #poetry.lock
110
+
111
+ # pdm
112
+ # Similar to Pipfile.lock, it is generally recommended to include pdm.lock in version control.
113
+ #pdm.lock
114
+ # pdm stores project-wide configurations in .pdm.toml, but it is recommended to not include it
115
+ # in version control.
116
+ # https://pdm.fming.dev/latest/usage/project/#working-with-version-control
117
+ .pdm.toml
118
+ .pdm-python
119
+ .pdm-build/
120
+
121
+ # PEP 582; used by e.g. github.com/David-OConnor/pyflow and github.com/pdm-project/pdm
122
+ __pypackages__/
123
+
124
+ # Celery stuff
125
+ celerybeat-schedule
126
+ celerybeat.pid
127
+
128
+ # SageMath parsed files
129
+ *.sage.py
130
+
131
+ # Environments
132
+ .env
133
+ .venv
134
+ env/
135
+ venv/
136
+ ENV/
137
+ env.bak/
138
+ venv.bak/
139
+
140
+ # Spyder project settings
141
+ .spyderproject
142
+ .spyproject
143
+
144
+ # Rope project settings
145
+ .ropeproject
146
+
147
+ # mkdocs documentation
148
+ /site
149
+
150
+ # mypy
151
+ .mypy_cache/
152
+ .dmypy.json
153
+ dmypy.json
154
+
155
+ # Pyre type checker
156
+ .pyre/
157
+
158
+ # pytype static type analyzer
159
+ .pytype/
160
+
161
+ # Cython debug symbols
162
+ cython_debug/
163
+
164
+ # PyCharm
165
+ # JetBrains specific template is maintained in a separate JetBrains.gitignore that can
166
+ # be found at https://github.com/github/gitignore/blob/main/Global/JetBrains.gitignore
167
+ # and can be added to the global gitignore or merged into this file. For a more nuclear
168
+ # option (not recommended) you can uncomment the following to ignore the entire idea folder.
169
+ #.idea/
170
+
171
+ # PyPI configuration file
172
+ .pypirc
173
+ .python-version
174
+ tests/html5lib-tests-*
justhtml-0.1.0/LICENSE ADDED
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2025 Emil StenstrΓΆm
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
justhtml-0.1.0/PKG-INFO ADDED
@@ -0,0 +1,144 @@
1
+ Metadata-Version: 2.4
2
+ Name: justhtml
3
+ Version: 0.1.0
4
+ Summary: A pure Python HTML5 parser that just works.
5
+ Project-URL: Homepage, https://github.com/emilstenstrom/justhtml
6
+ Project-URL: Issues, https://github.com/emilstenstrom/justhtml/issues
7
+ Author-email: Emil StenstrΓΆm <emil@emilstenstrom.se>
8
+ License-File: LICENSE
9
+ Classifier: License :: OSI Approved :: MIT License
10
+ Classifier: Operating System :: OS Independent
11
+ Classifier: Programming Language :: Python :: 3
12
+ Requires-Python: >=3.8
13
+ Provides-Extra: benchmark
14
+ Requires-Dist: beautifulsoup4; extra == 'benchmark'
15
+ Requires-Dist: html5-parser; extra == 'benchmark'
16
+ Requires-Dist: html5lib; extra == 'benchmark'
17
+ Requires-Dist: lxml; extra == 'benchmark'
18
+ Requires-Dist: psutil; extra == 'benchmark'
19
+ Requires-Dist: selectolax; extra == 'benchmark'
20
+ Requires-Dist: zstandard; extra == 'benchmark'
21
+ Description-Content-Type: text/markdown
22
+
23
+ # JustHTML
24
+
25
+ JustHTML is a pure Python HTML5 parser that just works. It parses HTML and returns a DOM tree that you can traverse and manipulate.
26
+
27
+ ## Why JustHTML?
28
+
29
+ ### 1. βœ… Correctness: 100% Spec Compliant
30
+ JustHTML is built to be **correct**. It implements the official WHATWG HTML5 specification exactly (tree builder and tokenizer), including all the complex error-handling rules that browsers use.
31
+
32
+ - **Verified Compliance**: Passes all 8,500+ tests in the official `html5lib-tests` suite (used by browser vendors) (see /tests/).
33
+ - **100% Coverage**: Every single line and branch of code is covered by integration tests.
34
+ - **Fuzz Tested**: Has parsed 3 million randomized broken HTML documents to ensure it never crashes or hangs (see fuzz.py).
35
+ - **Living Standard**: It tracks the living standard, not a snapshot from 2012.
36
+
37
+ ### 2. 🐍 Pure Python with zero dependencies
38
+ JustHTML has **zero dependencies**. It's pure Python.
39
+
40
+ - **Easy Installation**: No C extensions to compile, no system libraries (like libxml2) required. Works on PyPy, WASM (Pyodide), and anywhere Python runs.
41
+ - **No dependency upgrade hassle**: Some libraries depend on a large set of libraries, all which require upgrades to avoid security issues.
42
+ - **Debuggable**: It's just Python code. You can step through it with a debugger to understand exactly how your HTML is being parsed.
43
+ - **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.
44
+
45
+ ### 3. ⚑ Fast enoughβ„’ Performance
46
+
47
+ If you need to parse terabytes of data, use a C or Rust parser (like `html5ever`). They are 10x-20x faster (see benchmarks.py).
48
+
49
+ 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`.
50
+
51
+ ### Comparison to other parsers
52
+
53
+ | Parser | Spec Compliant? | Pure Python? | Speed | Notes |
54
+ |--------|:---------------:|:------------:|-------|-------|
55
+ | **JustHTML** | βœ… Yes | βœ… Yes | ⚑ Fast | The sweet spot. Correct, easy to install, and fast enough. |
56
+ | `html.parser` | ❌ No | βœ… Yes | ⚑ Fast | Standard library. Chokes on malformed HTML. |
57
+ | `lxml` | ❌ No | ❌ No | πŸš€ Very Fast | C-based. Fast but not spec-compliant (different output than browsers). |
58
+ | `html5lib` | βœ… Yes | βœ… Yes | 🐒 Slow | The reference implementation. Very correct but very slow. |
59
+ | `BeautifulSoup` | N/A | N/A | 🐒 Slow | Wrapper around other parsers. Slower and more memory hungry than the underlying parser. |
60
+ | `gumbo` / `html5ever` | βœ… Yes | ❌ No | πŸš€ Very Fast | C/Rust based. Fast and correct, but requires compiling extensions. |
61
+
62
+ ## Installation
63
+
64
+ ```bash
65
+ pip install justhtml
66
+ ```
67
+
68
+ ## Example usage
69
+
70
+ ### Python API
71
+
72
+ ```python
73
+ from justhtml import JustHTML
74
+
75
+ html = "<html><body><div id='main'><p>Hello, <b>world</b>!</p></div></body></html>"
76
+ doc = JustHTML(html)
77
+
78
+ # 1. Traverse the tree
79
+ # The tree is made of SimpleDomNode objects.
80
+ # Each node has .name, .attrs, .children, and .parent
81
+ root = doc.root # #document
82
+ html_node = root.children[0] # html
83
+ body = html_node.children[1] # body (children[0] is head)
84
+ div = body.children[0] # div
85
+
86
+ print(f"Tag: {div.name}")
87
+ print(f"Attributes: {div.attrs}")
88
+
89
+ # 2. Pretty-print HTML
90
+ # You can serialize any node back to HTML
91
+ print(div.to_html())
92
+ # Output:
93
+ # <div id="main">
94
+ # <p>
95
+ # Hello,
96
+ # <b>world</b>
97
+ # !
98
+ # </p>
99
+ # </div>
100
+ ```
101
+
102
+ ### Command Line Interface
103
+
104
+ You can also use JustHTML from the command line to pretty-print HTML files:
105
+
106
+ ```bash
107
+ # Parse a file
108
+ python -m justhtml index.html
109
+
110
+ # Parse from stdin (great for piping)
111
+ curl -s https://example.com | python -m justhtml -
112
+ ```
113
+
114
+ ## Develop locally and run the tests
115
+
116
+ 1. Clone the repository:
117
+ ```bash
118
+ git clone git@github.com:EmilStenstrom/justhtml.git
119
+ cd justhtml
120
+ ```
121
+
122
+ 2. Install the library locally (there's no dependencies!):
123
+ ```bash
124
+ pip install -e .
125
+ ```
126
+
127
+ 3. Run the tests:
128
+ ```bash
129
+ python run_tests.py
130
+ ```
131
+
132
+ For verbose output showing diffs on failures:
133
+ ```bash
134
+ python run_tests.py -v
135
+ ```
136
+
137
+ 4. Run the benchmarks:
138
+ ```bash
139
+ python benchmark.py
140
+ ```
141
+
142
+ ## License
143
+
144
+ MIT. Free to use for commercial and non-commercial use.
justhtml-0.1.0/README.md ADDED
@@ -0,0 +1,122 @@
1
+ # JustHTML
2
+
3
+ JustHTML is a pure Python HTML5 parser that just works. It parses HTML and returns a DOM tree that you can traverse and manipulate.
4
+
5
+ ## Why JustHTML?
6
+
7
+ ### 1. βœ… Correctness: 100% Spec Compliant
8
+ JustHTML is built to be **correct**. It implements the official WHATWG HTML5 specification exactly (tree builder and tokenizer), including all the complex error-handling rules that browsers use.
9
+
10
+ - **Verified Compliance**: Passes all 8,500+ tests in the official `html5lib-tests` suite (used by browser vendors) (see /tests/).
11
+ - **100% Coverage**: Every single line and branch of code is covered by integration tests.
12
+ - **Fuzz Tested**: Has parsed 3 million randomized broken HTML documents to ensure it never crashes or hangs (see fuzz.py).
13
+ - **Living Standard**: It tracks the living standard, not a snapshot from 2012.
14
+
15
+ ### 2. 🐍 Pure Python with zero dependencies
16
+ JustHTML has **zero dependencies**. It's pure Python.
17
+
18
+ - **Easy Installation**: No C extensions to compile, no system libraries (like libxml2) required. Works on PyPy, WASM (Pyodide), and anywhere Python runs.
19
+ - **No dependency upgrade hassle**: Some libraries depend on a large set of libraries, all which require upgrades to avoid security issues.
20
+ - **Debuggable**: It's just Python code. You can step through it with a debugger to understand exactly how your HTML is being parsed.
21
+ - **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.
22
+
23
+ ### 3. ⚑ Fast enoughβ„’ Performance
24
+
25
+ If you need to parse terabytes of data, use a C or Rust parser (like `html5ever`). They are 10x-20x faster (see benchmarks.py).
26
+
27
+ 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`.
28
+
29
+ ### Comparison to other parsers
30
+
31
+ | Parser | Spec Compliant? | Pure Python? | Speed | Notes |
32
+ |--------|:---------------:|:------------:|-------|-------|
33
+ | **JustHTML** | βœ… Yes | βœ… Yes | ⚑ Fast | The sweet spot. Correct, easy to install, and fast enough. |
34
+ | `html.parser` | ❌ No | βœ… Yes | ⚑ Fast | Standard library. Chokes on malformed HTML. |
35
+ | `lxml` | ❌ No | ❌ No | πŸš€ Very Fast | C-based. Fast but not spec-compliant (different output than browsers). |
36
+ | `html5lib` | βœ… Yes | βœ… Yes | 🐒 Slow | The reference implementation. Very correct but very slow. |
37
+ | `BeautifulSoup` | N/A | N/A | 🐒 Slow | Wrapper around other parsers. Slower and more memory hungry than the underlying parser. |
38
+ | `gumbo` / `html5ever` | βœ… Yes | ❌ No | πŸš€ Very Fast | C/Rust based. Fast and correct, but requires compiling extensions. |
39
+
40
+ ## Installation
41
+
42
+ ```bash
43
+ pip install justhtml
44
+ ```
45
+
46
+ ## Example usage
47
+
48
+ ### Python API
49
+
50
+ ```python
51
+ from justhtml import JustHTML
52
+
53
+ html = "<html><body><div id='main'><p>Hello, <b>world</b>!</p></div></body></html>"
54
+ doc = JustHTML(html)
55
+
56
+ # 1. Traverse the tree
57
+ # The tree is made of SimpleDomNode objects.
58
+ # Each node has .name, .attrs, .children, and .parent
59
+ root = doc.root # #document
60
+ html_node = root.children[0] # html
61
+ body = html_node.children[1] # body (children[0] is head)
62
+ div = body.children[0] # div
63
+
64
+ print(f"Tag: {div.name}")
65
+ print(f"Attributes: {div.attrs}")
66
+
67
+ # 2. Pretty-print HTML
68
+ # You can serialize any node back to HTML
69
+ print(div.to_html())
70
+ # Output:
71
+ # <div id="main">
72
+ # <p>
73
+ # Hello,
74
+ # <b>world</b>
75
+ # !
76
+ # </p>
77
+ # </div>
78
+ ```
79
+
80
+ ### Command Line Interface
81
+
82
+ You can also use JustHTML from the command line to pretty-print HTML files:
83
+
84
+ ```bash
85
+ # Parse a file
86
+ python -m justhtml index.html
87
+
88
+ # Parse from stdin (great for piping)
89
+ curl -s https://example.com | python -m justhtml -
90
+ ```
91
+
92
+ ## Develop locally and run the tests
93
+
94
+ 1. Clone the repository:
95
+ ```bash
96
+ git clone git@github.com:EmilStenstrom/justhtml.git
97
+ cd justhtml
98
+ ```
99
+
100
+ 2. Install the library locally (there's no dependencies!):
101
+ ```bash
102
+ pip install -e .
103
+ ```
104
+
105
+ 3. Run the tests:
106
+ ```bash
107
+ python run_tests.py
108
+ ```
109
+
110
+ For verbose output showing diffs on failures:
111
+ ```bash
112
+ python run_tests.py -v
113
+ ```
114
+
115
+ 4. Run the benchmarks:
116
+ ```bash
117
+ python benchmark.py
118
+ ```
119
+
120
+ ## License
121
+
122
+ MIT. Free to use for commercial and non-commercial use.