confext 0.7.2__tar.gz

confext-0.7.2/LICENSE

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

confext-0.7.2/PKG-INFO

@@ -0,0 +1,145 @@
+Metadata-Version: 2.4
+Name: confext
+Version: 0.7.2
+Summary: Stdlib HTML parsing into a tree model
+Author-email: kinishuki <kinishuki@gmail.com>
+License: MIT
+Keywords: html,parser,tree
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.8
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Text Processing :: Markup :: HTML
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Dynamic: license-file
+
+## Quick start
+
+```python
+import confext
+
+html = '''
+<!DOCTYPE html>
+<html><body>
+  <div id="main" class="wrap card">
+    <p class="lead">Hello <b>world</b></p>
+    <ul><li>1</li><li>2</li></ul>
+  </div>
+</body></html>
+'''
+
+doc = confext.parse(html)              # -> parse html
+doc.doctype                            # '<!DOCTYPE html>'
+doc.stats()                            # {'elements': 7, 'comments': 0, 'max_depth': 4}
+doc.to_html()                          # serialized markup
+doc.root.iter_elements()               # walk every element node
+```
+
+## API
+
+### Functions
+
+| Function | Description |
+|---|---|
+| `parse(html)` | Parse `str` or `bytes` into a `ParsedDocument` using the default engine. |
+
+That is the whole module-level API, confext is a parser, nothing else.
+
+### ParsedDocument
+
+| Member | Description |
+|---|---|
+| `to_html()` | Re-serialize the tree. |
+| `stats()` | `{'elements', 'comments', 'max_depth'}`. |
+| `to_dict()` | `{'doctype', 'stats', 'html', 'errors'}`. |
+| `doctype`, `root`, `comments`, `errors` | Raw parse artifacts. |
+
+### Node
+
+`tag`, `attrs`, `parent`, `children` (mix of `Node`s and text `str`s),
+plus: `get_attr`, `has_class`, `append_child`, `remove`, `text_content`,
+`iter_elements`, `to_html`, `to_dict`.
+
+### Engine
+
+For isolated runs with a custom config and no global state:
+
+```python
+from confext import Engine, ConfextError
+
+engine = Engine({'strict_mode': True})
+doc = engine.parse('<div><p>ok</p></div>')
+engine.parse('<div><p>oops</div>')   # raises ConfextError in strict mode
+```
+
+Also accepts `use_cache=False` to disable document memoization
+(`cache_size` is clamped to a minimum of 1).
+
+## Configuration
+
+`DEFAULT_CONFIG` is a plain dict; `Engine(config)` merges over it.
+Settings can also be persisted to and loaded from a `default.config`
+file:
+
+```python
+from confext import Config, load_config, save_config
+
+cfg = load_config()                    # finds the caller's default.config
+cfg.get('max_depth')                   # user setting layered over defaults
+save_config(cfg, 'default.config', compression='xz')
+```
+
+The binary layout is `[8-byte sha256][4-byte size][payload]`, where
+the payload is a raw, lzma (xz), or zlib compressed payload of a
+plain-data dict. Size and checksum are verified before decompression
+and unpickling; both checks run before any decompression is
+attempted. Failures raise `ConfigLoadError`, `ConfigChecksumError`,
+or `ConfigDecompressError`.
+
+| Key | Default | Used by |
+|---|---|---|
+| `encoding` | `'utf-8'` | Fallback when bytes input has no BOM / `<meta charset>`. |
+| `max_depth` | `100` | Element nesting cap (deeper nodes are dropped). |
+| `max_file_size_mb` | `10` | Input size cap; parse raises `ConfextError` beyond it. |
+| `cache_size` | `50` | LRU capacity for parsed documents. |
+| `strict_mode` | `False` | If true, malformed HTML (unclosed/stray tags) raises. |
+| `strip_whitespace` | `True` | Collapse whitespace runs in text nodes at parse time. |
+| `preserve_comments` | `False` | Keep comments in the tree (always captured in `doc.comments`). |
+
+Output and sanitize keys (`remove_comments`, `pretty_indent`,
+`allowed_tags`, …) are consumed by paster, not confext.
+
+## Errors
+
+```
+ConfextError  parse failures, strict-mode violations (unclosed/
+                  stray tags and depth-limit breaches — deeper nodes
+                  are silently dropped outside strict mode) and
+                  size-limit breaches
+```
+
+Invalid selectors now raise paster's `SelectorSyntaxError`.
+
+## Layout
+
+```
+confext/
+├── __init__.py     public API: parse; re-exports Engine,
+│                   DEFAULT_CONFIG, ConfextError, Node,
+│                   ParsedDocument, VOID_ELEMENTS, Config,
+│                   load_config/save_config, config errors
+├── errors.py       ConfextError, ConfigLoadError family
+├── tree.py         Node, ParsedDocument (tree model + stats)
+├── reader.py       encoding detection, TreeBuilder (stdlib tokenizer)
+├── engine.py       Engine, DEFAULT_CONFIG, LRU cache
+└── config.py       Config, load_config/save_config (default.config)
+```

