astree 0.1.0__tar.gz

astree-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Outside Labs
+
+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.

astree-0.1.0/PKG-INFO

@@ -0,0 +1,107 @@
+Metadata-Version: 2.4
+Name: astree
+Version: 0.1.0
+Summary: Dependency-free HTML trees and extraction powered by html.parser
+Author: ellainng
+Author-email: ellainng <299958882+ellainng@users.noreply.github.com>
+License-Expression: MIT
+License-File: LICENSE
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Typing :: Typed
+Requires-Python: >=3.14
+Project-URL: Homepage, https://github.com/wispsy/astree
+Project-URL: Repository, https://github.com/wispsy/astree
+Project-URL: Issues, https://github.com/wispsy/astree/issues
+Description-Content-Type: text/markdown
+
+# astree
+
+Dependency-free HTML tree parsing, CSS selector querying, and structured record extraction powered by Python's `html.parser`.
+
+Requires Python 3.14+.
+
+## Highlights
+
+- **Dependency-Free**: Built strictly on Python standard library primitives.
+- **Full DOM Navigation**: Navigable `Document` and `Node` tree with parent/child links and attributes.
+- **CSS Selectors**: Fast CSS selector queries (`select`, `select_one`).
+- **Streaming Collectors**: Single-pass `LinkCollector` and `TextCollector` with bounds protection.
+- **Declarative Schema Extraction**: `extract` and `extract_all` using `Field` definitions with type converters and cardinality validation.
+- **Configurable Limits**: Protect against deeply nested tags or resource exhaustion (`max_depth`, `max_nodes`, `max_chars`).
+
+## Installation
+
+```sh
+pip install astree
+```
+
+For development:
+
+```sh
+git clone https://github.com/wispsy/astree.git
+cd astree
+uv sync
+```
+
+## Quick Start
+
+### Basic Parsing & Queries
+
+```python
+from astree import Document
+
+doc = Document.from_html('''
+<!doctype html>
+<html>
+  <head><title>My Article</title></head>
+  <body>
+    <article class="card" data-id="42">
+      <h2>Headline</h2>
+      <a href="/post/42">Read story</a>
+    </article>
+  </body>
+</html>
+''')
+
+assert doc.title == 'My Article'
+card = doc.select_one('article.card')
+assert card is not None
+assert card.attrs['data-id'] == '42'
+
+link = card.find('a', href=True)
+assert link is not None
+assert link.attrs['href'] == '/post/42'
+assert card.get_text(' ', strip=True) == 'Headline Read story'
+```
+
+### Structured Record Extraction
+
+```python
+from astree import Document, Field, extract_all
+
+records = extract_all(doc, 'article.card', {
+    'id': Field(attribute='data-id', convert=int),
+    'headline': Field('h2'),
+    'url': Field('a', attribute='href'),
+})
+
+# [{'id': 42, 'headline': 'Headline', 'url': '/post/42'}]
+```
+
+## Documentation
+
+See [docs/api.md](docs/api.md) for full API details, selector capabilities, collectors, and structured extraction specifications.
+
+## Running Tests
+
+```sh
+python -m unittest discover -s tests -v
+```
+
+## License
+
+MIT

astree-0.1.0/README.md

