from __future__ import annotations

from collections.abc import Mapping
from pathlib import Path

from .write_batch import write_batch


def write_point(
    record: Mapping[str, object],
    *,
    settings_path: str | Path | None = None,
) -> dict[str, object]:
    """Write one QOI point.

    Parameters
    ----------
    record : Mapping[str, object]
        One record dictionary using the same schema as ``write_batch``.
        Use ``extra_tags`` and ``extra_fields`` keys in the record for
        optional user-defined tags/fields.
    settings_path : str | Path | None, default=None
        Optional path to settings TOML. Defaults to ``settings.toml``.

    Returns
    -------
    dict[str, object]
        Write summary with ``records_total``, ``records_written``,
        and ``records_failed``.
    """
    return write_batch([record], settings_path=settings_path)