confext-0.7.2/README.md

@@ -0,0 +1,121 @@
+## Quick start
+
+```python
+import confext
+
+html = '''
+<!DOCTYPE html>
+<html><body>
+  <div id="main" class="wrap card">
+    <p class="lead">Hello <b>world</b></p>
+    <ul><li>1</li><li>2</li></ul>
+  </div>
+</body></html>
+'''
+
+doc = confext.parse(html)              # -> parse html
+doc.doctype                            # '<!DOCTYPE html>'
+doc.stats()                            # {'elements': 7, 'comments': 0, 'max_depth': 4}
+doc.to_html()                          # serialized markup
+doc.root.iter_elements()               # walk every element node
+```
+
+## API
+
+### Functions
+
+| Function | Description |
+|---|---|
+| `parse(html)` | Parse `str` or `bytes` into a `ParsedDocument` using the default engine. |
+
+That is the whole module-level API, confext is a parser, nothing else.
+
+### ParsedDocument
+
+| Member | Description |
+|---|---|
+| `to_html()` | Re-serialize the tree. |
+| `stats()` | `{'elements', 'comments', 'max_depth'}`. |
+| `to_dict()` | `{'doctype', 'stats', 'html', 'errors'}`. |
+| `doctype`, `root`, `comments`, `errors` | Raw parse artifacts. |
+
+### Node
+
+`tag`, `attrs`, `parent`, `children` (mix of `Node`s and text `str`s),
+plus: `get_attr`, `has_class`, `append_child`, `remove`, `text_content`,
+`iter_elements`, `to_html`, `to_dict`.
+
+### Engine
+
+For isolated runs with a custom config and no global state:
+
+```python
+from confext import Engine, ConfextError
+
+engine = Engine({'strict_mode': True})
+doc = engine.parse('<div><p>ok</p></div>')
+engine.parse('<div><p>oops</div>')   # raises ConfextError in strict mode
+```
+
+Also accepts `use_cache=False` to disable document memoization
+(`cache_size` is clamped to a minimum of 1).
+
+## Configuration
+
+`DEFAULT_CONFIG` is a plain dict; `Engine(config)` merges over it.
+Settings can also be persisted to and loaded from a `default.config`
+file:
+
+```python
+from confext import Config, load_config, save_config
+
+cfg = load_config()                    # finds the caller's default.config
+cfg.get('max_depth')                   # user setting layered over defaults
+save_config(cfg, 'default.config', compression='xz')
+```
+
+The binary layout is `[8-byte sha256][4-byte size][payload]`, where
+the payload is a raw, lzma (xz), or zlib compressed payload of a
+plain-data dict. Size and checksum are verified before decompression
+and unpickling; both checks run before any decompression is
+attempted. Failures raise `ConfigLoadError`, `ConfigChecksumError`,
+or `ConfigDecompressError`.
+
+| Key | Default | Used by |
+|---|---|---|
+| `encoding` | `'utf-8'` | Fallback when bytes input has no BOM / `<meta charset>`. |
+| `max_depth` | `100` | Element nesting cap (deeper nodes are dropped). |
+| `max_file_size_mb` | `10` | Input size cap; parse raises `ConfextError` beyond it. |
+| `cache_size` | `50` | LRU capacity for parsed documents. |
+| `strict_mode` | `False` | If true, malformed HTML (unclosed/stray tags) raises. |
+| `strip_whitespace` | `True` | Collapse whitespace runs in text nodes at parse time. |
+| `preserve_comments` | `False` | Keep comments in the tree (always captured in `doc.comments`). |
+
+Output and sanitize keys (`remove_comments`, `pretty_indent`,
+`allowed_tags`, …) are consumed by paster, not confext.
+
+## Errors
+
+```
+ConfextError  parse failures, strict-mode violations (unclosed/
+                  stray tags and depth-limit breaches — deeper nodes
+                  are silently dropped outside strict mode) and
+                  size-limit breaches
+```
+
+Invalid selectors now raise paster's `SelectorSyntaxError`.
+
+## Layout
+
+```
+confext/
+├── __init__.py     public API: parse; re-exports Engine,
+│                   DEFAULT_CONFIG, ConfextError, Node,
+│                   ParsedDocument, VOID_ELEMENTS, Config,
+│                   load_config/save_config, config errors
+├── errors.py       ConfextError, ConfigLoadError family
+├── tree.py         Node, ParsedDocument (tree model + stats)
+├── reader.py       encoding detection, TreeBuilder (stdlib tokenizer)
+├── engine.py       Engine, DEFAULT_CONFIG, LRU cache
+└── config.py       Config, load_config/save_config (default.config)
+```

confext-0.7.2/confext/__init__.py

