"""Small XML utility helpers for ISTAT XML serialization."""

from __future__ import annotations

from datetime import date
from io import BytesIO
from xml.etree import ElementTree


def safe_text(value: object) -> str:
    """Return a safe XML text value."""
    if value is None:
        return ""
    return str(value)


def format_xml_date(value: date) -> str:
    """Format dates for ISTAT XML documents as YYYYMMDD."""
    return value.strftime("%Y%m%d")


def format_date(value: date) -> str:
    return format_xml_date(value)


def append_text_node(parent: ElementTree.Element, tag: str, value: object) -> ElementTree.Element:
    """Append a child element with text and return it."""
    element = ElementTree.SubElement(parent, tag)
    element.text = safe_text(value)
    return element


def to_xml_string(root: ElementTree.Element) -> str:
    """Serialize an XML tree to a UTF-8 document string."""
    tree = ElementTree.ElementTree(root)
    buffer = BytesIO()
    tree.write(
        buffer,
        encoding="UTF-8",
        xml_declaration=True,
        short_empty_elements=False,
    )
    return buffer.getvalue().decode("UTF-8")