from __future__ import annotations

from collections.abc import Mapping
from pathlib import Path

from ..types import TUID
from .writer import FieldValue, InfluxWriter


def write_point(
    *,
    qoi: str,
    nominal_value: FieldValue,
    uncertainty: FieldValue | None = None,
    tuid: TUID | None = None,
    element: str | None = None,
    label: str | None = None,
    unit: str | None = None,
    element_label: str | None = None,
    device_ID: str | None = None,
    run_ID: str | None = None,
    cycle_ID: str | None = None,
    condition: str | None = None,
    extra_tags: Mapping[str, str] | None = None,
    extra_fields: Mapping[str, FieldValue] | None = None,
    settings_path: str | Path | None = None,
) -> dict[str, int]:
    """Write one QOI point.

    Parameters
    ----------
    qoi : str
        Measurement name.
    nominal_value : FieldValue
        Primary field value.
    uncertainty : FieldValue | None, default=None
        Optional uncertainty field.
    tuid : TUID | None, default=None
        Optional TUID field.
    element : str | None, default=None
        Optional ``element`` tag.
    label : str | None, default=None
        Optional ``label`` tag.
    unit : str | None, default=None
        Optional ``unit`` tag.
    element_label : str | None, default=None
        Optional ``element_label`` tag.
    device_ID : str | None, default=None
        Optional ``device_ID`` tag.
    run_ID : str | None, default=None
        Optional ``run_ID`` tag.
    cycle_ID : str | None, default=None
        Optional ``cycle_ID`` tag.
    condition : str | None, default=None
        Optional ``condition`` tag.
    extra_tags : Mapping[str, str] | None, default=None
        Extra user-defined tags.
    extra_fields : Mapping[str, FieldValue] | None, default=None
        Extra user-defined fields.
    settings_path : str | Path | None, default=None
        Optional path to settings TOML. Defaults to ``settings.toml``.

    Returns
    -------
    dict[str, int]
        Write summary with ``records_total``, ``records_written``,
        and ``records_failed``.
    """
    with InfluxWriter.from_toml(settings_path) as writer:
        writer.write_point(
            qoi=qoi,
            nominal_value=nominal_value,
            uncertainty=uncertainty,
            tuid=tuid,
            element=element,
            label=label,
            unit=unit,
            element_label=element_label,
            device_ID=device_ID,
            run_ID=run_ID,
            cycle_ID=cycle_ID,
            condition=condition,
            extra_tags=extra_tags,
            extra_fields=extra_fields,
        )
    return {
        "records_total": 1,
        "records_written": 1,
        "records_failed": 0,
    }
