astree 0.1.0__py3-none-any.whl

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/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)

astree/extract.py

@@ -0,0 +1,138 @@
+"""Explicit, scoped HTML fields returning ordinary Python records."""
+
+from collections.abc import Callable, Mapping
+from dataclasses import dataclass, field as dataclass_field
+from typing import Literal
+
+from .nodes import Node
+from .selectors import _Grammar
+
+__all__ = ['Field', 'ExtractionError', 'extract', 'extract_all']
+_UNSET = object()
+type ErrorReason = Literal['missing', 'multiple', 'attribute', 'conversion', 'default']
+
+
+class ExtractionError(ValueError):
+    """A field failed; messages do not contain extracted source values."""
+
+    def __init__(self, field: str, reason: ErrorReason, *, record: int | None = None,
+                 item: int | None = None) -> None:
+        self.field = field
+        self.reason = reason
+        self.record = record
+        self.item = item
+        context = f'record {record}, ' if record is not None else ''
+        super().__init__(f'{context}field {field!r}: {reason}')
+
+
+@dataclass(frozen=True, slots=True)
+class Field:
+    """Read the receiver (selector=None) or scoped descendant elements.
+
+    Exactly one match is required unless many=True. Optional missing selections
+    use a default, a per-use factory, None for a scalar, or [] for a collection.
+    Optional missing/boolean attributes use the scalar fallback for that item.
+    Constants are returned by reference; use a factory for fresh mutable defaults.
+    """
+
+    selector: str | None = None
+    attribute: str | None = None
+    many: bool = False
+    required: bool = True
+    strip: bool = True
+    convert: Callable[[str], object] | None = None
+    default: object = dataclass_field(default=_UNSET, repr=False)
+    default_factory: Callable[[], object] | None = None
+
+    def __post_init__(self) -> None:
+        if self.selector is not None:
+            _Grammar(self.selector).parse()
+        if self.attribute is not None:
+            if not isinstance(self.attribute, str):
+                raise TypeError('attribute must be a string or None')
+            if not self.attribute:
+                raise ValueError('attribute must not be empty')
+            object.__setattr__(self, 'attribute', self.attribute.lower())
+        if any(not isinstance(getattr(self, name), bool) for name in ('many', 'required', 'strip')):
+            raise TypeError('many, required and strip must be bools')
+        for name in ('convert', 'default_factory'):
+            value = getattr(self, name)
+            if value is not None and not callable(value):
+                raise TypeError(f'{name} must be callable or None')
+        if self.default is not _UNSET and self.default_factory is not None:
+            raise ValueError('choose default or default_factory')
+        if self.required and (self.default is not _UNSET or self.default_factory is not None):
+            raise ValueError('defaults require required=False')
+
+
+def _schema(fields: Mapping[str, Field]) -> dict[str, Field]:
+    if not isinstance(fields, Mapping):
+        raise TypeError('fields must be a mapping')
+    result = dict(fields)
+    if any(not isinstance(name, str) or not name or not isinstance(spec, Field)
+           for name, spec in result.items()):
+        raise TypeError('fields require nonempty string names and Field values')
+    return result
+
+
+def _fallback(spec: Field, name: str, record: int | None, *, collection: bool = False) -> object:
+    if spec.default_factory is not None:
+        try:
+            return spec.default_factory()
+        except Exception as error:
+            raise ExtractionError(name, 'default', record=record) from error
+    if spec.default is not _UNSET:
+        return spec.default
+    return [] if collection else None
+
+
+def _record(node: Node, fields: dict[str, Field], record: int | None) -> dict[str, object]:
+    result: dict[str, object] = {}
+    for name, spec in fields.items():
+        nodes = [node] if spec.selector is None else node.select(spec.selector)
+        if not nodes:
+            if spec.required:
+                raise ExtractionError(name, 'missing', record=record)
+            result[name] = _fallback(spec, name, record, collection=spec.many)
+            continue
+        if not spec.many and len(nodes) != 1:
+            raise ExtractionError(name, 'multiple', record=record)
+        values: list[object] = []
+        for index, target in enumerate(nodes):
+            item = index if spec.many else None
+            value = target.attrs.get(spec.attribute) if spec.attribute is not None else target.text
+            if value is None:
+                if spec.required:
+                    raise ExtractionError(name, 'attribute', record=record, item=item)
+                values.append(_fallback(spec, name, record))
+                continue
+            if spec.strip:
+                value = value.strip()
+            if spec.convert is not None:
+                try:
+                    values.append(spec.convert(value))
+                except Exception as error:
+                    raise ExtractionError(name, 'conversion', record=record, item=item) from error
+            else:
+                values.append(value)
+        result[name] = values if spec.many else values[0]
+    return result
+
+
+def extract(node: Node, fields: Mapping[str, Field]) -> dict[str, object]:
+    """Extract one record; no coercion occurs without a conversion callback."""
+    if not isinstance(node, Node):
+        raise TypeError('node must be a Node')
+    return _record(node, _schema(fields), None)
+
+
+def extract_all(node: Node, selector: str, fields: Mapping[str, Field]) -> list[dict[str, object]]:
+    """Extract records from selected descendants; error.record is zero-based.
+
+    This collects every record into a list. Use explicit iteration and extract()
+    when the caller needs incremental consumption or custom error handling.
+    """
+    if not isinstance(node, Node):
+        raise TypeError('node must be a Node')
+    schema = _schema(fields)
+    return [_record(target, schema, index) for index, target in enumerate(node.select(selector))]