@@ -0,0 +1,87 @@
+# astree
+
+Dependency-free HTML tree parsing, CSS selector querying, and structured record extraction powered by Python's `html.parser`.
+
+Requires Python 3.14+.
+
+## Highlights
+
+- **Dependency-Free**: Built strictly on Python standard library primitives.
+- **Full DOM Navigation**: Navigable `Document` and `Node` tree with parent/child links and attributes.
+- **CSS Selectors**: Fast CSS selector queries (`select`, `select_one`).
+- **Streaming Collectors**: Single-pass `LinkCollector` and `TextCollector` with bounds protection.
+- **Declarative Schema Extraction**: `extract` and `extract_all` using `Field` definitions with type converters and cardinality validation.
+- **Configurable Limits**: Protect against deeply nested tags or resource exhaustion (`max_depth`, `max_nodes`, `max_chars`).
+
+## Installation
+
+```sh
+pip install astree
+```
+
+For development:
+
+```sh
+git clone https://github.com/wispsy/astree.git
+cd astree
+uv sync
+```
+
+## Quick Start
+
+### Basic Parsing & Queries
+
+```python
+from astree import Document
+
+doc = Document.from_html('''
+<!doctype html>
+<html>
+  <head><title>My Article</title></head>
+  <body>
+    <article class="card" data-id="42">
+      <h2>Headline</h2>
+      <a href="/post/42">Read story</a>
+    </article>
+  </body>
+</html>
+''')
+
+assert doc.title == 'My Article'
+card = doc.select_one('article.card')
+assert card is not None
+assert card.attrs['data-id'] == '42'
+
+link = card.find('a', href=True)
+assert link is not None
+assert link.attrs['href'] == '/post/42'
+assert card.get_text(' ', strip=True) == 'Headline Read story'
+```
+
+### Structured Record Extraction
+
+```python
+from astree import Document, Field, extract_all
+
+records = extract_all(doc, 'article.card', {
+    'id': Field(attribute='data-id', convert=int),
+    'headline': Field('h2'),
+    'url': Field('a', attribute='href'),
+})
+
+# [{'id': 42, 'headline': 'Headline', 'url': '/post/42'}]
+```
+
+## Documentation
+
+See [docs/api.md](docs/api.md) for full API details, selector capabilities, collectors, and structured extraction specifications.
+
+## Running Tests
+
+```sh
+python -m unittest discover -s tests -v
+```
+
+## License
+
+MIT

astree-0.1.0/docs/api.md

@@ -0,0 +1,92 @@
+# astree API Reference
+
+`astree` provides dependency-free HTML tree parsing, CSS selector queries, streaming collectors, and structured record extraction powered by Python's standard library `html.parser.HTMLParser`. Python 3.14+ is required.
+
+---
+
+## 1. Document & Node Model
+
+### `Document`
+
+Constructed via:
+- `Document.from_html(html: str, **limits) -> Document`: Convenience factory parsing the full HTML string.
+- Or via `DocumentParser`.
+
+#### Methods & Properties
+- `title: str | None`: Returns the text of the `<title>` tag, if present.
+- `text: str`: Normalized text across all descendants (excluding script/style/comments).
+- `get_text(separator: str = '', strip: bool = False) -> str`: Concatenates text nodes with a separator and optional whitespace stripping.
+- `select(selector: str) -> list[Node]`: Queries descendant elements using CSS selectors in document order.
+- `select_one(selector: str) -> Node | None`: Returns the first matching element, or `None`.
+- `find(tag: str | None = None, attrs: Mapping[str, Any] | None = None, **kwargs) -> Node | None`: Searches for matching descendant element.
+- `find_all(tag: str | None = None, attrs: Mapping[str, Any] | None = None, **kwargs) -> list[Node]`: Finds all matching descendant elements.
+- `descendants() -> Iterator[Node]`: Iterates over all descendant nodes in depth-first preorder.
+
+### `Node`
+
+Represents a DOM node.
+- `kind: Literal['root', 'element', 'text', 'comment', 'decl', 'pi']`
+- `tag: str | None`: Tag name for elements (e.g. `'div'`, `'a'`).
+- `attrs: Mapping[str, str]`: Read-only attributes dictionary.
+- `parent: Node | None`: Parent node.
+- `children: tuple[Node, ...]`: Direct child nodes.
+- `data: str | None`: Text content for text/comment/decl nodes.
+
+---
+
+## 2. Streaming Parsers & Collectors
+
+### `DocumentParser`
+
+Subclasses `html.parser.HTMLParser`. Incrementally feeds HTML chunks.
+
+```python
+parser = DocumentParser(max_depth=512, max_nodes=50_000, max_chars=10_000_000)
+parser.feed(chunk)
+parser.close()
+doc = parser.document
+```
+
+### `LinkCollector`
+
+Streaming anchor tag extractor:
+```python
+collector = LinkCollector(base_url='https://example.com/', collect=True, on_link=callback)
+collector.feed(chunk)
+collector.close()
+for link in collector.links:
+    print(link.url, link.text)
+```
+
+### `TextCollector`
+
+Streaming text extractor ignoring non-visible tags:
+```python
+collector = TextCollector()
+collector.feed(chunk)
+collector.close()
+print(collector.text)
+```
+
+---
+
+## 3. Structured Record Extraction
+
+Extracts typed dictionaries or dataclass records from HTML elements:
+
+```python
+from astree import Document, Field, extract_all
+
+doc = Document.from_html(html)
+records = extract_all(doc, 'article.item', {
+    'id': Field(attribute='data-id', convert=int),
+    'title': Field('h2'),
+    'link': Field('a', attribute='href'),
+    'tags': Field('span.tag', many=True),
+})
+```
+
+- `Field(selector=None, attribute=None, default=..., required=True, many=False, convert=None)`: Defines how a record field is extracted from a scoped element.
+- `extract(node, schema, factory=dict)`: Extracts a single record from a node.
+- `extract_all(node, row_selector, schema, factory=dict)`: Scopes and extracts records for all elements matching `row_selector`.
+- `ExtractionError`: Raised when extraction fails due to missing required fields, cardinality mismatch, or conversion errors.

