mf2dom 0.1.9__py3-none-any.whl

mf2dom/__init__.py

@@ -0,0 +1,8 @@
+"""mf2dom: Microformats2 parsing + rendering using JustHTML."""
+
+from __future__ import annotations
+
+from .parser import parse, parse_async
+from .renderer import render
+
+__all__ = ["parse", "parse_async", "render"]

mf2dom/classes.py

@@ -0,0 +1,87 @@
+"""Microformats2 class token validation.
+
+The official test suite (`microformats-v2-unit/names-*`) defines additional
+constraints beyond "starts with the right prefix". This module encodes those
+rules and provides utilities for extracting valid root and property classes.
+"""
+
+from __future__ import annotations
+
+import re
+
+_DIGIT_LETTER_RE = re.compile(r"^\d+[a-z]$")
+_DIGIT_LETTERS_DIGITS_RE = re.compile(r"^\d+[a-z]+\d+$")
+_LETTERS_DIGITS_OPTLETTERS_RE = re.compile(r"^([a-z]+)(\d+)([a-z]*)$")
+
+_ALLOWED_NAME_CHARS = frozenset("abcdefghijklmnopqrstuvwxyz0123456789-")
+_MIN_DIGITS_FOR_TRAILING_LETTERS = 2
+
+
+def is_valid_mf2_name(name: str) -> bool:
+    """Validate the mf2 *name* portion after the prefix.
+
+    Based on the official microformats2 parsing test suite:
+    - ASCII lowercase letters, digits, and hyphen only
+    - no leading/trailing hyphen, no empty segments / no '--'
+    - a purely numeric name is invalid ('p-19')
+    - numeric-only segments are allowed only as the first segment ('p-6-test')
+    - segments starting with a digit must be either:
+        - digits+single-letter ('7t')
+        - digits+letters+digits ('8t8', '8to8')
+    - segments starting with a letter may contain digits; if digits are followed by letters,
+      the digit run must be at least 2 ('t11t' valid, 'car1d' invalid)
+    """
+    if not name:
+        return False
+    if name[0] == "-" or name[-1] == "-" or "--" in name:
+        return False
+    if any(ch not in _ALLOWED_NAME_CHARS for ch in name):
+        return False
+
+    parts = name.split("-")
+    if len(parts) == 1 and parts[0].isdigit():
+        return False
+
+    return all(_is_valid_name_part(part, is_first=(idx == 0)) for idx, part in enumerate(parts))
+
+
+def _is_valid_name_part(part: str, *, is_first: bool) -> bool:
+    if part.isdigit():
+        return is_first
+    if part[0].isdigit():
+        return bool(_DIGIT_LETTER_RE.match(part) or _DIGIT_LETTERS_DIGITS_RE.match(part))
+    if part.isalpha():
+        return True
+
+    match = _LETTERS_DIGITS_OPTLETTERS_RE.match(part)
+    if not match:
+        return False
+
+    _letters, digits, trailing = match.groups()
+    if trailing == "":
+        return True
+    return len(digits) >= _MIN_DIGITS_FOR_TRAILING_LETTERS
+
+
+def is_valid_root_class(token: str) -> bool:
+    return token.startswith("h-") and is_valid_mf2_name(token[2:])
+
+
+def is_valid_property_class(token: str) -> bool:
+    if token.startswith(("p-", "u-", "e-")):
+        return is_valid_mf2_name(token[2:])
+    if token.startswith("dt-"):
+        return is_valid_mf2_name(token[3:])
+    return False
+
+
+def root_types(classes: list[str]) -> list[str]:
+    return sorted({c for c in classes if is_valid_root_class(c)})
+
+
+def property_classes(classes: list[str]) -> list[str]:
+    return [c for c in classes if is_valid_property_class(c)]
+
+
+def has_root_class(classes: list[str]) -> bool:
+    return any(is_valid_root_class(c) for c in classes)

mf2dom/dom.py

