mf2dom 0.1.9__py3-none-any.whl

mf2dom/types.py

@@ -0,0 +1,57 @@
+"""Type definitions for mf2dom.
+
+These TypedDicts model the JSON output defined by the Microformats2 parsing
+specification and the official test suite.
+"""
+
+from __future__ import annotations
+
+from typing import NotRequired, TypeAlias, TypedDict
+
+
+class UrlObject(TypedDict):
+    value: str
+    alt: NotRequired[str]
+    srcset: NotRequired[dict[str, str]]
+
+
+class EValue(TypedDict, total=False):
+    value: str
+    html: str
+    lang: str
+
+
+PropertyPrimitive: TypeAlias = str
+UrlValue: TypeAlias = str | UrlObject
+
+
+class Mf2Item(TypedDict, total=False):
+    type: list[str]
+    properties: dict[str, list[PropertyValue]]
+    id: str
+    children: list[Mf2Item]
+    value: PropertyValue
+    html: str
+    lang: str
+
+
+PropertyValue: TypeAlias = PropertyPrimitive | UrlObject | EValue | Mf2Item
+
+
+class RelUrl(TypedDict, total=False):
+    rels: list[str]
+    text: str
+    media: str
+    hreflang: str
+    type: str
+    title: str
+
+
+Mf2Document = TypedDict(
+    "Mf2Document",
+    {
+        "items": list[Mf2Item],
+        "rels": dict[str, list[str]],
+        "rel-urls": dict[str, RelUrl],
+    },
+)

mf2dom/urls.py

@@ -0,0 +1,31 @@
+"""URL utilities (joining and `srcset` parsing)."""
+
+from __future__ import annotations
+
+import re
+from urllib.parse import urljoin
+
+
+def try_urljoin(base: str | None, url: str | None, *, allow_fragments: bool = True) -> str | None:
+    if url is None:
+        return None
+    if url.startswith(("https://", "http://")):
+        return url
+    if not base:
+        return url
+    try:
+        return urljoin(base, url, allow_fragments=allow_fragments)
+    except ValueError:
+        return url
+
+
+_SRCSET_RE = re.compile(r"(\S+)\s*([\d.]+[xw])?\s*,?\s*", re.MULTILINE)
+
+
+def parse_srcset(srcset: str, base_url: str | None) -> dict[str, str]:
+    sources: dict[str, str] = {}
+    for url, descriptor in _SRCSET_RE.findall(srcset):
+        key = descriptor or "1x"
+        if key not in sources:
+            sources[key] = try_urljoin(base_url, url.strip(",")) or url.strip(",")
+    return sources

mf2dom/vcp.py