@@ -0,0 +1,34 @@
+from .errors import (
+    ConfigChecksumError,
+    ConfigDecompressError,
+    ConfigLoadError,
+    ConfextError,
+)
+from .tree import VOID_ELEMENTS, Node, ParsedDocument
+from .engine import DEFAULT_CONFIG, Engine
+from .config import Config, find_default_config, load_config, save_config
+
+_default_engine = Engine()
+
+
+def parse(html):
+    """Parse HTML into a ParsedDocument using the default engine."""
+    return _default_engine.parse(html)
+
+
+__all__ = [
+    'Engine',
+    'Node',
+    'ParsedDocument',
+    'ConfextError',
+    'DEFAULT_CONFIG',
+    'VOID_ELEMENTS',
+    'parse',
+    'Config',
+    'load_config',
+    'save_config',
+    'find_default_config',
+    'ConfigLoadError',
+    'ConfigChecksumError',
+    'ConfigDecompressError',
+]

confext-0.7.2/confext/config.py

@@ -0,0 +1,238 @@
+"""Configuration loading and persistence for the parser package.
+
+Config files use a strict binary layout:
+
+    raw:   [8-byte sha256 checksum][4-byte size][pickle payload]
+    xz:    [8-byte sha256 checksum][4-byte size][lzma.compress(pickle payload)]
+    zlib:  [8-byte sha256 checksum][4-byte size][zlib.compress(pickle payload)]
+
+The size field is the big-endian length of the stored payload (compressed
+length when xz/zlib is used). Load order: verify size -> verify checksum
+-> detect compression -> decompress if needed -> unpickle. Both checks run
+before decompression is attempted.
+"""
+
+import hashlib
+import importlib.util
+import lzma
+import os
+import pickle
+import sys
+import tempfile
+import zlib
+from pathlib import Path
+from typing import Any, Dict, Optional, Tuple, Union
+
+from .engine import DEFAULT_CONFIG
+from .errors import ConfigChecksumError, ConfigDecompressError, ConfigLoadError
+
+PathLike = Union[str, os.PathLike]
+
+_CHECKSUM_SIZE = 8
+_SIZE_SIZE = 4
+_HEADER_SIZE = _CHECKSUM_SIZE + _SIZE_SIZE
+
+CONFIG_NAME = 'default.config'
+
+
+def _checksum(payload: bytes) -> bytes:
+    """First _CHECKSUM_SIZE bytes of the sha256 digest of payload."""
+    return hashlib.sha256(payload).digest()[:_CHECKSUM_SIZE]
+
+
+def _detect_compression(data: bytes) -> Optional[Tuple[str, Any]]:
+    """Detect compression format by magic bytes. Returns (name, module) or None.
+
+    zlib has no magic number; it is detected last by validating its CMF/FLG
+    header (deflate method, CINFO <= 7, no preset dictionary, header value
+    divisible by 31).
+    """
+    if data[:6] == b'\xfd7zXZ\x00':
+        return 'xz', lzma
+    if (
+        len(data) >= 2
+        and data[0] & 0x0F == 8
+        and data[0] >> 4 <= 7
+        and not data[1] & 0x20
+        and ((data[0] << 8) | data[1]) % 31 == 0
+    ):
+        return 'zlib', zlib
+    return None
+
+
+def _verify_header(data: bytes, path: PathLike) -> bytes:
+    """Verify the 8-byte sha256 and 4-byte size header; return the payload."""
+    if len(data) < _HEADER_SIZE:
+        raise ConfigLoadError(
+            f"config file '{path}' is too short to be a valid config file"
+        )
+    stored = data[:_CHECKSUM_SIZE]
+    size = int.from_bytes(data[_CHECKSUM_SIZE:_HEADER_SIZE], 'big')
+    payload = data[_HEADER_SIZE:]
+    if len(payload) != size:
+        raise ConfigLoadError(
+            f"size mismatch in config file '{path}': file truncated or "
+            f"tampered with; expected {size} payload bytes, got {len(payload)}"
+        )
+    if _checksum(payload) != stored:
+        raise ConfigChecksumError(
+            f"checksum mismatch in config file '{path}': file may be corrupted "
+            "or tampered with; files written by older versions are not accepted"
+        )
+    return payload
+
+
+def _sanitize_value(value: Any) -> Any:
+    """Recursively verify that a value only contains allowed plain types."""
+    if isinstance(value, (str, bytes, int, float, bool, type(None))):
+        return value
+    if isinstance(value, dict):
+        return {str(key): _sanitize_value(item) for key, item in value.items()}
+    if isinstance(value, (list, tuple)):
+        return [_sanitize_value(item) for item in value]
+    if isinstance(value, (set, frozenset)):
+        return {_sanitize_value(item) for item in value}
+    raise ConfigLoadError(
+        f'disallowed type {type(value).__name__!r} in config file; '
+        'only plain data types are allowed'
+    )
+
+
+class Config:
+    """Configuration holder that layers user settings over DEFAULT_CONFIG."""
+
+    def __init__(self, settings: Optional[Dict[str, Any]] = None):
+        self._settings: Dict[str, Any] = {**DEFAULT_CONFIG, **(settings or {})}
+
+    def get(self, key: str, default: Any = None) -> Any:
+        return self._settings.get(key, default)
+
+    def update(self, settings: Dict[str, Any]) -> 'Config':
+        """Return a new Config with extra settings layered on top of this one."""
+        return Config({**self._settings, **(settings or {})})
+
+    def to_dict(self) -> Dict[str, Any]:
+        return dict(self._settings)
+
+    @classmethod
+    def load_default(cls) -> 'Config':
+        """Return a Config built from DEFAULT_CONFIG without reading any file."""
+        return cls()
+
+    def __eq__(self, other: Any) -> bool:
+        if isinstance(other, Config):
+            return self._settings == other._settings
+        return NotImplemented
+
+    def __repr__(self) -> str:
+        return f'Config({self._settings})'
+
+
+def _read_config(path: PathLike) -> Dict[str, Any]:
+    """Read config bytes from path."""
+    try:
+        with open(path, 'rb') as handle:
+            data = handle.read()
+    except Exception as exc:
+        raise ConfigLoadError(f"failed to read config file '{path}': {exc}") from exc
+
+    blob = _verify_header(data, path)
+
+    detected = _detect_compression(blob)
+    if detected is not None:
+        name, module = detected
+        try:
+            blob = module.decompress(blob)
+        except Exception as exc:
+            raise ConfigDecompressError(
+                f"failed to decompress {name} config file '{path}': {exc}"
+            ) from exc
+
+    try:
+        loaded = pickle.loads(blob)
+    except Exception as exc:
+        raise ConfigLoadError(
+            f"failed to load pickle payload from '{path}': {exc}"
+        ) from exc
+    if not isinstance(loaded, dict):
+        raise ConfigLoadError(
+            f"config file '{path}' must contain a dict, "
+            f"got {type(loaded).__name__}"
+        )
+    return _sanitize_value(loaded)
+
+
+def load_config(path: Optional[PathLike] = None) -> Config:
+    """Load a Config from an explicit file, or the caller's default.config."""
+    if path is None:
+        path = _locate_config(sys._getframe(1).f_globals)
+    return Config(_read_config(path))
+
+
+def save_config(
+    config: Union[Config, Dict[str, Any]],
+    path: Optional[PathLike] = None,
+    compression: Optional[str] = None,
+) -> Path:
+    """Persist settings to path atomically; no path auto-finds default.config."""
+    if compression not in (None, 'xz', 'zlib'):
+        raise ValueError(
+            f"unsupported compression {compression!r}; expected 'xz', 'zlib' or None"
+        )
+
+    if path is None:
+        path = _locate_config(sys._getframe(1).f_globals)
+
+    if isinstance(config, Config):
+        settings = config.to_dict()
+    else:
+        settings = Config(config).to_dict()
+    payload = pickle.dumps(settings, protocol=pickle.HIGHEST_PROTOCOL)
+    if compression == 'xz':
+        payload = lzma.compress(payload)
+    elif compression == 'zlib':
+        payload = zlib.compress(payload)
+    blob = _checksum(payload) + len(payload).to_bytes(_SIZE_SIZE, 'big') + payload
+
+    target = Path(path)
+    if not target.parent.exists():
+        target.parent.mkdir(parents=True, exist_ok=True)
+
+    fd, tmp_name = tempfile.mkstemp(dir=str(target.parent), suffix='.config.tmp')
+    try:
+        with os.fdopen(fd, 'wb') as handle:
+            handle.write(blob)
+        os.replace(tmp_name, str(target))
+    except Exception:
+        try:
+            os.unlink(tmp_name)
+        except OSError:
+            pass
+        raise
+    return target
+
+def _locate_config(g: Dict[str, Any]) -> Path:
+    """Resolve the default.config path for a module globals mapping."""
+    file = g.get('__file__')
+    if file:
+        candidate = Path(os.path.abspath(file)).parent / CONFIG_NAME
+        if candidate.exists():
+            return candidate
+    package = g.get('__package__') or g.get('__name__', '').partition('.')[0]
+    if package:
+        try:
+            spec = importlib.util.find_spec(package)
+        except (ImportError, AttributeError, ValueError):
+            spec = None
+        if spec and spec.submodule_search_locations:
+            return Path(spec.submodule_search_locations[0]) / CONFIG_NAME
+    raise ConfigLoadError(f'no {CONFIG_NAME} found for caller')
+
+
+def find_default_config() -> Path:
+    """Locate the caller's default.config without loading it.
+
+    Searches the caller's module directory first, then the caller's
+    package directory. Raises ConfigLoadError when neither can be resolved.
+    """
+    return _locate_config(sys._getframe(1).f_globals)