astree-0.1.0/examples/html_extract.py

@@ -0,0 +1,21 @@
+"""Offline HTML querying and callback-based link extraction."""
+
+from astree import Document, LinkCollector, TextCollector
+
+source = '<title>Reading</title><article class=card><h2>A &amp; B</h2><a href="/one">Read</a></article>'
+doc = Document.from_html(source)
+assert doc.title == 'Reading'
+assert doc.select_one('.card > h2').text == 'A & B'
+assert doc.select_one('article').get_text(' ', strip=True) == 'A & B Read'
+links = []
+parser = LinkCollector(base_url='https://example.test/', collect=False, on_link=links.append)
+for offset in range(0, len(source), 7):
+    parser.feed(source[offset:offset + 7])
+parser.close()
+assert links[0].url == 'https://example.test/one'
+assert links[0].text == 'Read'
+collector = TextCollector()
+collector.feed('<p>Visible</p><style>hidden</style>')
+collector.close()
+assert collector.text == 'Visible'
+print('HTML extraction passed')

astree-0.1.0/pyproject.toml

@@ -0,0 +1,40 @@
+[project]
+name = "astree"
+version = "0.1.0"
+description = "Dependency-free HTML trees and extraction powered by html.parser"
+readme = "README.md"
+license = "MIT"
+license-files = ["LICENSE"]
+requires-python = ">=3.14"
+dependencies = []
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Developers",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.14",
+    "Typing :: Typed",
+]
+
+[[project.authors]]
+name = "ellainng"
+email = "299958882+ellainng@users.noreply.github.com"
+
+[project.urls]
+Homepage = "https://github.com/wispsy/astree"
+Repository = "https://github.com/wispsy/astree"
+Issues = "https://github.com/wispsy/astree/issues"
+
+[build-system]
+requires = ["uv_build>=0.13.6,<0.14.0"]
+build-backend = "uv_build"
+
+[tool.uv.build-backend]
+source-include = [
+    "tests/**",
+    "docs/**",
+    "examples/**",
+    "scripts/**",
+    "LICENSE",
+    "README.md",
+]

astree-0.1.0/pyproject.toml.orig

@@ -0,0 +1,32 @@
+[project]
+name = "astree"
+version = "0.1.0"
+description = "Dependency-free HTML trees and extraction powered by html.parser"
+readme = "README.md"
+license = "MIT"
+license-files = ["LICENSE"]
+authors = [
+    { name = "ellainng", email = "299958882+ellainng@users.noreply.github.com" }
+]
+requires-python = ">=3.14"
+dependencies = []
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Developers",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.14",
+    "Typing :: Typed",
+]
+
+[project.urls]
+Homepage = "https://github.com/wispsy/astree"
+Repository = "https://github.com/wispsy/astree"
+Issues = "https://github.com/wispsy/astree/issues"
+
+[build-system]
+requires = ["uv_build>=0.13.6,<0.14.0"]
+build-backend = "uv_build"
+
+[tool.uv.build-backend]
+source-include = ["tests/**", "docs/**", "examples/**", "scripts/**", "LICENSE", "README.md"]

astree-0.1.0/scripts/profile_extraction.py