@@ -0,0 +1,211 @@
+"""Value Class Pattern (VCP) parsing.
+
+Implements the mf2 Value Class Pattern for `p-*`, `u-*`, and `dt-*` properties.
+See: https://microformats.org/wiki/value-class-pattern
+"""
+
+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
+
+if TYPE_CHECKING:  # pragma: no cover
+    from collections.abc import Iterator
+
+_DATE_RE = r"(\d{4}-\d{2}-\d{2})|(\d{4}-\d{3})"
+_SEC_RE = r"(:(?P<second>\d{2})(\.\d+)?)"
+_RAWTIME_RE = rf"(?P<hour>\d{{1,2}})(:(?P<minute>\d{{2}}){_SEC_RE}?)?"
+_AMPM_RE = r"am|pm|a\.m\.|p\.m\.|AM|PM|A\.M\.|P\.M\."
+_TIMEZONE_RE = r"Z|[+-]\d{1,2}:?\d{2}?"
+_TIME_RE = rf"(?P<rawtime>{_RAWTIME_RE})( ?(?P<ampm>{_AMPM_RE}))?( ?(?P<tz>{_TIMEZONE_RE}))?"
+_DATETIME_RE = rf"(?P<date>{_DATE_RE})(?P<separator>[Tt ])(?P<time>{_TIME_RE})"
+
+_TIME_RE_COMPILED = re.compile(_TIME_RE + "$")
+_DATE_RE_COMPILED = re.compile(_DATE_RE + "$")
+_TZ_ONLY_RE_COMPILED = re.compile(_TIMEZONE_RE + "$")
+_DATETIME_RE_COMPILED = re.compile(_DATETIME_RE + "$")
+
+_HOURS_IN_HALF_DAY = 12
+
+
+def _is_value_node(el: Element) -> bool:
+    classes = set(get_classes(el))
+    return "value" in classes or "value-title" in classes
+
+
+def _is_property_node(el: Element) -> bool:
+    return any(is_valid_property_class(c) for c in get_classes(el))
+
+
+def _is_microformat_root(el: Element) -> bool:
+    return has_root_class(get_classes(el))
+
+
+def _iter_value_nodes(root: Element) -> Iterator[Element]:
+    # Descendants (not self), in document order, but do not traverse into nested
+    # properties or microformats unless the node itself is a value node.
+    stack: list[Element] = list(reversed(list(iter_child_elements(root))))
+    while stack:
+        el = stack.pop()
+        if _is_value_node(el):
+            yield el
+            continue
+        if _is_property_node(el) or _is_microformat_root(el):
+            continue
+        stack.extend(reversed(list(iter_child_elements(el))))
+
+
+def text(root: Element) -> str | None:
+    parts: list[str] = []
+    for el in _iter_value_nodes(root):
+        classes = set(get_classes(el))
+        if "value-title" in classes:
+            title = get_attr(el, "title")
+            if title is not None:
+                parts.append(title)
+            continue
+
+        tag = el.name.lower()
+        if tag in {"img", "area"}:
+            alt = get_attr(el, "alt")
+            if alt is not None:
+                parts.append(alt)
+            else:
+                parts.append(text_content(el))
+        elif tag in {"data", "input"}:
+            val = get_attr(el, "value")
+            parts.append(val if val is not None else text_content(el))
+        elif tag == "abbr":
+            title = get_attr(el, "title")
+            parts.append(title if title is not None else text_content(el))
+        else:
+            parts.append(text_content(el))
+
+    if not parts:
+        return None
+    return "".join(parts)
+
+
+def datetime(root: Element, default_date: str | None) -> tuple[str, str | None] | None:
+    raw_parts: list[tuple[str, bool]] = []
+    for el in _iter_value_nodes(root):
+        classes = set(get_classes(el))
+        if "value-title" in classes:
+            title = get_attr(el, "title")
+            if title:
+                raw_parts.append((title.strip(), False))
+            continue
+
+        tag = el.name.lower()
+        if tag in {"img", "area"}:
+            alt = get_attr(el, "alt") or text_content(el)
+            if alt:
+                raw_parts.append((alt.strip(), False))
+        elif tag in {"data", "input"}:
+            val = get_attr(el, "value") or text_content(el)
+            if val:
+                raw_parts.append((val.strip(), False))
+        elif tag == "abbr":
+            title = get_attr(el, "title") or text_content(el)
+            if title:
+                raw_parts.append((title.strip(), False))
+        elif tag in {"del", "ins", "time"}:
+            dt = get_attr(el, "datetime") or text_content(el)
+            if dt:
+                raw_parts.append((dt.strip(), True))
+        else:
+            txt = text_content(el)
+            if txt:
+                raw_parts.append((txt.strip(), False))
+
+    if not raw_parts:
+        return None
+
+    date_part: str | None = None
+    time_part: str | None = None
+    time_part_from_time_el = False
+    tz_part: str | None = None
+
+    for part, from_time_el in raw_parts:
+        dt_match = _DATETIME_RE_COMPILED.match(part)
+        if dt_match:
+            if date_part is None and time_part is None and tz_part is None:
+                normalized = normalize_datetime(part, match=dt_match)
+                return normalized, dt_match.group("date")
+            continue
+
+        if date_part is None and _DATE_RE_COMPILED.match(part):
+            date_part = part
+            continue
+
+        time_match = _TIME_RE_COMPILED.match(part)
+        if time_part is None and time_match:
+            time_part = part
+            time_part_from_time_el = from_time_el
+            tz_group = time_match.group("tz")
+            if tz_part is None and tz_group:
+                tz_part = tz_group
+            continue
+
+        if tz_part is None and _TZ_ONLY_RE_COMPILED.match(part):
+            tz_part = part
+
+    if date_part is None and time_part is None:
+        return None
+    if date_part is None and time_part is not None:
+        date_part = default_date
+
+    value = f"{date_part} {time_part}" if date_part and time_part else date_part or time_part or ""
+
+    if tz_part and time_part and tz_part not in value:
+        value += tz_part
+
+    if time_part_from_time_el:
+        # In the official test suite, timezones with a colon originating from <time>/<ins>/<del>
+        # value nodes are normalized to the compact form (e.g. -08:00 => -0800).
+        value = re.sub(r"([+-]\d{1,2}):(\d{2})$", r"\1\2", value)
+
+    match = _DATETIME_RE_COMPILED.match(value)
+    if match:
+        value = normalize_datetime(value, match=match)
+    return value, date_part
+
+
+def normalize_datetime(dtstr: str, *, match: re.Match[str] | None = None) -> str:
+    match = match or _DATETIME_RE_COMPILED.match(dtstr)
+    if not match:
+        return dtstr
+
+    datestr = match.group("date")
+    separator = match.group("separator")
+    hour = match.group("hour")
+    minute = match.group("minute")
+    second = match.group("second")
+    ampm = match.group("ampm")
+    tz = match.group("tz") or ""
+
+    # Only normalize when AM/PM is present.
+    if not ampm:
+        return dtstr
+
+    hour_int = int(hour)
+    if ampm.lower().startswith("a") and hour_int == _HOURS_IN_HALF_DAY:
+        hour_int = 0
+    elif ampm.lower().startswith("p") and hour_int < _HOURS_IN_HALF_DAY:
+        hour_int += _HOURS_IN_HALF_DAY
+
+    minute_out = minute or "00"
+    time_out = f"{hour_int:02d}:{minute_out}"
+    if second is not None:
+        time_out += f":{second}"
+
+    return f"{datestr}{separator}{time_out}{tz}"