astree/nodes.py

@@ -0,0 +1,145 @@
+"""Read-only HTML tree views and iterative extraction."""
+
+from collections.abc import Iterator, Mapping
+from types import MappingProxyType
+from typing import Literal
+
+type NodeKind = Literal['document', 'element', 'text', 'comment', 'declaration', 'processing_instruction']
+type AttributeFilter = str | bool | None
+
+
+class Node:
+    """A parser-owned node; public child and attribute collections are read-only."""
+
+    __slots__ = ('_kind', '_tag', '_attrs', '_parts', '_parent', '_children')
+
+    def __init__(
+        self, kind: NodeKind, *, tag: str | None = None,
+        attrs: Mapping[str, str | None] | None = None, data: str = '',
+        parent: Node | None = None,
+    ) -> None:
+        self._kind = kind
+        self._tag = tag
+        self._attrs = MappingProxyType(dict(attrs or {}))
+        self._parts = [data] if data else []
+        self._parent = parent
+        self._children: list[Node] = []
+
+    @property
+    def kind(self) -> NodeKind:
+        return self._kind
+
+    @property
+    def tag(self) -> str | None:
+        return self._tag
+
+    @property
+    def attrs(self) -> Mapping[str, str | None]:
+        return self._attrs
+
+    @property
+    def data(self) -> str:
+        return ''.join(self._parts)
+
+    @property
+    def parent(self) -> Node | None:
+        return self._parent
+
+    @property
+    def children(self) -> tuple[Node, ...]:
+        return tuple(self._children)
+
+    def descendants(self) -> Iterator[Node]:
+        """Visit every descendant in source order, excluding this node."""
+        pending = list(reversed(self._children))
+        while pending:
+            node = pending.pop()
+            yield node
+            pending.extend(reversed(node._children))
+
+    @staticmethod
+    def _filters(
+        tag: str | None, attrs: Mapping[str, AttributeFilter] | None,
+        attributes: Mapping[str, AttributeFilter],
+    ) -> tuple[str | None, dict[str, AttributeFilter]]:
+        if tag is not None and not isinstance(tag, str):
+            raise TypeError('tag must be a string or None')
+        filters = dict(attrs or {})
+        filters.update(attributes)
+        for name, value in filters.items():
+            if not isinstance(name, str) or not isinstance(value, (str, bool, type(None))):
+                raise TypeError('attribute filters require string names and str, bool, or None values')
+        return tag.lower() if tag is not None else None, filters
+
+    @staticmethod
+    def _matches(node: Node, tag: str | None, filters: Mapping[str, AttributeFilter]) -> bool:
+        if node.kind != 'element' or (tag is not None and node.tag != tag):
+            return False
+        for name, expected in filters.items():
+            token_match = name == 'class_'
+            key = 'class' if token_match else name.lower()
+            present = key in node.attrs
+            if expected is True:
+                if not present:
+                    return False
+            elif expected is False:
+                if present:
+                    return False
+            elif not present:
+                return False
+            elif token_match and isinstance(expected, str):
+                if expected not in (node.attrs[key] or '').split():
+                    return False
+            elif node.attrs[key] != expected:
+                return False
+        return True
+
+    def find_all(
+        self, tag: str | None = None, *, attrs: Mapping[str, AttributeFilter] | None = None,
+        **attributes: AttributeFilter,
+    ) -> list[Node]:
+        """Find descendant elements using exact attributes or class_ token matching."""
+        tag, filters = self._filters(tag, attrs, attributes)
+        return [node for node in self.descendants() if self._matches(node, tag, filters)]
+
+    def find(
+        self, tag: str | None = None, *, attrs: Mapping[str, AttributeFilter] | None = None,
+        **attributes: AttributeFilter,
+    ) -> Node | None:
+        """Return the first matching descendant element, or None."""
+        tag, filters = self._filters(tag, attrs, attributes)
+        return next((node for node in self.descendants() if self._matches(node, tag, filters)), None)
+
+    def get_text(self, separator: str = '', *, strip: bool = False, include_hidden: bool = False) -> str:
+        """Join text pieces, omitting script/style subtrees unless requested."""
+        if not isinstance(separator, str):
+            raise TypeError('separator must be a string')
+        pieces: list[str] = []
+        pending = [self]
+        while pending:
+            node = pending.pop()
+            if node.kind == 'text':
+                piece = node.data.strip() if strip else node.data
+                if piece:
+                    pieces.append(piece)
+            elif include_hidden or node.tag not in {'script', 'style'}:
+                pending.extend(reversed(node._children))
+        return separator.join(pieces)
+
+    @property
+    def text(self) -> str:
+        return self.get_text()
+
+    def select(self, selector: str) -> list[Node]:
+        """Select descendants with the documented CSS subset."""
+        from .selectors import select
+        return select(self, selector)
+
+    def select_one(self, selector: str) -> Node | None:
+        """Return the first selected descendant, or None."""
+        from .selectors import select
+        result = select(self, selector, first=True)
+        return result[0] if result else None
+
+    def __repr__(self) -> str:
+        return f'Node(kind={self.kind!r}, tag={self.tag!r})'