@@ -0,0 +1,78 @@
+"""Bounded diagnostic measurements; no benchmark threshold or speed claim."""
+
+import argparse
+import gc
+import json
+import platform
+import sys
+from time import perf_counter
+import tracemalloc
+
+from astree import Document, Field, __version__, extract_all
+
+
+def _measure(source: str) -> dict[str, object]:
+    tracemalloc.start()
+    try:
+        started = perf_counter()
+        document = Document.from_html(source)
+        records = extract_all(
+            document,
+            'article',
+            {
+                'id': Field(attribute='data-id', convert=int),
+                'title': Field('h2'),
+            },
+        )
+        elapsed = perf_counter() - started
+        _, peak = tracemalloc.get_traced_memory()
+        return {'records': len(records), 'elapsed_seconds': elapsed, 'traced_peak_bytes': peak}
+    finally:
+        tracemalloc.stop()
+
+
+def profile(records: int = 1000, iterations: int = 3) -> dict[str, object]:
+    for name, value, maximum in (('records', records, 10000), ('iterations', iterations, 20)):
+        if isinstance(value, bool) or not isinstance(value, int):
+            raise TypeError(f'{name} must be an integer')
+        if not 1 <= value <= maximum:
+            raise ValueError(f'{name} must be between 1 and {maximum}')
+    if tracemalloc.is_tracing():
+        raise RuntimeError('run this diagnostic in its own tracemalloc session')
+    source = ''.join(f'<article data-id="{n}"><h2>Entry {n}</h2></article>' for n in range(records))
+    samples = []
+    for _ in range(iterations):
+        gc.collect()
+        samples.append(_measure(source))
+    return {
+        'environment': {
+            'astree': __version__,
+            'python': sys.version,
+            'implementation': platform.python_implementation(),
+            'platform': platform.platform(),
+        },
+        'workload': {
+            'records': records,
+            'input_characters': len(source),
+            'iterations': iterations,
+            'measured_stage': 'parse, select and extract; excludes input generation/imports',
+            'memory_scope': 'traced Python allocations, not process RSS',
+        },
+        'samples': samples,
+    }
+
+
+def main() -> None:
+    parser = argparse.ArgumentParser(description=__doc__)
+    parser.add_argument('--records', type=int, default=1000)
+    parser.add_argument('--iterations', type=int, default=3)
+    args = parser.parse_args()
+    try:
+        result = profile(args.records, args.iterations)
+    except (ValueError, TypeError, RuntimeError) as error:
+        parser.error(str(error))
+    print(json.dumps(result, indent=2))
+
+
+if __name__ == '__main__':
+    main()

astree-0.1.0/src/astree/__init__.py

@@ -0,0 +1,25 @@
+"""Dependency-free HTML trees and extraction powered by html.parser."""
+
+from .collectors import Link, LinkCollector, TextCollector
+from .extract import ExtractionError, Field, extract, extract_all
+from .nodes import Node
+from .parser import Document, DocumentParser, ParseLimitError
+from .selectors import SelectorSyntaxError
+
+__version__ = '0.1.0'
+
+__all__ = [
+    'Document',
+    'DocumentParser',
+    'Node',
+    'ParseLimitError',
+    'SelectorSyntaxError',
+    'Link',
+    'LinkCollector',
+    'TextCollector',
+    'Field',
+    'ExtractionError',
+    'extract',
+    'extract_all',
+    '__version__',
+]

astree-0.1.0/src/astree/collectors.py

