api_24sea.datasignals.writes ============================ .. py:module:: api_24sea.datasignals.writes .. autoapi-nested-parse:: Shared request planning for DataSignals PUT and PATCH operations. Classes ------- .. autoapisummary:: api_24sea.datasignals.writes.DatasignalWriteRequest Functions --------- .. autoapisummary:: api_24sea.datasignals.writes.is_missing_write_value api_24sea.datasignals.writes.normalize_write_timestamp api_24sea.datasignals.writes.normalize_write_json_value api_24sea.datasignals.writes.normalize_write_record api_24sea.datasignals.writes.normalize_write_payload api_24sea.datasignals.writes.plan_write_request api_24sea.datasignals.writes.parse_write_response Module Contents --------------- .. py:class:: DatasignalWriteRequest Normalized request for one DataSignals write operation. Attributes ---------- method : str HTTP write method, either ``PUT`` or ``PATCH``. query_params : dict Endpoint control values sent in the query string. payload : list of dict JSON-compatible datasignal rows sent in the request body. .. py:function:: is_missing_write_value(value: Any) -> bool Return whether a scalar value represents missing pandas data. Parameters ---------- value : Any Candidate scalar value. Returns ------- bool ``True`` for ``NaN``, ``NaT``, and ``pandas.NA`` values. Examples -------- >>> is_missing_write_value(float("nan")) True >>> is_missing_write_value(None) False .. py:function:: normalize_write_timestamp(value: Any) -> str Return a write timestamp as an ISO-8601 UTC string. Parameters ---------- value : Any String, ``datetime``, or pandas timestamp value. Returns ------- str UTC timestamp ending in ``Z``. Raises ------ ValueError If the value is missing or cannot be parsed as a timestamp. Examples -------- >>> normalize_write_timestamp("2026-07-23T10:00:00+02:00") '2026-07-23T08:00:00Z' .. py:function:: normalize_write_json_value(value: Any) -> Any Return a value that can be encoded as strict JSON. Parameters ---------- value : Any Metric value supplied by the caller. Returns ------- Any JSON-compatible scalar or nested collection. Raises ------ ValueError If the value is missing, non-finite, or unsupported. .. py:function:: normalize_write_record(record: collections.abc.Mapping[str, Any], *, method: str, site: Optional[str] = None, location: Optional[str] = None, omit_missing_metrics: bool = False) -> dict[str, Any] Normalize one row for the DataSignals write endpoint. Parameters ---------- record : Mapping Datasignal row containing timestamp, site, location, and metrics. method : str Write method, either ``PUT`` or ``PATCH``. site : str, optional Site used when the record does not contain one. location : str, optional Location used when the record does not contain one. omit_missing_metrics : bool, default False Omit pandas missing metric values. This is intended for sparse DataFrame PATCH requests. Returns ------- dict Normalized JSON-compatible datasignal row. .. py:function:: normalize_write_payload(data: Any, *, method: str, site: Optional[str] = None, location: Optional[str] = None) -> list[dict[str, Any]] Normalize supported SDK write inputs into endpoint rows. Parameters ---------- data : Any Mapping, sequence of mappings, or pandas DataFrame. method : str Write method, either ``PUT`` or ``PATCH``. site : str, optional Default site for rows that omit the field. location : str, optional Default location for rows that omit the field. Returns ------- list of dict Ordered, JSON-compatible datasignal rows. Raises ------ ValueError If the input is empty, malformed, or contains duplicate identities. .. py:function:: plan_write_request(data: Any, *, method: str, site: Optional[str] = None, location: Optional[str] = None, on_conflict: str = 'replace', include_cyclecount: bool = True, profile: bool = False) -> DatasignalWriteRequest Build a validated DataSignals write request. Parameters ---------- data : Any Mapping, sequence of mappings, or pandas DataFrame. method : str Write method, either ``PUT`` or ``PATCH``. site : str, optional Default site for rows that omit the field. location : str, optional Default location for rows that omit the field. on_conflict : {"replace", "nothing"}, default "replace" Conflict behavior defined by the backend endpoint. include_cyclecount : bool, default True Whether metrics beginning with ``CC_`` should be written. profile : bool, default False Whether the backend should include timing information. Returns ------- DatasignalWriteRequest Normalized method, query parameters, and payload. .. py:function:: parse_write_response(payload: Any) -> dict[str, Any] Validate and return a DataSignals write response. Parameters ---------- payload : Any Decoded endpoint response. Returns ------- dict Write result from the backend. Raises ------ ValueError If the endpoint returns an unexpected successful response.