astree/parser.py

@@ -0,0 +1,158 @@
+"""Bounded, incremental HTMLParser adapters."""
+
+from html.parser import HTMLParser
+
+from .nodes import Node
+
+VOID_ELEMENTS = frozenset({'area', 'base', 'br', 'col', 'embed', 'hr', 'img', 'input',
+                           'link', 'meta', 'param', 'source', 'track', 'wbr'})
+
+
+class ParseLimitError(ValueError):
+    """An explicit parsing resource limit was exceeded."""
+
+
+def _positive(name: str, value: int) -> int:
+    if isinstance(value, bool) or not isinstance(value, int):
+        raise TypeError(f'{name} must be a positive integer')
+    if value <= 0:
+        raise ValueError(f'{name} must be a positive integer')
+    return value
+
+
+class _BoundedParser(HTMLParser):
+    """Shared single-use parser lifecycle; subclasses retain their own output."""
+
+    def __init__(self, *, max_chars: int = 10_000_000, max_nodes: int = 100_000,
+                 max_depth: int = 256) -> None:
+        self.max_chars = _positive('max_chars', max_chars)
+        self.max_nodes = _positive('max_nodes', max_nodes)
+        self.max_depth = _positive('max_depth', max_depth)
+        self._chars = 0
+        self._events = 0
+        self._closed = False
+        self._failed = False
+        super().__init__(convert_charrefs=True)
+
+    def reset(self) -> None:
+        # HTMLParser calls reset during construction. Reuse would desynchronize
+        # subclass output and input buffers, so it is deliberately unsupported.
+        if hasattr(self, 'rawdata'):
+            raise RuntimeError('parsers are single-use; construct a new parser')
+        super().reset()
+
+    def _available(self) -> None:
+        if self._closed or self._failed:
+            raise RuntimeError('parser is closed or failed')
+
+    def _count(self) -> None:
+        self._events += 1
+        if self._events > self.max_nodes:
+            raise ParseLimitError('max_nodes exceeded')
+
+    def feed(self, data: str) -> None:
+        self._available()
+        if not isinstance(data, str):
+            raise TypeError('HTML input must be a string')
+        try:
+            if self._chars + len(data) > self.max_chars:
+                raise ParseLimitError('max_chars exceeded')
+            self._chars += len(data)
+            super().feed(data)
+        except BaseException:
+            self._failed = True
+            raise
+
+    def close(self) -> None:
+        if self._closed:
+            return
+        self._available()
+        try:
+            super().close()
+            self._finish()
+        except BaseException:
+            self._failed = True
+            raise
+        self._closed = True
+
+    def _finish(self) -> None:
+        pass
+
+
+class Document(Node):
+    """A document tree that never performs network I/O or executes markup."""
+
+    def __init__(self) -> None:
+        super().__init__('document')
+
+    @classmethod
+    def from_html(cls, source: str, *, max_chars: int = 10_000_000,
+                  max_nodes: int = 100_000, max_depth: int = 256) -> Document:
+        parser = DocumentParser(max_chars=max_chars, max_nodes=max_nodes, max_depth=max_depth)
+        parser.feed(source)
+        parser.close()
+        return parser.document
+
+    @property
+    def title(self) -> str | None:
+        node = self.find('title')
+        return node.text.strip() if node is not None else None
+
+
+class DocumentParser(_BoundedParser):
+    """Incrementally build a read-only tree; inspect document after close()."""
+
+    def __init__(self, *, max_chars: int = 10_000_000, max_nodes: int = 100_000,
+                 max_depth: int = 256) -> None:
+        super().__init__(max_chars=max_chars, max_nodes=max_nodes, max_depth=max_depth)
+        self.document = Document()
+        self._stack: list[Node] = [self.document]
+
+    def _append(self, kind, *, tag=None, attrs=None, data='') -> Node:
+        self._count()
+        parent = self._stack[-1]
+        node = Node(kind, tag=tag, attrs=attrs, data=data, parent=parent)
+        parent._children.append(node)
+        return node
+
+    def handle_starttag(self, tag: str, attrs: list[tuple[str, str | None]]) -> None:
+        if len(self._stack) > self.max_depth:
+            raise ParseLimitError('max_depth exceeded')
+        node = self._append('element', tag=tag, attrs=dict(attrs))
+        if tag not in VOID_ELEMENTS:
+            self._stack.append(node)
+
+    def handle_startendtag(self, tag: str, attrs: list[tuple[str, str | None]]) -> None:
+        if len(self._stack) > self.max_depth:
+            raise ParseLimitError('max_depth exceeded')
+        self._append('element', tag=tag, attrs=dict(attrs))
+
+    def handle_endtag(self, tag: str) -> None:
+        for index in range(len(self._stack) - 1, 0, -1):
+            if self._stack[index].tag == tag:
+                del self._stack[index:]
+                break
+
+    def handle_data(self, data: str) -> None:
+        if not data:
+            return
+        children = self._stack[-1]._children
+        if children and children[-1].kind == 'text':
+            children[-1]._parts.append(data)
+        else:
+            self._append('text', data=data)
+
+    def handle_comment(self, data: str) -> None:
+        self._append('comment', data=data)
+
+    def handle_decl(self, decl: str) -> None:
+        self._append('declaration', data=decl)
+
+    def handle_pi(self, data: str) -> None:
+        self._append('processing_instruction', data=data)
+
+    def unknown_decl(self, data: str) -> None:
+        self._append('declaration', data=data)
+
+    def _finish(self) -> None:
+        self._stack = [self.document]