mf2dom-0.1.9.dist-info/METADATA

@@ -0,0 +1,94 @@
+Metadata-Version: 2.4
+Name: mf2dom
+Version: 0.1.9
+Summary: Microformats2 (mf2) parser and renderer powered by JustHTML.
+Author-email: Beto Dealmeida <contact@robida.net>
+License-File: LICENSE.md
+Requires-Python: >=3.11
+Requires-Dist: justhtml>=0.12.0
+Description-Content-Type: text/markdown
+
+# mf2dom
+
+Microformats2 (mf2) parser and deterministic renderer powered by JustHTML.
+
+`mf2dom` focuses on:
+- Correct mf2 parsing (validated against the official `microformats-tests` suite)
+- Deterministic HTML rendering and stable round-trips (`HTML -> mf2 -> HTML`)
+- A small runtime surface area (no network I/O, no BeautifulSoup)
+
+## Installation
+
+```bash
+pip install mf2dom
+```
+
+Requires Python 3.11+.
+
+## Quickstart
+
+Parse mf2 JSON from HTML:
+
+```python
+import mf2dom
+
+html = '<a class="h-card u-url p-name" href="/me">Alice</a>'
+doc = mf2dom.parse(html, base_url="https://example.com/")
+print(doc["items"])
+```
+
+The parsed document is a dict with `items`, `rels`, and `rel-urls` keys (mf2 JSON shape).
+
+Render mf2 JSON back into canonical HTML:
+
+```python
+html2 = mf2dom.render(doc)
+```
+
+Async parsing (offloads to a thread):
+
+```python
+doc = await mf2dom.parse_async(html, base_url="https://example.com/")
+```
+
+## API
+
+- `mf2dom.parse(html, *, base_url=None, url=None) -> dict`
+  - `html` can be a string/bytes, a `justhtml.JustHTML` instance, or a JustHTML root node.
+  - `base_url` controls resolution of relative URLs (preferred). `url` is a deprecated alias.
+- `mf2dom.parse_async(...)` is `parse(...)` via `asyncio.to_thread(...)`.
+- `mf2dom.render(doc) -> str` renders a deterministic HTML representation of an mf2 document.
+
+## Why mf2dom vs mf2py?
+
+Both libraries parse microformats, but they optimize for different use cases:
+
+- Choose `mf2dom` if you need deterministic rendering, stable round-trips, and a smaller/no-network
+  runtime surface (useful for normalization, caching, and “canonical mf2 HTML” fixtures).
+- Choose `mf2py` if you need URL fetching, microformats1 compatibility, metaformats support, or
+  wider Python version support.
+
+## Testing & correctness
+
+- Official parsing fixtures: `tests/test_official_microformats_suite.py` runs the upstream
+  `microformats-tests` JSON fixtures.
+- Coverage gate: `pyproject.toml` enforces 100% branch coverage.
+
+To run the official fixture suite locally, check out `microformats-tests` as a sibling directory:
+
+```bash
+git clone https://github.com/microformats/microformats-tests ../microformats-tests
+```
+
+## Development (uv)
+
+```bash
+uv sync --group dev
+uv run pytest
+uv run coverage run -m pytest && uv run coverage report
+uv run pre-commit install
+```
+
+## License
+
+AGPL 3