@@ -0,0 +1,133 @@
+"""DOM helpers for JustHTML nodes.
+
+JustHTML exposes a lightweight DOM-like tree. This module provides:
+- Safe element detection
+- Deterministic traversal helpers
+- HTML `class` parsing that follows the HTML spec (ASCII whitespace only)
+
+Important: `class` tokens are returned in document order (a list), because some
+microformats parsing rules are order-sensitive.
+"""
+
+from __future__ import annotations
+
+import re
+from dataclasses import dataclass
+from typing import TYPE_CHECKING, Any, Protocol
+
+if TYPE_CHECKING:  # pragma: no cover
+    from collections.abc import Iterable, Iterator
+
+
+class HasDom(Protocol):
+    name: str
+    parent: Any | None
+
+    @property
+    def children(self) -> list[Any]: ...  # pragma: no cover
+
+
+class Element(HasDom, Protocol):
+    attrs: dict[str, str | None]
+
+    def to_html(
+        self, *, pretty: bool = True, indent_size: int = 2, indent: int = 0
+    ) -> str: ...  # pragma: no cover
+
+
+def is_element(node: Any) -> bool:
+    name = str(getattr(node, "name", ""))
+    if not name or name.startswith(("#", "!")):
+        return False
+    return isinstance(getattr(node, "attrs", None), dict)
+
+
+def iter_child_nodes(node: HasDom) -> Iterator[Any]:
+    """Yield child nodes (including text/comment/doctype nodes)."""
+    children = getattr(node, "children", None)
+    if children:
+        yield from children
+
+
+def iter_child_elements(node: HasDom) -> Iterator[Element]:
+    """Yield element children, skipping `<template>` elements."""
+    for child in iter_child_nodes(node):
+        if is_element(child) and getattr(child, "name", "").lower() != "template":
+            yield child
+
+
+def iter_descendants(node: HasDom) -> Iterator[Any]:
+    """Yield descendant nodes in document order (depth-first)."""
+    stack: list[Any] = list(reversed(list(iter_child_nodes(node))))
+    while stack:
+        cur = stack.pop()
+        yield cur
+        if hasattr(cur, "children"):
+            stack.extend(reversed(list(iter_child_nodes(cur))))
+
+
+def iter_descendant_elements(node: HasDom) -> Iterator[Element]:
+    """Yield descendant elements, skipping `<template>` elements."""
+    for cur in iter_descendants(node):
+        if is_element(cur) and getattr(cur, "name", "").lower() != "template":
+            yield cur
+
+
+def iter_preorder_elements(root: Element) -> Iterator[Element]:
+    """Yield `root` then its descendant elements (pre-order)."""
+    yield root
+    yield from iter_descendant_elements(root)
+
+
+def get_attr(el: Element, name: str) -> str | None:
+    """Get an attribute value (or None if missing)."""
+    return el.attrs.get(name)
+
+
+def set_attr(el: Element, name: str, value: str | None) -> None:
+    """Set an attribute value (use None for boolean attributes)."""
+    el.attrs[name] = value
+
+
+def get_classes(el: Element) -> list[str]:
+    """Return `class` tokens in document order.
+
+    Per HTML, class attributes are split on ASCII whitespace only
+    (` \\t\\n\\f\\r`). Non-ASCII whitespace characters are treated as part of the token.
+    """
+    raw = get_attr(el, "class")
+    if not raw:
+        return []
+    # Per HTML, class is split on ASCII whitespace only.
+    raw = raw.strip(" \t\n\f\r")
+    if not raw:
+        return []
+    return [c for c in _ASCII_WHITESPACE_RE.split(raw) if c]
+
+
+_ASCII_WHITESPACE_RE = re.compile(r"[ \t\n\f\r]+")
+
+
+def has_any_class(el: Element, names: Iterable[str]) -> bool:
+    classes = set(get_classes(el))
+    return any(name in classes for name in names)
+
+
+def has_class_prefix(el: Element, prefixes: Iterable[str]) -> bool:
+    """Return True if any class token starts with one of `prefixes`."""
+    prefix_tuple = tuple(prefixes)
+    return any(cls.startswith(prefix_tuple) for cls in get_classes(el))
+
+
+def ancestor_elements(el: Element) -> Iterator[Element]:
+    """Yield ancestor elements starting from the parent."""
+    cur: Any | None = el.parent
+    while cur is not None:
+        if is_element(cur):
+            yield cur
+        cur = getattr(cur, "parent", None)
+
+
+@dataclass(frozen=True, slots=True)
+class ValueClassNodes:
+    nodes: list[Element]

mf2dom/implied.py