confext-0.7.2/confext/engine.py

@@ -0,0 +1,101 @@
+"""Engine: the configured parsing facade with document caching."""
+
+import hashlib
+from typing import Any, Dict, Optional, Union
+
+from collections import OrderedDict
+
+from .errors import ConfextError
+from .reader import TreeBuilder, detect_encoding, extract_doctype
+from .tree import Node, ParsedDocument
+
+DEFAULT_CONFIG: Dict[str, Any] = {
+    'encoding': 'utf-8',
+    'max_depth': 100,
+    'max_file_size_mb': 10,
+    'cache_size': 50,
+    'strict_mode': False,
+    'strip_whitespace': True,
+    'preserve_comments': False,
+}
+
+
+class LRUCache:
+    """Tiny LRU cache used to memoize parsed documents."""
+
+    def __init__(self, max_size: int) -> None:
+        self._max_size = max(int(max_size), 1)
+        self._data: 'OrderedDict[str, Any]' = OrderedDict()
+
+    def get(self, key: str) -> Any:
+        if key in self._data:
+            self._data.move_to_end(key)
+            return self._data[key]
+        return None
+
+    def set(self, key: str, value: Any) -> None:
+        self._data[key] = value
+        self._data.move_to_end(key)
+        while len(self._data) > self._max_size:
+            self._data.popitem(last=False)
+
+
+class Engine:
+    """High-level HTML parsing engine configured by a plain dict."""
+
+    def __init__(self, config: Optional[Dict[str, Any]] = None,
+                 use_cache: bool = True) -> None:
+        self.config: Dict[str, Any] = dict(DEFAULT_CONFIG)
+        if config:
+            self.config.update(config)
+        self.cache: Optional[LRUCache] = None
+        if use_cache:
+            self.cache = LRUCache(
+                max_size=int(self.config.get('cache_size', 50) or 50)
+            )
+
+    def parse(self, html: Union[str, bytes]) -> ParsedDocument:
+        """Parse HTML (str or bytes) into a ParsedDocument."""
+        if isinstance(html, bytes):
+            encoding = detect_encoding(
+                html,
+                default=str(self.config.get('encoding', 'utf-8') or 'utf-8'),
+            )
+            html = html.decode(encoding, errors='replace')
+        key = hashlib.sha256(html.encode('utf-8', errors='replace')).hexdigest()
+        if self.cache is not None:
+            cached = self.cache.get(key)
+            if cached is not None:
+                return cached
+        self._check_size(html)
+        builder = TreeBuilder(self.config)
+        try:
+            builder.feed(html)
+            builder.close()
+        except ConfextError:
+            raise
+        except Exception as exc:
+            raise ConfextError(f'failed to parse HTML: {exc}') from exc
+        if bool(self.config.get('strict_mode', False)) and builder.errors:
+            summary = '; '.join(builder.errors[:5])
+            raise ConfextError(f'malformed HTML (strict mode): {summary}')
+        doc = ParsedDocument(
+            doctype=extract_doctype(html),
+            root=builder.root,
+            comments=builder.comments,
+            config=self.config,
+            errors=builder.errors,
+        )
+        if self.cache is not None:
+            self.cache.set(key, doc)
+        return doc
+
+    def _check_size(self, html: str) -> None:
+        cap = self.config.get('max_file_size_mb', 10)
+        if not cap:
+            return
+        size_mb = len(html.encode('utf-8', errors='replace')) / (1024 * 1024)
+        if size_mb > float(cap):
+            raise ConfextError(
+                f'input of {size_mb:.2f} MB exceeds max_file_size_mb={cap}'
+            )