mf2dom-0.1.9.dist-info/RECORD

@@ -0,0 +1,15 @@
+mf2dom/__init__.py,sha256=YmTk1FZ8B2u6J2LfZETnxxuNWa88pCcpYDXdBaaFlt0,215
+mf2dom/classes.py,sha256=39YrnFFTh1onGs_EIRkV-EFFEBm2atfpcfbzDydMtps,2921
+mf2dom/dom.py,sha256=GgKSjwcrWrn8Dow-SuDf295ZgwopvhyZMkAMcshQACc,4061
+mf2dom/implied.py,sha256=P8HrXX1JLNzZGl2psstd4qnfAHYuPHjsG-qUD4mjqnc,5893
+mf2dom/parser.py,sha256=dZTzs2Q-dKM_FuA5jnLd6-VNlpTLJyYGnkgQwJvaQnc,13372
+mf2dom/properties.py,sha256=BFtVsntKzN8yu52bjjjSTPwK674E48wfRneY314k41w,7629
+mf2dom/renderer.py,sha256=UkWYEpJeRbxF-83bnqsNPTgTETpdaUaU1SoUSSmICSs,19261
+mf2dom/text.py,sha256=g15f58Oh-tSUrOSCNK661YeGLTaamttlNrrgixF8g2I,1827
+mf2dom/types.py,sha256=mKRe9UaVVV0HlMJRefUSbHCsbFBvIKo6xlv7eLhRSuk,1100
+mf2dom/urls.py,sha256=VeyRxYNl3CyZu-dxLIWf7b1GF0Bol4yEVTOLHDS9F_M,895
+mf2dom/vcp.py,sha256=d8nH7ORA1P5lJe-HwdQInmmIZPHEjTAuT_6KPHEvbqg,7001
+mf2dom-0.1.9.dist-info/METADATA,sha256=jj5scPTQIunaAPOmXtYVnNLDQJzxSsyn6Z0IlVrq344,2643
+mf2dom-0.1.9.dist-info/WHEEL,sha256=WLgqFyCfm_KASv4WHyYy0P3pM_m7J5L9k2skdKLirC8,87
+mf2dom-0.1.9.dist-info/licenses/LICENSE.md,sha256=MqCnOBu8uXsEOzRZWh9EBVfVz-kE9NkXcLCrtGXo2yU,34354
+mf2dom-0.1.9.dist-info/RECORD,,

mf2dom-0.1.9.dist-info/WHEEL

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