@@ -0,0 +1,166 @@
+"""Implied property parsing (name/photo/url).
+
+Implied properties are applied when an mf2 item has no explicit corresponding
+properties, per the mf2 parsing algorithm.
+"""
+
+from __future__ import annotations
+
+import re
+from typing import TYPE_CHECKING
+
+from .classes import has_root_class, is_valid_property_class
+from .dom import Element, get_attr, get_classes, iter_child_elements
+from .text import text_content
+from .urls import parse_srcset, try_urljoin
+
+if TYPE_CHECKING:  # pragma: no cover
+    from .types import UrlObject, UrlValue
+
+
+def _is_microformat_root(el: Element) -> bool:
+    return has_root_class(get_classes(el))
+
+
+def _has_property_class(el: Element) -> bool:
+    return any(is_valid_property_class(cls) for cls in get_classes(el))
+
+
+def _is_implied_candidate(el: Element) -> bool:
+    return not _is_microformat_root(el) and not _has_property_class(el)
+
+
+_WHITESPACE_RE = re.compile(r"\s+")
+
+
+def implied_name(root: Element, base_url: str | None) -> str:
+    """Compute implied `name` for an item root."""
+
+    def non_empty(val: str | None) -> bool:
+        return val is not None and val != ""
+
+    def normalize_ws(val: str) -> str:
+        return _WHITESPACE_RE.sub(" ", val).strip()
+
+    if root.name.lower() in {"img", "area"}:
+        alt = get_attr(root, "alt")
+        if alt is not None:
+            return normalize_ws(alt)
+
+    if root.name.lower() == "abbr":
+        title = get_attr(root, "title")
+        if title is not None:
+            return normalize_ws(title)
+
+    children = list(iter_child_elements(root))
+    candidate: Element | None = None
+    if len(children) == 1:
+        candidate = children[0]
+        if _is_microformat_root(candidate):
+            candidate = None
+        elif candidate.name.lower() not in {"img", "area", "abbr"}:
+            grand = list(iter_child_elements(candidate))
+            if len(grand) == 1:
+                candidate = grand[0]
+                if candidate.name.lower() not in {"img", "area", "abbr"} or _is_microformat_root(
+                    candidate
+                ):
+                    candidate = None
+
+    if candidate is not None:
+        if candidate.name.lower() in {"img", "area"}:
+            alt = get_attr(candidate, "alt")
+            if non_empty(alt):
+                return normalize_ws(alt or "")
+        if candidate.name.lower() == "abbr":
+            title = get_attr(candidate, "title")
+            if non_empty(title):
+                return normalize_ws(title or "")
+
+    return normalize_ws(text_content(root, replace_img=True, img_to_src=False, base_url=base_url))
+
+
+def _img_value(img: Element, base_url: str | None) -> UrlValue | None:
+    src = get_attr(img, "src")
+    if src is None:
+        return None
+    abs_src = try_urljoin(base_url, src) or src
+    alt = get_attr(img, "alt")
+    srcset = get_attr(img, "srcset")
+    if alt is not None or srcset:
+        out: UrlObject = {"value": abs_src}
+        if alt is not None:
+            out["alt"] = alt
+        if srcset:
+            out["srcset"] = parse_srcset(srcset, base_url)
+        return out
+    return abs_src
+
+
+def implied_photo(root: Element, base_url: str | None) -> UrlValue | None:
+    """Compute implied `photo` for an item root."""
+    if root.name.lower() == "img":
+        return _img_value(root, base_url)
+    if root.name.lower() == "object":
+        data = get_attr(root, "data")
+        if data is not None:
+            return try_urljoin(base_url, data) or data
+
+    def has_u_property(el: Element) -> bool:
+        return any(cls.startswith("u-") and is_valid_property_class(cls) for cls in get_classes(el))
+
+    def photo_child(children: list[Element]) -> Element | None:
+        imgs = [c for c in children if c.name.lower() == "img"]
+        if len(imgs) == 1 and not _is_microformat_root(imgs[0]) and not has_u_property(imgs[0]):
+            return imgs[0]
+        objs = [c for c in children if c.name.lower() == "object"]
+        if len(objs) == 1 and not _is_microformat_root(objs[0]) and not has_u_property(objs[0]):
+            return objs[0]
+        return None
+
+    children = list(iter_child_elements(root))
+    candidate = photo_child(children)
+    if candidate is None and len(children) == 1 and not _is_microformat_root(children[0]):
+        candidate = photo_child(list(iter_child_elements(children[0])))
+
+    if candidate is None:
+        return None
+
+    if candidate.name.lower() == "img":
+        return _img_value(candidate, base_url)
+    data = get_attr(candidate, "data")
+    if data is not None:
+        return try_urljoin(base_url, data) or data
+    return None
+
+
+def implied_url(root: Element, base_url: str | None) -> str | None:
+    """Compute implied `url` for an item root."""
+    if root.name.lower() in {"a", "area"}:
+        href = get_attr(root, "href")
+        if href is not None:
+            return try_urljoin(base_url, href) or href
+
+    def has_u_property(el: Element) -> bool:
+        return any(cls.startswith("u-") and is_valid_property_class(cls) for cls in get_classes(el))
+
+    def url_child(children: list[Element]) -> Element | None:
+        as_ = [c for c in children if c.name.lower() == "a"]
+        if len(as_) == 1 and not _is_microformat_root(as_[0]) and not has_u_property(as_[0]):
+            return as_[0]
+        areas = [c for c in children if c.name.lower() == "area"]
+        if len(areas) == 1 and not _is_microformat_root(areas[0]) and not has_u_property(areas[0]):
+            return areas[0]
+        return None
+
+    children = list(iter_child_elements(root))
+    candidate = url_child(children)
+    if candidate is None and len(children) == 1 and not _is_microformat_root(children[0]):
+        candidate = url_child(list(iter_child_elements(children[0])))
+    if candidate is None:
+        return None
+
+    href = get_attr(candidate, "href")
+    if href is None:
+        return None
+    return try_urljoin(base_url, href) or href