fasthtmlparser 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.
@@ -0,0 +1,9 @@
1
+ # Sources with LF everywhere.
2
+ *.rs text eol=lf
3
+ *.toml text eol=lf
4
+ *.py text eol=lf
5
+ *.pyi text eol=lf
6
+
7
+ # Test pages and the expected .NET output are compared byte for byte (positions are byte offsets):
8
+ # git must never convert their line endings.
9
+ testdata/** -text linguist-vendored
@@ -0,0 +1,117 @@
1
+ name: CI
2
+
3
+ on:
4
+ push:
5
+ branches: [main]
6
+ tags: ["v*"]
7
+ pull_request:
8
+
9
+ permissions:
10
+ contents: read
11
+
12
+ jobs:
13
+ test:
14
+ runs-on: ${{ matrix.os }}
15
+ strategy:
16
+ matrix:
17
+ os: [ubuntu-latest, windows-latest, macos-latest]
18
+ python: ["3.10", "3.14"]
19
+ steps:
20
+ - uses: actions/checkout@v4
21
+ - uses: actions/setup-python@v5
22
+ with:
23
+ python-version: ${{ matrix.python }}
24
+ - uses: dtolnay/rust-toolchain@stable
25
+ - name: Build and test
26
+ shell: bash
27
+ run: |
28
+ python -m venv .venv
29
+ if [ -f .venv/bin/activate ]; then . .venv/bin/activate; else . .venv/Scripts/activate; fi
30
+ pip install maturin pytest
31
+ maturin develop --release
32
+ pytest -q
33
+
34
+ lint:
35
+ runs-on: ubuntu-latest
36
+ steps:
37
+ - uses: actions/checkout@v4
38
+ - uses: dtolnay/rust-toolchain@stable
39
+ with:
40
+ components: clippy, rustfmt
41
+ - run: cargo fmt --check
42
+ - run: cargo clippy -- -D warnings
43
+
44
+ # Every library of the benchmark must extract the same records.
45
+ bench:
46
+ runs-on: ubuntu-latest
47
+ steps:
48
+ - uses: actions/checkout@v4
49
+ - uses: actions/setup-python@v5
50
+ with:
51
+ python-version: "3.14"
52
+ - uses: dtolnay/rust-toolchain@stable
53
+ - run: |
54
+ python -m venv .venv && . .venv/bin/activate
55
+ pip install maturin selectolax lxml parsel beautifulsoup4
56
+ maturin develop --release
57
+ python bench/bench.py --check
58
+
59
+ # abi3 wheels (one per platform for Python 3.10+) and the sdist.
60
+ wheels:
61
+ needs: [test, lint]
62
+ runs-on: ${{ matrix.os }}
63
+ strategy:
64
+ matrix:
65
+ include:
66
+ - { os: ubuntu-latest, target: x86_64, manylinux: auto }
67
+ - { os: ubuntu-latest, target: aarch64, manylinux: auto }
68
+ - { os: ubuntu-latest, target: x86_64, manylinux: musllinux_1_2 }
69
+ - { os: ubuntu-latest, target: aarch64, manylinux: musllinux_1_2 }
70
+ - { os: windows-latest, target: x64 }
71
+ - { os: windows-11-arm, target: aarch64 }
72
+ - { os: macos-latest, target: aarch64 }
73
+ - { os: macos-15-intel, target: x86_64 }
74
+ steps:
75
+ - uses: actions/checkout@v4
76
+ - uses: actions/setup-python@v5
77
+ with:
78
+ python-version: "3.14"
79
+ - uses: PyO3/maturin-action@v1
80
+ with:
81
+ target: ${{ matrix.target }}
82
+ manylinux: ${{ matrix.manylinux }}
83
+ args: --release --out dist
84
+ - uses: actions/upload-artifact@v4
85
+ with:
86
+ name: wheels-${{ matrix.os }}-${{ matrix.target }}-${{ matrix.manylinux }}
87
+ path: dist
88
+
89
+ sdist:
90
+ needs: [test, lint]
91
+ runs-on: ubuntu-latest
92
+ steps:
93
+ - uses: actions/checkout@v4
94
+ - uses: PyO3/maturin-action@v1
95
+ with:
96
+ command: sdist
97
+ args: --out dist
98
+ - uses: actions/upload-artifact@v4
99
+ with:
100
+ name: sdist
101
+ path: dist
102
+
103
+ # A version tag (v0.1.0) publishes to PyPI with trusted publishing: no token is stored in the repository.
104
+ # PyPI must list this repository, this workflow (ci.yml) and the environment "pypi" as a trusted publisher.
105
+ publish:
106
+ if: startsWith(github.ref, 'refs/tags/v')
107
+ needs: [wheels, sdist, bench]
108
+ runs-on: ubuntu-latest
109
+ environment: pypi
110
+ permissions:
111
+ id-token: write
112
+ steps:
113
+ - uses: actions/download-artifact@v4
114
+ with:
115
+ path: dist
116
+ merge-multiple: true
117
+ - uses: pypa/gh-action-pypi-publish@release/v1
@@ -0,0 +1,6 @@
1
+ /target
2
+ /.venv
3
+ __pycache__/
4
+ *.pyd
5
+ *.so
6
+ /dist
@@ -0,0 +1,148 @@
1
+ # This file is automatically @generated by Cargo.
2
+ # It is not intended for manual editing.
3
+ version = 4
4
+
5
+ [[package]]
6
+ name = "fasthtmlparser"
7
+ version = "0.1.0"
8
+ source = "registry+https://github.com/rust-lang/crates.io-index"
9
+ checksum = "7d35fd1e20a7a369d46059753584f38a6605ce7af65edab5babd6251ad2dbfed"
10
+ dependencies = [
11
+ "memchr",
12
+ ]
13
+
14
+ [[package]]
15
+ name = "fasthtmlparser-py"
16
+ version = "0.1.0"
17
+ dependencies = [
18
+ "fasthtmlparser",
19
+ "pyo3",
20
+ ]
21
+
22
+ [[package]]
23
+ name = "heck"
24
+ version = "0.5.0"
25
+ source = "registry+https://github.com/rust-lang/crates.io-index"
26
+ checksum = "2304e00983f87ffb38b55b444b5e3b60a884b5d30c0fca7d82fe33449bbe55ea"
27
+
28
+ [[package]]
29
+ name = "libc"
30
+ version = "0.2.191"
31
+ source = "registry+https://github.com/rust-lang/crates.io-index"
32
+ checksum = "65cd87c9a6d60536580b316ad985726104730a5151c99845f2490428ef91240a"
33
+
34
+ [[package]]
35
+ name = "memchr"
36
+ version = "2.8.3"
37
+ source = "registry+https://github.com/rust-lang/crates.io-index"
38
+ checksum = "cf8baf1c55e62ffcace7a9f06f4bd9cd3f0c4beb022d3b367256b91b87513d98"
39
+
40
+ [[package]]
41
+ name = "once_cell"
42
+ version = "1.21.4"
43
+ source = "registry+https://github.com/rust-lang/crates.io-index"
44
+ checksum = "9f7c3e4beb33f85d45ae3e3a1792185706c8e16d043238c593331cc7cd313b50"
45
+
46
+ [[package]]
47
+ name = "portable-atomic"
48
+ version = "1.15.0"
49
+ source = "registry+https://github.com/rust-lang/crates.io-index"
50
+ checksum = "05c8b63e8d9609db387f0324918f81d68fe27748f084ef092fb35954d0539a85"
51
+
52
+ [[package]]
53
+ name = "proc-macro2"
54
+ version = "1.0.107"
55
+ source = "registry+https://github.com/rust-lang/crates.io-index"
56
+ checksum = "985e7ec9bb745e6ce6535b544d84d6cd6f7ad8bd711c398938ae983b91a766d9"
57
+ dependencies = [
58
+ "unicode-ident",
59
+ ]
60
+
61
+ [[package]]
62
+ name = "pyo3"
63
+ version = "0.30.1"
64
+ source = "registry+https://github.com/rust-lang/crates.io-index"
65
+ checksum = "229ca13b8a15bb0d1487b81ab975bfcd97513416499a8312011b6036e42e0de4"
66
+ dependencies = [
67
+ "libc",
68
+ "once_cell",
69
+ "portable-atomic",
70
+ "pyo3-build-config",
71
+ "pyo3-ffi",
72
+ "pyo3-macros",
73
+ ]
74
+
75
+ [[package]]
76
+ name = "pyo3-build-config"
77
+ version = "0.30.1"
78
+ source = "registry+https://github.com/rust-lang/crates.io-index"
79
+ checksum = "70130e2b6dd1ee589a8788026a429561ca5c40fa7a2fa7914c2282eddae24700"
80
+ dependencies = [
81
+ "target-lexicon",
82
+ ]
83
+
84
+ [[package]]
85
+ name = "pyo3-ffi"
86
+ version = "0.30.1"
87
+ source = "registry+https://github.com/rust-lang/crates.io-index"
88
+ checksum = "5e7ff73c555c286d212d4ce7e5fbda845a973c4f61bd5f160f5f2c3c2a04d1c4"
89
+ dependencies = [
90
+ "libc",
91
+ "pyo3-build-config",
92
+ ]
93
+
94
+ [[package]]
95
+ name = "pyo3-macros"
96
+ version = "0.30.1"
97
+ source = "registry+https://github.com/rust-lang/crates.io-index"
98
+ checksum = "c46d2e5862c7bb8207e3b639f713dda3c499933444784154c11d013c5a691b60"
99
+ dependencies = [
100
+ "proc-macro2",
101
+ "pyo3-macros-backend",
102
+ "quote",
103
+ "syn",
104
+ ]
105
+
106
+ [[package]]
107
+ name = "pyo3-macros-backend"
108
+ version = "0.30.1"
109
+ source = "registry+https://github.com/rust-lang/crates.io-index"
110
+ checksum = "38b89f066f2ae72a2aef52d1537ca2fcd104440ebfadee06e97aa90738a25b9b"
111
+ dependencies = [
112
+ "heck",
113
+ "proc-macro2",
114
+ "quote",
115
+ "syn",
116
+ ]
117
+
118
+ [[package]]
119
+ name = "quote"
120
+ version = "1.0.47"
121
+ source = "registry+https://github.com/rust-lang/crates.io-index"
122
+ checksum = "1fbf4db142a473a8d80c26bbf18454ed458bf8d26c8219c331daecfdbd079001"
123
+ dependencies = [
124
+ "proc-macro2",
125
+ ]
126
+
127
+ [[package]]
128
+ name = "syn"
129
+ version = "3.0.10"
130
+ source = "registry+https://github.com/rust-lang/crates.io-index"
131
+ checksum = "4ae9ccbea3a7b0b09443036490c8f34a8b1b760fd345e5c0dae0aac718faea79"
132
+ dependencies = [
133
+ "proc-macro2",
134
+ "quote",
135
+ "unicode-ident",
136
+ ]
137
+
138
+ [[package]]
139
+ name = "target-lexicon"
140
+ version = "0.13.6"
141
+ source = "registry+https://github.com/rust-lang/crates.io-index"
142
+ checksum = "8c447be3a2abfa84b2d91680c56600bd6b2873866de27b36ec911be705e291da"
143
+
144
+ [[package]]
145
+ name = "unicode-ident"
146
+ version = "1.0.27"
147
+ source = "registry+https://github.com/rust-lang/crates.io-index"
148
+ checksum = "a2c754d6c33795a1c324727428e5a7dedb5b06195f9890bdbcba760d3e246563"
@@ -0,0 +1,18 @@
1
+ [package]
2
+ name = "fasthtmlparser-py"
3
+ version = "0.1.0"
4
+ edition = "2021"
5
+ publish = false
6
+ readme = "README.md"
7
+
8
+ [lib]
9
+ name = "_fasthtmlparser"
10
+ crate-type = ["cdylib"]
11
+
12
+ [dependencies]
13
+ fasthtmlparser = "0.1"
14
+ pyo3 = { version = "0.30", features = ["extension-module", "abi3-py310", "generate-import-lib"] }
15
+
16
+ [profile.release]
17
+ lto = "fat"
18
+ codegen-units = 1
@@ -0,0 +1,79 @@
1
+ # z3l.FastHtmlParser License
2
+
3
+ Copyright © 2026 z3l. All rights reserved.
4
+
5
+ This license applies to the z3l.FastHtmlParser library, its source code, binaries and
6
+ NuGet packages (the "Software").
7
+
8
+ ## 1. Definitions
9
+
10
+ - **"Licensee"** — the individual or legal entity that uses the Software, together with its
11
+ Affiliates.
12
+ - **"Affiliate"** — any entity that controls, is controlled by, or is under common control with
13
+ the Licensee.
14
+ - **"Annual Revenue"** — the total gross revenue of the Licensee (including all Affiliates) for
15
+ the last completed fiscal year, in US dollars or equivalent.
16
+ - **"Headcount"** — the total number of employees and individual contractors working for the
17
+ Licensee (including all Affiliates) on a full-time or full-time-equivalent basis, at any time
18
+ during the last 12 months.
19
+ - **"Small Licensee"** — a Licensee whose Annual Revenue is **below USD 1,000,000** and whose
20
+ Headcount is **below 100**. Both conditions must be met.
21
+
22
+ ## 2. Free License (Small Licensees)
23
+
24
+ If the Licensee is a Small Licensee (Annual Revenue **below USD 1,000,000** and Headcount
25
+ **below 100**), the Licensee is granted, free of charge, a worldwide, non-exclusive,
26
+ non-transferable license to use, copy and modify the Software and to distribute it as part of the
27
+ Licensee's own applications and services, including commercial ones.
28
+
29
+ ## 3. Commercial License (all other Licensees)
30
+
31
+ If the Licensee's Annual Revenue is **USD 1,000,000 or more**, or its Headcount is **100 or
32
+ more**, the Licensee must purchase a Commercial License.
33
+
34
+ - Price: a **one-time payment of USD 1,000** per Licensee (the Licensee together with all its
35
+ Affiliates).
36
+ - The Commercial License is perpetual and covers all current and future versions of the
37
+ Software, any number of developers, applications, servers and deployments of the Licensee.
38
+ - A Licensee that stops being a Small Licensee (its Annual Revenue or Headcount reaches the
39
+ threshold) while already using the Software must purchase the Commercial License within
40
+ 30 days.
41
+ - To purchase: https://romanti3172.github.io/z3l.FastHtmlParser/#pricing, or contact **romanti3172@gmail.com** for an invoice.
42
+
43
+ The Commercial License grants the same rights as section 2, without the revenue and headcount
44
+ limits.
45
+
46
+ **One license for all z3l libraries.** The Commercial License is not limited to the Software: it
47
+ also covers z3l.Scraper and every other library and package published by z3l, now or in the
48
+ future, on the same terms. The Licensee pays USD 1,000 once and needs no other z3l license.
49
+
50
+ ## 4. Conditions (both licenses)
51
+
52
+ 1. This license text and the copyright notice must be kept in all copies or substantial portions
53
+ of the Software's source code.
54
+ 2. The Licensee may not sell, sublicense or redistribute the Software on its own, or as part of a
55
+ library, SDK or component whose main purpose is HTML/XML parsing, so that it competes with the
56
+ Software.
57
+ 3. Modified versions of the Software may not be published or distributed under a different
58
+ license.
59
+ 4. End users of the Licensee's applications and services do not need their own license to use
60
+ those applications and services.
61
+
62
+ ## 5. Termination
63
+
64
+ The license terminates automatically if the Licensee breaches it and does not cure the breach
65
+ within 30 days after becoming aware of it. On termination the Licensee must stop using and
66
+ distributing the Software.
67
+
68
+ ## 6. No Warranty
69
+
70
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT
71
+ NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
72
+ NONINFRINGEMENT.
73
+
74
+ ## 7. Limitation of Liability
75
+
76
+ IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
77
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN
78
+ CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. THE TOTAL LIABILITY OF
79
+ THE COPYRIGHT HOLDERS SHALL NOT EXCEED THE AMOUNT PAID BY THE LICENSEE FOR THE SOFTWARE.
@@ -0,0 +1,156 @@
1
+ Metadata-Version: 2.4
2
+ Name: fasthtmlparser
3
+ Version: 0.1.0
4
+ Classifier: Development Status :: 4 - Beta
5
+ Classifier: Intended Audience :: Developers
6
+ Classifier: License :: Other/Proprietary License
7
+ Classifier: Programming Language :: Python :: 3
8
+ Classifier: Programming Language :: Python :: 3 :: Only
9
+ Classifier: Programming Language :: Rust
10
+ Classifier: Topic :: Internet :: WWW/HTTP :: Indexing/Search
11
+ Classifier: Topic :: Text Processing :: Markup :: HTML
12
+ Classifier: Topic :: Text Processing :: Markup :: XML
13
+ Classifier: Typing :: Typed
14
+ License-File: LICENSE.md
15
+ Summary: Fast HTML / XML parser for scraping with XPath 1.0 and CSS selectors, in Rust. A port of z3l.FastHtmlParser.
16
+ Keywords: html,parser,xpath,css,selectors,scraping,web-scraping,rust
17
+ Author: z3l
18
+ Requires-Python: >=3.10
19
+ Description-Content-Type: text/markdown; charset=UTF-8; variant=GFM
20
+ Project-URL: Homepage, https://github.com/romanti3172/fasthtmlparser-py
21
+ Project-URL: Issues, https://github.com/romanti3172/fasthtmlparser-py/issues
22
+ Project-URL: Rust crate, https://crates.io/crates/fasthtmlparser
23
+ Project-URL: Source, https://github.com/romanti3172/fasthtmlparser-py
24
+
25
+ # fasthtmlparser
26
+
27
+ [![CI](https://github.com/romanti3172/fasthtmlparser-py/actions/workflows/ci.yml/badge.svg)](https://github.com/romanti3172/fasthtmlparser-py/actions/workflows/ci.yml)
28
+ [![PyPI](https://img.shields.io/pypi/v/fasthtmlparser.svg)](https://pypi.org/project/fasthtmlparser/)
29
+
30
+ A fast HTML / XML parser for scraping, with **XPath 1.0** and **CSS selectors**: Python bindings of the
31
+ [Rust port](https://github.com/romanti3172/fasthtmlparser-rs) of
32
+ [z3l.FastHtmlParser](https://github.com/romanti3172/z3l.FastHtmlParser). It is built for extracting data, not for
33
+ building a DOM: a page becomes a flat list of tags that hold only positions in the source; text, attributes and
34
+ entities are read when you ask for them. Parsing is **5–7x faster than selectolax** and **20x faster than lxml**
35
+ (see below).
36
+
37
+ ```
38
+ pip install fasthtmlparser
39
+ ```
40
+
41
+ Python 3.10 or later. Wheels for Linux (glibc and musl), Windows and macOS, x86-64 and ARM64; no dependencies.
42
+
43
+ ```python
44
+ import fasthtmlparser as fh
45
+
46
+ doc = fh.parse(html, url="https://books.toscrape.com/") # str or bytes; url resolves relative links
47
+
48
+ # CSS selectors, as querySelectorAll / querySelector
49
+ for pod in doc.css("article.product_pod"):
50
+ title = pod.css_first("h3 a").attr("title")
51
+ price = pod.css_first("p.price_color").text
52
+ link = pod.css_first("h3 a").href # absolute URL
53
+ ul.css("> li") # the children of ul
54
+
55
+ # XPath 1.0
56
+ doc.xpath("//div[@class='card']//span[@class='price']") # tags
57
+ doc.xpath_values("//a[contains(@href, '/product/')]/@href")
58
+ doc.xpath_value("//dt[.='Price']/following-sibling::dd[1]")
59
+ doc.xpath_value("count(//table//tr)") # "12"
60
+
61
+ # compile once, reuse on any number of pages and threads
62
+ TITLES = fh.XPathQuery("//article//h3/a/@title")
63
+ TITLES.values(doc)
64
+ PRICES = fh.CssQuery("p.price_color")
65
+ PRICES.all(doc)
66
+
67
+ # search by name (any name, case-insensitive) and criteria, as in BeautifulSoup
68
+ pod = doc.find("article", class_="product_pod")
69
+ pod.find("p", class_="price_color").text
70
+ doc.find_all("a", attr=("rel", "next"))
71
+ doc.find("dt", text="Price").find_next_sibling("dd").text
72
+ doc.find("my-widget", id_starts_with="w-")
73
+ # criteria: class_, id, attr=(name, value), text, id_starts_with, text_starts_with, body, body_starts_with, source
74
+
75
+ # reading a tag
76
+ tag.name, tag.depth, tag.index, tag.pos # pos: byte offsets in the UTF-8 source
77
+ tag.text # visible text, entities decoded, whitespace collapsed
78
+ tag.text_line_breaks # <br> and block elements → new lines, <p> and headings → paragraphs
79
+ tag.attr("data-src") # decoded value, "" when missing; attr_raw(): as written
80
+ tag.attrs # {"href": "...", "class": "..."}
81
+ tag.href, tag.src # absolute URLs; href_from(base) / src_from(base)
82
+ tag.mailto, tag.tel # the address of a mailto: link, the number of a tel: link
83
+ tag.body, tag.outer_html, tag.source # inner HTML, the whole element, the opening tag
84
+
85
+ # navigation
86
+ tag.parent, tag.children, tag.next_sibling, tag.previous_sibling, tag.next, tag.previous
87
+ tag.find_parent("table"), tag.find_next("h2"), tag.text_after_until("br")
88
+
89
+ # the whole document
90
+ len(doc), doc[0], doc[-1], list(doc) # every tag, comments included
91
+ ```
92
+
93
+ A missing tag is `None`, a missing value is `""`. An invalid selector raises `fh.CssSelectorError`, an invalid XPath
94
+ expression `fh.XPathError` (both are `ValueError`s); `xpath()` on an expression that gives a number or string raises
95
+ `XPathError` too (use `xpath_value`). The string methods compile and cache queries. A `Node` keeps its document alive,
96
+ nodes compare equal when they are the same tag, and are hashable. The GIL is released while a page is parsed, and
97
+ documents and compiled queries can be shared between threads. Type stubs are included.
98
+
99
+ CSS: type, `*`, `#id`, `.class`, attribute selectors with all operators and the `i` / `s` flags, the four combinators,
100
+ selector lists, `:first-child`, `:last-child`, `:only-child`, `:*-of-type`, `:nth-child(An+B [of S])` and its relatives,
101
+ `:not()`, `:is()`, `:where()`, `:has()`, `:empty`, `:root`, `:scope`, `:link`, `:checked`, `:disabled`, `:enabled`,
102
+ `:required`, `:optional`, `:contains("text")`. XPath: all axes except namespace, predicates, `|`, the operators and all
103
+ XPath 1.0 functions, plus `ends-with()`, `lower-case()`, `upper-case()`. HTML rules apply: names are case-insensitive,
104
+ the string-value of an element is its visible text, attribute values and text are decoded. HTML5 optional end tags
105
+ (`<li>`, `<p>`, `<td>`, `<option>` without end tags) give the same elements as in a browser; there is no full HTML5
106
+ tree construction (no implied `<tbody>` or `<html>`), and documents are read-only.
107
+
108
+ ## Same results as the .NET version
109
+
110
+ `tests/test_conformance.py` runs the conformance data of the Rust crate through the Python package: on 117 pages
111
+ (fixtures, broken markup, cut-off pages, CR LF, 600-deep nesting, ...) every tag's name, position, text, text with line
112
+ breaks, attributes, navigation and links, and 569 XPath / CSS queries on the document and from three tags of each
113
+ page, must give exactly what z3l.FastHtmlParser (.NET) gives. So the bindings are checked as well as the parser.
114
+
115
+ ## Benchmarks
116
+
117
+ `python bench/bench.py` (Python 3.14, AMD Ryzen 7 3800X, Windows; [`bench-results.md`](bench-results.md)). Every
118
+ library must extract the same records before anything is timed.
119
+
120
+ Parse a page:
121
+
122
+ | Page | fasthtmlparser | selectolax (lexbor) | lxml | parsel | BeautifulSoup (lxml) |
123
+ |---|---:|---:|---:|---:|---:|
124
+ | quotes, 11 KB | 19 μs | 95 μs | 495 μs | 499 μs | 4,368 μs |
125
+ | laptops, 38 KB | 53 μs | 306 μs | 1,379 μs | 1,420 μs | 12,192 μs |
126
+ | books, 51 KB | 65 μs | 424 μs | 1,547 μs | 1,616 μs | 15,273 μs |
127
+ | books x10, 510 KB | 652 μs | 3,531 μs | 13,873 μs | 14,886 μs | 15,083 μs\* |
128
+ | books without `</li>` `</p>` | 59 μs | 221 μs | 1,460 μs | 1,593 μs | 14,393 μs |
129
+
130
+ \* BeautifulSoup with lxml stops at the first `</html>`: it finds 20 of the 200 books on that page.
131
+
132
+ Scrape a page: parse and extract the records (books: 20 × title, price, rating; quotes: 10 × text, author, tags).
133
+
134
+ | Task | fasthtmlparser | selectolax | lxml / parsel | BeautifulSoup (lxml) |
135
+ |---|---:|---:|---:|---:|
136
+ | 20 books, CSS | 126 μs | 587 μs | parsel 2,543 μs | 19,006 μs |
137
+ | 20 books, XPath | 217 μs | | lxml 2,715 μs | |
138
+ | 20 books, `find` | 152 μs | | | |
139
+ | 10 quotes | 74 μs | 271 μs | parsel 1,030 μs | 5,984 μs |
140
+
141
+ ## Build from source
142
+
143
+ Needs Rust 1.85+ and [maturin](https://www.maturin.rs/):
144
+
145
+ ```
146
+ python -m venv .venv && .venv/Scripts/activate # or . .venv/bin/activate
147
+ pip install maturin pytest
148
+ maturin develop --release
149
+ pytest
150
+ ```
151
+
152
+ ## License
153
+
154
+ Same terms as z3l.FastHtmlParser (see LICENSE.md): free for companies under USD 1M annual revenue and under 100
155
+ people, a commercial license above that. This is source-available, not an OSI open-source license.
156
+
@@ -0,0 +1,131 @@
1
+ # fasthtmlparser
2
+
3
+ [![CI](https://github.com/romanti3172/fasthtmlparser-py/actions/workflows/ci.yml/badge.svg)](https://github.com/romanti3172/fasthtmlparser-py/actions/workflows/ci.yml)
4
+ [![PyPI](https://img.shields.io/pypi/v/fasthtmlparser.svg)](https://pypi.org/project/fasthtmlparser/)
5
+
6
+ A fast HTML / XML parser for scraping, with **XPath 1.0** and **CSS selectors**: Python bindings of the
7
+ [Rust port](https://github.com/romanti3172/fasthtmlparser-rs) of
8
+ [z3l.FastHtmlParser](https://github.com/romanti3172/z3l.FastHtmlParser). It is built for extracting data, not for
9
+ building a DOM: a page becomes a flat list of tags that hold only positions in the source; text, attributes and
10
+ entities are read when you ask for them. Parsing is **5–7x faster than selectolax** and **20x faster than lxml**
11
+ (see below).
12
+
13
+ ```
14
+ pip install fasthtmlparser
15
+ ```
16
+
17
+ Python 3.10 or later. Wheels for Linux (glibc and musl), Windows and macOS, x86-64 and ARM64; no dependencies.
18
+
19
+ ```python
20
+ import fasthtmlparser as fh
21
+
22
+ doc = fh.parse(html, url="https://books.toscrape.com/") # str or bytes; url resolves relative links
23
+
24
+ # CSS selectors, as querySelectorAll / querySelector
25
+ for pod in doc.css("article.product_pod"):
26
+ title = pod.css_first("h3 a").attr("title")
27
+ price = pod.css_first("p.price_color").text
28
+ link = pod.css_first("h3 a").href # absolute URL
29
+ ul.css("> li") # the children of ul
30
+
31
+ # XPath 1.0
32
+ doc.xpath("//div[@class='card']//span[@class='price']") # tags
33
+ doc.xpath_values("//a[contains(@href, '/product/')]/@href")
34
+ doc.xpath_value("//dt[.='Price']/following-sibling::dd[1]")
35
+ doc.xpath_value("count(//table//tr)") # "12"
36
+
37
+ # compile once, reuse on any number of pages and threads
38
+ TITLES = fh.XPathQuery("//article//h3/a/@title")
39
+ TITLES.values(doc)
40
+ PRICES = fh.CssQuery("p.price_color")
41
+ PRICES.all(doc)
42
+
43
+ # search by name (any name, case-insensitive) and criteria, as in BeautifulSoup
44
+ pod = doc.find("article", class_="product_pod")
45
+ pod.find("p", class_="price_color").text
46
+ doc.find_all("a", attr=("rel", "next"))
47
+ doc.find("dt", text="Price").find_next_sibling("dd").text
48
+ doc.find("my-widget", id_starts_with="w-")
49
+ # criteria: class_, id, attr=(name, value), text, id_starts_with, text_starts_with, body, body_starts_with, source
50
+
51
+ # reading a tag
52
+ tag.name, tag.depth, tag.index, tag.pos # pos: byte offsets in the UTF-8 source
53
+ tag.text # visible text, entities decoded, whitespace collapsed
54
+ tag.text_line_breaks # <br> and block elements → new lines, <p> and headings → paragraphs
55
+ tag.attr("data-src") # decoded value, "" when missing; attr_raw(): as written
56
+ tag.attrs # {"href": "...", "class": "..."}
57
+ tag.href, tag.src # absolute URLs; href_from(base) / src_from(base)
58
+ tag.mailto, tag.tel # the address of a mailto: link, the number of a tel: link
59
+ tag.body, tag.outer_html, tag.source # inner HTML, the whole element, the opening tag
60
+
61
+ # navigation
62
+ tag.parent, tag.children, tag.next_sibling, tag.previous_sibling, tag.next, tag.previous
63
+ tag.find_parent("table"), tag.find_next("h2"), tag.text_after_until("br")
64
+
65
+ # the whole document
66
+ len(doc), doc[0], doc[-1], list(doc) # every tag, comments included
67
+ ```
68
+
69
+ A missing tag is `None`, a missing value is `""`. An invalid selector raises `fh.CssSelectorError`, an invalid XPath
70
+ expression `fh.XPathError` (both are `ValueError`s); `xpath()` on an expression that gives a number or string raises
71
+ `XPathError` too (use `xpath_value`). The string methods compile and cache queries. A `Node` keeps its document alive,
72
+ nodes compare equal when they are the same tag, and are hashable. The GIL is released while a page is parsed, and
73
+ documents and compiled queries can be shared between threads. Type stubs are included.
74
+
75
+ CSS: type, `*`, `#id`, `.class`, attribute selectors with all operators and the `i` / `s` flags, the four combinators,
76
+ selector lists, `:first-child`, `:last-child`, `:only-child`, `:*-of-type`, `:nth-child(An+B [of S])` and its relatives,
77
+ `:not()`, `:is()`, `:where()`, `:has()`, `:empty`, `:root`, `:scope`, `:link`, `:checked`, `:disabled`, `:enabled`,
78
+ `:required`, `:optional`, `:contains("text")`. XPath: all axes except namespace, predicates, `|`, the operators and all
79
+ XPath 1.0 functions, plus `ends-with()`, `lower-case()`, `upper-case()`. HTML rules apply: names are case-insensitive,
80
+ the string-value of an element is its visible text, attribute values and text are decoded. HTML5 optional end tags
81
+ (`<li>`, `<p>`, `<td>`, `<option>` without end tags) give the same elements as in a browser; there is no full HTML5
82
+ tree construction (no implied `<tbody>` or `<html>`), and documents are read-only.
83
+
84
+ ## Same results as the .NET version
85
+
86
+ `tests/test_conformance.py` runs the conformance data of the Rust crate through the Python package: on 117 pages
87
+ (fixtures, broken markup, cut-off pages, CR LF, 600-deep nesting, ...) every tag's name, position, text, text with line
88
+ breaks, attributes, navigation and links, and 569 XPath / CSS queries on the document and from three tags of each
89
+ page, must give exactly what z3l.FastHtmlParser (.NET) gives. So the bindings are checked as well as the parser.
90
+
91
+ ## Benchmarks
92
+
93
+ `python bench/bench.py` (Python 3.14, AMD Ryzen 7 3800X, Windows; [`bench-results.md`](bench-results.md)). Every
94
+ library must extract the same records before anything is timed.
95
+
96
+ Parse a page:
97
+
98
+ | Page | fasthtmlparser | selectolax (lexbor) | lxml | parsel | BeautifulSoup (lxml) |
99
+ |---|---:|---:|---:|---:|---:|
100
+ | quotes, 11 KB | 19 μs | 95 μs | 495 μs | 499 μs | 4,368 μs |
101
+ | laptops, 38 KB | 53 μs | 306 μs | 1,379 μs | 1,420 μs | 12,192 μs |
102
+ | books, 51 KB | 65 μs | 424 μs | 1,547 μs | 1,616 μs | 15,273 μs |
103
+ | books x10, 510 KB | 652 μs | 3,531 μs | 13,873 μs | 14,886 μs | 15,083 μs\* |
104
+ | books without `</li>` `</p>` | 59 μs | 221 μs | 1,460 μs | 1,593 μs | 14,393 μs |
105
+
106
+ \* BeautifulSoup with lxml stops at the first `</html>`: it finds 20 of the 200 books on that page.
107
+
108
+ Scrape a page: parse and extract the records (books: 20 × title, price, rating; quotes: 10 × text, author, tags).
109
+
110
+ | Task | fasthtmlparser | selectolax | lxml / parsel | BeautifulSoup (lxml) |
111
+ |---|---:|---:|---:|---:|
112
+ | 20 books, CSS | 126 μs | 587 μs | parsel 2,543 μs | 19,006 μs |
113
+ | 20 books, XPath | 217 μs | | lxml 2,715 μs | |
114
+ | 20 books, `find` | 152 μs | | | |
115
+ | 10 quotes | 74 μs | 271 μs | parsel 1,030 μs | 5,984 μs |
116
+
117
+ ## Build from source
118
+
119
+ Needs Rust 1.85+ and [maturin](https://www.maturin.rs/):
120
+
121
+ ```
122
+ python -m venv .venv && .venv/Scripts/activate # or . .venv/bin/activate
123
+ pip install maturin pytest
124
+ maturin develop --release
125
+ pytest
126
+ ```
127
+
128
+ ## License
129
+
130
+ Same terms as z3l.FastHtmlParser (see LICENSE.md): free for companies under USD 1M annual revenue and under 100
131
+ people, a commercial license above that. This is source-available, not an OSI open-source license.