confext-0.7.2/confext/errors.py

@@ -0,0 +1,19 @@
+class ConfextError(Exception):
+    """Raised when HTML cannot be parsed, a selector is invalid, or a
+    parse/sanitize limit is exceeded."""
+
+
+class ConfigLoadError(Exception):
+    """Raised when a config file is missing, unreadable, malformed,
+    unsafe, or not discoverable."""
+
+
+class ConfigChecksumError(ConfigLoadError):
+    """Raised when a config payload does not match its stored checksum."""
+
+    def __init__(self, message: str):
+        super().__init__(message)
+
+
+class ConfigDecompressError(ConfigLoadError):
+    """Raised when a compressed config payload cannot be decompressed."""

confext-0.7.2/confext/reader.py

@@ -0,0 +1,118 @@
+"""HTML tokenizing, encoding detection, and tree building."""
+
+import codecs
+import re
+from html.parser import HTMLParser as _BaseHTMLParser
+from typing import Any, Dict, List, Optional
+
+from .tree import COMMENT_TAG, ROOT_TAG, VOID_ELEMENTS, Node
+
+_META_CHARSET = re.compile(
+    r'<meta[^>]+charset\s*=\s*["\']?\s*([\w.:+-]+)', re.IGNORECASE
+)
+
+
+def detect_encoding(data: bytes, default: str = 'utf-8') -> str:
+    """Detect the encoding of raw HTML: BOM sniff, then <meta charset>."""
+    if data.startswith(codecs.BOM_UTF8):
+        return 'utf-8-sig'
+    if data.startswith((codecs.BOM_UTF32_LE, codecs.BOM_UTF32_BE)):
+        return 'utf-32'
+    if data.startswith((codecs.BOM_UTF16_LE, codecs.BOM_UTF16_BE)):
+        return 'utf-16'
+    head = data[:2048].decode('latin-1', errors='ignore')
+    match = _META_CHARSET.search(head)
+    if match:
+        try:
+            codecs.lookup(match.group(1))
+            return match.group(1)
+        except LookupError:
+            pass
+    return default
+
+
+def extract_doctype(html: str) -> Optional[str]:
+    match = re.search(r'<!DOCTYPE[^>]*>', html, re.IGNORECASE)
+    return match.group(0) if match else None
+
+
+class TreeBuilder(_BaseHTMLParser):
+    """Builds a Node tree from HTML using the stdlib tokenizer."""
+
+    def __init__(self, config: Dict[str, Any]) -> None:
+        super().__init__(convert_charrefs=True)
+        self.config = config
+        self.root = Node(ROOT_TAG)
+        self._stack: List[Node] = [self.root]
+        self.comments: List[str] = []
+        self.errors: List[str] = []
+        self._max_depth = int(config.get('max_depth', 100) or 100)
+        self._preserve_comments = bool(config.get('preserve_comments', False))
+        self._strip_whitespace = bool(config.get('strip_whitespace', True))
+        self._strict = bool(config.get('strict_mode', False))
+
+    def _current(self) -> Node:
+        return self._stack[-1]
+
+    def _attach(self, node: Node) -> None:
+        parent = self._current()
+        if len(self._stack) <= self._max_depth:
+            parent.children.append(node)
+            node.parent = parent
+        elif self._strict:
+            self.errors.append(
+                f'<{node.tag}> exceeds max_depth={self._max_depth}'
+            )
+        self._stack.append(node)
+
+    def handle_starttag(self, tag, attrs) -> None:
+        node = Node(tag, {k: (v if v is not None else '') for k, v in attrs})
+        self._attach(node)
+        if tag in VOID_ELEMENTS:
+            self._stack.pop()
+
+    def handle_startendtag(self, tag, attrs) -> None:
+        node = Node(tag, {k: (v if v is not None else '') for k, v in attrs})
+        if len(self._stack) <= self._max_depth:
+            parent = self._current()
+            parent.children.append(node)
+            node.parent = parent
+
+    def handle_endtag(self, tag) -> None:
+        if tag in VOID_ELEMENTS:
+            return
+        for i in range(len(self._stack) - 1, 0, -1):
+            if self._stack[i].tag == tag:
+                if len(self._stack) - 1 > i:
+                    unclosed = [n.tag for n in self._stack[i + 1:]]
+                    self.errors.append(
+                        f'unclosed tag(s) <{"> <".join(unclosed)}> before </{tag}>'
+                    )
+                del self._stack[i:]
+                return
+        self.errors.append(f'closing tag </{tag}> has no matching open tag')
+
+    def handle_data(self, data) -> None:
+        if not data:
+            return
+        if self._strip_whitespace:
+            data = re.sub(r'\s+', ' ', data)
+        self._current().children.append(data)
+
+    def handle_comment(self, data) -> None:
+        self.comments.append(data)
+        if self._preserve_comments:
+            comment = Node(COMMENT_TAG)
+            comment.children.append(data)
+            if len(self._stack) <= self._max_depth:
+                parent = self._current()
+                parent.children.append(comment)
+                comment.parent = parent
+
+    def close(self) -> None:
+        super().close()
+        if len(self._stack) > 1:
+            unclosed = [n.tag for n in self._stack[1:]]
+            self.errors.append(
+                f'unclosed tag(s) at end of input: <{"> <".join(unclosed)}>'
+            )