astree/selectors.py

@@ -0,0 +1,172 @@
+"""A deliberately small, strictly validated CSS selector subset."""
+
+from dataclasses import dataclass
+import re
+
+from .nodes import Node
+
+_IDENT = re.compile(r'-?[_a-zA-Z][_a-zA-Z0-9-]*')
+
+
+class SelectorSyntaxError(ValueError):
+    """A selector is malformed or uses syntax outside the supported subset."""
+
+
+@dataclass(frozen=True, slots=True)
+class _Compound:
+    tag: str | None
+    ids: tuple[str, ...]
+    classes: tuple[str, ...]
+    attrs: tuple[tuple[str, str | None], ...]
+
+    def matches(self, node: Node) -> bool:
+        if node.kind != 'element' or (self.tag is not None and node.tag != self.tag):
+            return False
+        classes = (node.attrs.get('class') or '').split()
+        return (all(node.attrs.get('id') == value for value in self.ids)
+                and all(value in classes for value in self.classes)
+                and all(name in node.attrs and (value is None or node.attrs[name] == value)
+                        for name, value in self.attrs))
+
+
+class _Grammar:
+    def __init__(self, source: str) -> None:
+        if not isinstance(source, str):
+            raise TypeError('selector must be a string')
+        if len(source) > 4096:
+            raise SelectorSyntaxError('selectors are limited to 4096 characters')
+        if '\\' in source:
+            raise SelectorSyntaxError('CSS escapes are not supported')
+        self.source = source
+        self.pos = 0
+
+    def peek(self) -> str:
+        return self.source[self.pos:self.pos + 1]
+
+    def space(self) -> bool:
+        start = self.pos
+        while self.peek() and self.peek().isspace():
+            self.pos += 1
+        return self.pos > start
+
+    def identifier(self) -> str:
+        match = _IDENT.match(self.source, self.pos)
+        if match is None:
+            raise SelectorSyntaxError(f'expected an ASCII identifier at position {self.pos}')
+        self.pos = match.end()
+        return match.group()
+
+    def attribute(self) -> tuple[str, str | None]:
+        self.pos += 1
+        self.space()
+        name = self.identifier().lower()
+        self.space()
+        value = None
+        if self.peek() == '=':
+            self.pos += 1
+            self.space()
+            if self.peek() in {'"', "'"}:
+                quote = self.peek()
+                self.pos += 1
+                end = self.source.find(quote, self.pos)
+                if end == -1:
+                    raise SelectorSyntaxError('unterminated attribute value')
+                value = self.source[self.pos:end]
+                self.pos = end + 1
+                if any(char in value for char in '\n\r\f'):
+                    raise SelectorSyntaxError('newlines in attribute strings are not supported')
+            else:
+                value = self.identifier()
+            self.space()
+        if self.peek() != ']':
+            raise SelectorSyntaxError(f'expected ] at position {self.pos}')
+        self.pos += 1
+        return name, value
+
+    def compound(self) -> _Compound:
+        start = self.pos
+        tag = None
+        ids: list[str] = []
+        classes: list[str] = []
+        attrs: list[tuple[str, str | None]] = []
+        if self.peek() == '*':
+            self.pos += 1
+        elif _IDENT.match(self.source, self.pos):
+            tag = self.identifier().lower()
+        while self.peek() in {'#', '.', '['}:
+            prefix = self.peek()
+            if prefix == '[':
+                attrs.append(self.attribute())
+            else:
+                self.pos += 1
+                (ids if prefix == '#' else classes).append(self.identifier())
+        if self.pos == start:
+            raise SelectorSyntaxError(f'expected a selector at position {self.pos}')
+        return _Compound(tag, tuple(ids), tuple(classes), tuple(attrs))
+
+    def parse(self) -> list[list[tuple[str, _Compound]]]:
+        groups: list[list[tuple[str, _Compound]]] = []
+        self.space()
+        group = [('', self.compound())]
+        count = 1
+        while True:
+            spaced = self.space()
+            char = self.peek()
+            if not char:
+                groups.append(group)
+                return groups
+            if char == ',':
+                groups.append(group)
+                group = []
+                relation = ''
+                self.pos += 1
+                self.space()
+            elif char == '>':
+                relation = 'child'
+                self.pos += 1
+                self.space()
+            elif spaced:
+                relation = 'descendant'
+            else:
+                raise SelectorSyntaxError(f'unsupported syntax at position {self.pos}')
+            count += 1
+            if count > 64:
+                raise SelectorSyntaxError('selectors are limited to 64 compound parts')
+            group.append((relation, self.compound()))
+
+
+def _matches(node: Node, group: list[tuple[str, _Compound]], scope: Node) -> bool:
+    # Backtrack descendant alternatives: the nearest matching ancestor may fail
+    # an earlier child constraint. Memoization bounds repeated ancestor states.
+    pending = [(node, len(group) - 1)]
+    visited: set[tuple[Node, int]] = set()
+    while pending:
+        current, index = pending.pop()
+        if (current, index) in visited:
+            continue
+        visited.add((current, index))
+        relation, compound = group[index]
+        if not compound.matches(current):
+            continue
+        if index == 0:
+            return True
+        if current is scope:
+            continue
+        parent = current.parent
+        while parent is not None:
+            pending.append((parent, index - 1))
+            if relation == 'child' or parent is scope:
+                break
+            parent = parent.parent
+    return False
+
+
+def select(scope: Node, selector: str, *, first: bool = False) -> list[Node]:
+    groups = _Grammar(selector).parse()
+    result: list[Node] = []
+    for node in scope.descendants():
+        if node.kind == 'element' and any(_matches(node, group, scope) for group in groups):
+            result.append(node)
+            if first:
+                break
+    return result

