from __future__ import annotations

from collections.abc import Mapping
from pathlib import Path

from .writer import FieldValue, InfluxWriter


def write_point(
    *,
    qoi: str,
    value: FieldValue,
    uncertainty: FieldValue | None = None,
    trace_id: str | 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,
) -> None:
    """Write one QOI point.

    Parameters
    ----------
    qoi : str
        Measurement name.
    value : FieldValue
        Primary field value.
    uncertainty : FieldValue | None, default=None
        Optional uncertainty field.
    trace_id : str | None, default=None
        Optional trace identifier 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``.
    """
    with InfluxWriter.from_toml(settings_path) as writer:
        writer.write_point(
            qoi=qoi,
            value=value,
            uncertainty=uncertainty,
            trace_id=trace_id,
            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,
        )