confext-0.7.2/confext/tree.py

@@ -0,0 +1,146 @@
+"""Tree data model: Node and ParsedDocument."""
+
+import re
+from html import escape as _escape
+from typing import Any, Dict, Iterator, List, Optional
+
+VOID_ELEMENTS = {
+    'area', 'base', 'br', 'col', 'embed', 'hr', 'img', 'input',
+    'link', 'meta', 'param', 'source', 'track', 'wbr',
+}
+
+ROOT_TAG = ':root'
+COMMENT_TAG = ':comment'
+
+_WS = re.compile(r'\s+')
+
+
+def normalize_ws(text: str) -> str:
+    return _WS.sub(' ', text)
+
+
+def format_attrs(attrs: Dict[str, str]) -> str:
+    return ''.join(
+        f' {name}' if value == '' else f' {name}="{_escape(value, quote=True)}"'
+        for name, value in attrs.items()
+    )
+
+
+class Node:
+    """A single element or comment node in the parsed HTML tree."""
+
+    def __init__(self, tag: str, attrs: Optional[Dict[str, str]] = None,
+                 parent: Optional['Node'] = None) -> None:
+        self.tag = tag
+        self.attrs: Dict[str, str] = dict(attrs or {})
+        self.children: List[Any] = []
+        self.parent: Optional[Node] = parent
+
+    @property
+    def is_comment(self) -> bool:
+        return self.tag == COMMENT_TAG
+
+    def get_attr(self, name: str, default: Optional[str] = None) -> Optional[str]:
+        return self.attrs.get(name, default)
+
+    def has_class(self, name: str) -> bool:
+        return name in (self.get_attr('class') or '').split()
+
+    def append_child(self, node: 'Node') -> 'Node':
+        if node.parent is not None:
+            node.parent.children.remove(node)
+        self.children.append(node)
+        node.parent = self
+        return self
+
+    def remove(self) -> 'Node':
+        if self.parent is not None:
+            self.parent.children.remove(self)
+            self.parent = None
+        return self
+
+    def text_content(self) -> str:
+        parts: List[str] = []
+        for child in self.children:
+            parts.append(child if isinstance(child, str) else child.text_content())
+        return ''.join(parts)
+
+    def iter_elements(self) -> Iterator['Node']:
+        for child in self.children:
+            if isinstance(child, Node) and not child.is_comment:
+                yield child
+                yield from child.iter_elements()
+
+    def to_html(self) -> str:
+        if self.is_comment:
+            return f'<!--{self.text_content()}-->'
+        attrs = format_attrs(self.attrs)
+        if self.tag in VOID_ELEMENTS:
+            return f'<{self.tag}{attrs}>'
+        inner = ''.join(
+            child if isinstance(child, str) else child.to_html()
+            for child in self.children
+        )
+        return f'<{self.tag}{attrs}>{inner}</{self.tag}>'
+
+    def to_dict(self) -> Dict[str, Any]:
+        return {
+            'tag': self.tag,
+            'attrs': dict(self.attrs),
+            'text': normalize_ws(self.text_content()).strip(),
+            'html': self.to_html(),
+        }
+
+    def __repr__(self) -> str:
+        return f'<Node {self.tag}>'
+
+
+class ParsedDocument:
+    """Structured result of parsing an HTML document."""
+
+    def __init__(self, doctype: Optional[str], root: Node,
+                 comments: Optional[List[str]] = None,
+                 config: Optional[Dict[str, Any]] = None,
+                 errors: Optional[List[str]] = None) -> None:
+        self.doctype = doctype
+        self.root = root
+        self.comments: List[str] = comments or []
+        self.errors: List[str] = errors or []
+        self.config: Dict[str, Any] = config or {}
+
+    def to_html(self) -> str:
+        return ''.join(
+            child if isinstance(child, str) else child.to_html()
+            for child in self.root.children
+        )
+
+    def stats(self) -> Dict[str, int]:
+        element_count = 0
+        max_depth = 0
+
+        def walk(node: Node, depth: int) -> None:
+            nonlocal element_count, max_depth
+            for child in node.children:
+                if isinstance(child, Node) and not child.is_comment:
+                    element_count += 1
+                    if depth + 1 > max_depth:
+                        max_depth = depth + 1
+                    walk(child, depth + 1)
+
+        walk(self.root, 0)
+        return {
+            'elements': element_count,
+            'comments': len(self.comments),
+            'max_depth': max_depth,
+        }
+
+    def to_dict(self) -> Dict[str, Any]:
+        return {
+            'doctype': self.doctype,
+            'stats': self.stats(),
+            'html': self.to_html(),
+            'errors': list(self.errors),
+        }
+
+    def __repr__(self) -> str:
+        return f'<ParsedDocument {self.stats()["elements"]} elements>'