@@ -0,0 +1,154 @@
+"""Incremental extraction without retaining an HTML document tree."""
+
+from collections.abc import Callable
+from dataclasses import dataclass, field
+from urllib.parse import urljoin
+
+from .parser import _BoundedParser, ParseLimitError, VOID_ELEMENTS
+
+
+@dataclass(frozen=True, slots=True)
+class Link:
+    """An anchor's original href, visible text, and explicitly resolved URL."""
+
+    href: str
+    text: str
+    url: str
+
+
+@dataclass(eq=False, slots=True)
+class _Frame:
+    tag: str
+    href: str | None = None
+    pieces: list[str] = field(default_factory=list)
+
+
+class _StreamParser(_BoundedParser):
+    def __init__(self, *, max_chars: int, max_nodes: int, max_depth: int) -> None:
+        super().__init__(max_chars=max_chars, max_nodes=max_nodes, max_depth=max_depth)
+        self._stack: list[_Frame] = []
+        self._last_was_data = False
+
+    def _open(self, tag: str, attrs: list[tuple[str, str | None]], *, closed: bool) -> None:
+        if len(self._stack) >= self.max_depth:
+            raise ParseLimitError('max_depth exceeded')
+        self._count()
+        self._last_was_data = False
+        frame = _Frame(tag, dict(attrs).get('href') if tag == 'a' else None)
+        if closed or tag in VOID_ELEMENTS:
+            self._end(frame)
+        else:
+            self._stack.append(frame)
+
+    def handle_starttag(self, tag: str, attrs: list[tuple[str, str | None]]) -> None:
+        self._open(tag, attrs, closed=False)
+
+    def handle_startendtag(self, tag: str, attrs: list[tuple[str, str | None]]) -> None:
+        self._open(tag, attrs, closed=True)
+
+    def handle_endtag(self, tag: str) -> None:
+        for index in range(len(self._stack) - 1, -1, -1):
+            if self._stack[index].tag == tag:
+                frames = self._stack[index:]
+                del self._stack[index:]
+                for frame in reversed(frames):
+                    self._end(frame)
+                self._last_was_data = False
+                break
+
+    def handle_data(self, data: str) -> None:
+        if not data:
+            return
+        if not self._last_was_data:
+            self._count()
+        self._last_was_data = True
+        if not any(frame.tag in {'script', 'style'} for frame in self._stack):
+            self._data(data)
+
+    def handle_comment(self, data: str) -> None:
+        self._count()
+        self._last_was_data = False
+
+    handle_decl = handle_comment
+    handle_pi = handle_comment
+    unknown_decl = handle_comment
+
+    def _data(self, data: str) -> None:
+        pass
+
+    def _end(self, frame: _Frame) -> None:
+        pass
+
+    def _finish(self) -> None:
+        frames, self._stack = self._stack, []
+        for frame in reversed(frames):
+            self._end(frame)
+
+
+class LinkCollector(_StreamParser):
+    """Emit links when anchors close, including implicit closure at EOF.
+
+    Set collect=False with on_link to process output without retaining results.
+    URL resolution does not validate schemes or make URLs safe to fetch.
+    """
+
+    def __init__(self, *, base_url: str | None = None,
+                 on_link: Callable[[Link], None] | None = None, collect: bool = True,
+                 max_chars: int = 10_000_000, max_nodes: int = 100_000,
+                 max_depth: int = 256) -> None:
+        if base_url is not None and not isinstance(base_url, str):
+            raise TypeError('base_url must be a string or None')
+        if on_link is not None and not callable(on_link):
+            raise TypeError('on_link must be callable or None')
+        if not isinstance(collect, bool):
+            raise TypeError('collect must be a bool')
+        super().__init__(max_chars=max_chars, max_nodes=max_nodes, max_depth=max_depth)
+        self._base_url = base_url
+        self._on_link = on_link
+        self._collect = collect
+        self._links: list[Link] = []
+
+    @property
+    def links(self) -> tuple[Link, ...]:
+        return tuple(self._links)
+
+    def _data(self, data: str) -> None:
+        for frame in self._stack:
+            if frame.href is not None:
+                frame.pieces.append(data)
+
+    def _end(self, frame: _Frame) -> None:
+        if frame.href is None:
+            return
+        url = urljoin(self._base_url, frame.href) if self._base_url is not None else frame.href
+        link = Link(frame.href, ''.join(frame.pieces), url)
+        if self._collect:
+            self._links.append(link)
+        if self._on_link is not None:
+            self._on_link(link)
+
+
+class TextCollector(_StreamParser):
+    """Collect visible text or call on_text with incremental decoded chunks."""
+
+    def __init__(self, *, on_text: Callable[[str], None] | None = None,
+                 collect: bool = True, max_chars: int = 10_000_000,
+                 max_nodes: int = 100_000, max_depth: int = 256) -> None:
+        if on_text is not None and not callable(on_text):
+            raise TypeError('on_text must be callable or None')
+        if not isinstance(collect, bool):
+            raise TypeError('collect must be a bool')
+        super().__init__(max_chars=max_chars, max_nodes=max_nodes, max_depth=max_depth)
+        self._on_text = on_text
+        self._collect = collect
+        self._pieces: list[str] = []
+
+    @property
+    def text(self) -> str:
+        return ''.join(self._pieces)
+
+    def _data(self, data: str) -> None:
+        if self._collect:
+            self._pieces.append(data)
+        if self._on_text is not None:
+            self._on_text(data)