astree-0.1.0.dist-info/METADATA

@@ -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.dist-info/RECORD

@@ -0,0 +1,11 @@
+astree/__init__.py,sha256=cZnAe9MSHz3wQbf0m9zc7aRIajR_1wtWe7om3rSH3qw,608
+astree/collectors.py,sha256=tHgPLtiWwwZHi7_eRsNXmDyhMVtrXKRP8MX6ENby2qY,5445
+astree/extract.py,sha256=-N3gRqLiD4-XSGXgJGmIsz1bRjlen_t6BTN_m2AR6es,5997
+astree/nodes.py,sha256=akufzADDO78Pzh-2QkXOgYvY5jGc4JFGwfy-iYI08EM,5490
+astree/parser.py,sha256=UMcE3Ne4xDDslhs-oGBBOdN96SzJaeAzPcqTxk0HmA8,5489
+astree/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+astree/selectors.py,sha256=HP7rxkhg1HMZEzVFe1H4JqIuzNAz56PD2AChryancMI,6082
+astree-0.1.0.dist-info/licenses/LICENSE,sha256=pAeG0B2X4uxLV9iLuLxEEk4YSQamiNrWf4E6P5vch1Q,1069
+astree-0.1.0.dist-info/WHEEL,sha256=MWx7psoF7KNST9G72pGtiBYuaXRXQXBk9pw5R6FzYko,80
+astree-0.1.0.dist-info/METADATA,sha256=Vkgv-Jeb_2z39QOzfDzuIrt07MLmqb6jiWziZNT0DFE,2883
+astree-0.1.0.dist-info/RECORD,,

astree-0.1.0.dist-info/WHEEL

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

astree-0.1.0.dist-info/licenses/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.