confext-0.7.2/confext.egg-info/PKG-INFO

@@ -0,0 +1,145 @@
+Metadata-Version: 2.4
+Name: confext
+Version: 0.7.2
+Summary: Stdlib HTML parsing into a tree model
+Author-email: kinishuki <kinishuki@gmail.com>
+License: MIT
+Keywords: html,parser,tree
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.8
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Text Processing :: Markup :: HTML
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Dynamic: license-file
+
+## Quick start
+
+```python
+import confext
+
+html = '''
+<!DOCTYPE html>
+<html><body>
+  <div id="main" class="wrap card">
+    <p class="lead">Hello <b>world</b></p>
+    <ul><li>1</li><li>2</li></ul>
+  </div>
+</body></html>
+'''
+
+doc = confext.parse(html)              # -> parse html
+doc.doctype                            # '<!DOCTYPE html>'
+doc.stats()                            # {'elements': 7, 'comments': 0, 'max_depth': 4}
+doc.to_html()                          # serialized markup
+doc.root.iter_elements()               # walk every element node
+```
+
+## API
+
+### Functions
+
+| Function | Description |
+|---|---|
+| `parse(html)` | Parse `str` or `bytes` into a `ParsedDocument` using the default engine. |
+
+That is the whole module-level API, confext is a parser, nothing else.
+
+### ParsedDocument
+
+| Member | Description |
+|---|---|
+| `to_html()` | Re-serialize the tree. |
+| `stats()` | `{'elements', 'comments', 'max_depth'}`. |
+| `to_dict()` | `{'doctype', 'stats', 'html', 'errors'}`. |
+| `doctype`, `root`, `comments`, `errors` | Raw parse artifacts. |
+
+### Node
+
+`tag`, `attrs`, `parent`, `children` (mix of `Node`s and text `str`s),
+plus: `get_attr`, `has_class`, `append_child`, `remove`, `text_content`,
+`iter_elements`, `to_html`, `to_dict`.
+
+### Engine
+
+For isolated runs with a custom config and no global state:
+
+```python
+from confext import Engine, ConfextError
+
+engine = Engine({'strict_mode': True})
+doc = engine.parse('<div><p>ok</p></div>')
+engine.parse('<div><p>oops</div>')   # raises ConfextError in strict mode
+```
+
+Also accepts `use_cache=False` to disable document memoization
+(`cache_size` is clamped to a minimum of 1).
+
+## Configuration
+
+`DEFAULT_CONFIG` is a plain dict; `Engine(config)` merges over it.
+Settings can also be persisted to and loaded from a `default.config`
+file:
+
+```python
+from confext import Config, load_config, save_config
+
+cfg = load_config()                    # finds the caller's default.config
+cfg.get('max_depth')                   # user setting layered over defaults
+save_config(cfg, 'default.config', compression='xz')
+```
+
+The binary layout is `[8-byte sha256][4-byte size][payload]`, where
+the payload is a raw, lzma (xz), or zlib compressed payload of a
+plain-data dict. Size and checksum are verified before decompression
+and unpickling; both checks run before any decompression is
+attempted. Failures raise `ConfigLoadError`, `ConfigChecksumError`,
+or `ConfigDecompressError`.
+
+| Key | Default | Used by |
+|---|---|---|
+| `encoding` | `'utf-8'` | Fallback when bytes input has no BOM / `<meta charset>`. |
+| `max_depth` | `100` | Element nesting cap (deeper nodes are dropped). |
+| `max_file_size_mb` | `10` | Input size cap; parse raises `ConfextError` beyond it. |
+| `cache_size` | `50` | LRU capacity for parsed documents. |
+| `strict_mode` | `False` | If true, malformed HTML (unclosed/stray tags) raises. |
+| `strip_whitespace` | `True` | Collapse whitespace runs in text nodes at parse time. |
+| `preserve_comments` | `False` | Keep comments in the tree (always captured in `doc.comments`). |
+
+Output and sanitize keys (`remove_comments`, `pretty_indent`,
+`allowed_tags`, …) are consumed by paster, not confext.
+
+## Errors
+
+```
+ConfextError  parse failures, strict-mode violations (unclosed/
+                  stray tags and depth-limit breaches — deeper nodes
+                  are silently dropped outside strict mode) and
+                  size-limit breaches
+```
+
+Invalid selectors now raise paster's `SelectorSyntaxError`.
+
+## Layout
+
+```
+confext/
+├── __init__.py     public API: parse; re-exports Engine,
+│                   DEFAULT_CONFIG, ConfextError, Node,
+│                   ParsedDocument, VOID_ELEMENTS, Config,
+│                   load_config/save_config, config errors
+├── errors.py       ConfextError, ConfigLoadError family
+├── tree.py         Node, ParsedDocument (tree model + stats)
+├── reader.py       encoding detection, TreeBuilder (stdlib tokenizer)
+├── engine.py       Engine, DEFAULT_CONFIG, LRU cache
+└── config.py       Config, load_config/save_config (default.config)
+```

