Frontmatter API Reference¶

def detect_handler(text: str) -> str | None:
    """Detect the frontmatter format of a text string.

    Args:
        text: The full document text.

    Returns:
        ``"yaml"``, ``"toml"``, ``"json"``, or ``None`` if no frontmatter
        is detected.
    """
    stripped = text.lstrip(_BOM)
    if stripped.startswith(_YAML_FENCE + "\n") or stripped.startswith(
        _YAML_FENCE + "\r\n"
    ):
        return "yaml"
    if stripped.startswith(_TOML_FENCE + "\n") or stripped.startswith(
        _TOML_FENCE + "\r\n"
    ):
        return "toml"
    if stripped.startswith("{"):
        return "json"
    return None

def check(text: str) -> bool:
    """Check whether a text string contains frontmatter.

    Args:
        text: The full document text.

    Returns:
        ``True`` if frontmatter is detected.
    """
    return detect_handler(text) is not None

def loads(text: str, *, handler: str | None = None) -> Document:
    """Parse a text string with frontmatter.

    Args:
        text: The full document text.
        handler: Force a specific format (``"yaml"``, ``"toml"``, ``"json"``).
            If ``None``, the format is auto-detected.

    Returns:
        A ``Document`` with parsed metadata and body content.

    Raises:
        FrontmatterError: If parsing fails.
        HandlerError: If the requested handler is not available.

    Example::

        doc = loads("---\\ntitle: Hello\\n---\\nBody text.")
        doc.metadata  # {'title': 'Hello'}
        doc.content   # 'Body text.'
    """
    if handler is None:
        handler = detect_handler(text)

    if handler is None:
        # No frontmatter detected — entire text is content
        return Document(metadata={}, content=text)

    if handler == "yaml":
        parts = _split_fenced(text, _YAML_FENCE)
        if parts is None:
            return Document(metadata={}, content=text)
        raw, body = parts
        if not raw.strip():
            return Document(metadata={}, content=body)
        metadata = _parse_yaml(raw)
        return Document(metadata=metadata, content=body)

    if handler == "toml":
        parts = _split_fenced(text, _TOML_FENCE)
        if parts is None:
            return Document(metadata={}, content=text)
        raw, body = parts
        if not raw.strip():
            return Document(metadata={}, content=body)
        metadata = _parse_toml(raw)
        return Document(metadata=metadata, content=body)

    if handler == "json":
        parts = _split_json(text)
        if parts is None:
            return Document(metadata={}, content=text)
        raw, body = parts
        metadata = _parse_json(raw)
        return Document(metadata=metadata, content=body)

    raise HandlerError(
        f"unknown handler: {handler!r} (expected yaml/toml/json)", handler=handler
    )

def load(
    source: IO[str] | str | Path,
    *,
    handler: str | None = None,
) -> Document:
    """Parse a file with frontmatter.

    Args:
        source: A file path (``str`` or ``Path``) or an open text stream.
        handler: Force a specific format. If ``None``, auto-detect.

    Returns:
        A ``Document`` with parsed metadata and body content.

    Example::

        doc = load("post.md")
        doc = load(Path("post.md"))
        with open("post.md") as f:
            doc = load(f)
    """
    if isinstance(source, (str, Path)):
        text = Path(source).read_text(encoding="utf-8")
    else:
        text = source.read()
    return loads(text, handler=handler)

def dumps(
    doc: Document,
    *,
    handler: str = "yaml",
    **kwargs: Any,
) -> str:
    """Serialize a ``Document`` to a string with frontmatter.

    Args:
        doc: The document to serialize.
        handler: Output format (``"yaml"``, ``"toml"``, ``"json"``).
            Defaults to ``"yaml"``.
        **kwargs: Passed to the underlying serializer.

    Returns:
        The full document text with frontmatter and body.

    Example::

        doc = Document({"title": "Hello"}, "Body text.")
        text = dumps(doc)
        # ---
        # title: Hello
        # ---
        # Body text.
    """
    if handler == "yaml":
        fence = _YAML_FENCE
        raw = _dump_yaml(doc.metadata, **kwargs) if doc.metadata else ""
    elif handler == "toml":
        fence = _TOML_FENCE
        raw = _dump_toml(doc.metadata, **kwargs) if doc.metadata else ""
    elif handler == "json":
        raw_json = _dump_json(doc.metadata, **kwargs) if doc.metadata else ""
        # JSON uses { } as delimiters, no fence
        if doc.content:
            return raw_json + doc.content
        return raw_json
    else:
        raise HandlerError(
            f"unknown handler: {handler!r} (expected yaml/toml/json)", handler=handler
        )

    parts = [fence, "\n"]
    if raw:
        # Ensure raw ends with newline
        if not raw.endswith("\n"):
            raw += "\n"
        parts.append(raw)
    parts.append(fence)
    parts.append("\n")
    if doc.content:
        parts.append(doc.content)
    return "".join(parts)

def dump(
    doc: Document,
    dest: IO[str] | str | Path,
    *,
    handler: str = "yaml",
    **kwargs: Any,
) -> None:
    """Serialize a ``Document`` to a file with frontmatter.

    Args:
        doc: The document to serialize.
        dest: A file path (``str`` or ``Path``) or an open text stream.
        handler: Output format. Defaults to ``"yaml"``.
        **kwargs: Passed to the underlying serializer.

    Example::

        dump(doc, "post.md")
        dump(doc, Path("post.md"), handler="toml")
        with open("post.md", "w") as f:
            dump(doc, f)
    """
    text = dumps(doc, handler=handler, **kwargs)
    if isinstance(dest, (str, Path)):
        Path(dest).write_text(text, encoding="utf-8")
    else:
        dest.write(text)