confext-0.7.2/confext.egg-info/SOURCES.txt

@@ -0,0 +1,13 @@
+LICENSE
+README.md
+pyproject.toml
+confext/__init__.py
+confext/config.py
+confext/engine.py
+confext/errors.py
+confext/reader.py
+confext/tree.py
+confext.egg-info/PKG-INFO
+confext.egg-info/SOURCES.txt
+confext.egg-info/dependency_links.txt
+confext.egg-info/top_level.txt

confext-0.7.2/confext.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

confext-0.7.2/confext.egg-info/top_level.txt

@@ -0,0 +1 @@
+confext

confext-0.7.2/pyproject.toml

@@ -0,0 +1,31 @@
+[build-system]
+requires = ["setuptools>=74.1"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "confext"
+version = "0.7.2"
+description = "Stdlib HTML parsing into a tree model"
+readme = "README.md"
+requires-python = ">=3.8"
+license = { text = "MIT" }
+authors = [{name = "kinishuki", email = "kinishuki@gmail.com"}]
+keywords = ["html", "parser", "tree"]
+classifiers = [
+    "Development Status :: 5 - Production/Stable",
+    "Intended Audience :: Developers",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.8",
+    "Programming Language :: Python :: 3.9",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Programming Language :: Python :: 3.14",
+    "Topic :: Text Processing :: Markup :: HTML",
+]
+dependencies = []
+
+[tool.setuptools]
+packages = ["confext"]

confext-0.7.2/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+