api_24sea.datasignals.writes#

Shared request planning for DataSignals PUT and PATCH operations.

Classes#

DatasignalWriteRequest

Normalized request for one DataSignals write operation.

Functions#

`is_missing_write_value`(→ bool)	Return whether a scalar value represents missing pandas data.
`normalize_write_timestamp`(→ str)	Return a write timestamp as an ISO-8601 UTC string.
`normalize_write_json_value`(→ Any)	Return a value that can be encoded as strict JSON.
`normalize_write_record`(→ dict[str, Any])	Normalize one row for the DataSignals write endpoint.
`normalize_write_payload`(→ list[dict[str, Any]])	Normalize supported SDK write inputs into endpoint rows.
`plan_write_request`(→ DatasignalWriteRequest)	Build a validated DataSignals write request.
`parse_write_response`(→ dict[str, Any])	Validate and return a DataSignals write response.

Module Contents#

class DatasignalWriteRequest#

Normalized request for one DataSignals write operation.

Attributes#

methodstr: HTTP write method, either PUT or PATCH.
query_paramsdict: Endpoint control values sent in the query string.
payloadlist of dict: JSON-compatible datasignal rows sent in the request body.

is_missing_write_value(value: Any) → bool#

Return whether a scalar value represents missing pandas data.

Parameters#

valueAny: 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

normalize_write_timestamp(value: Any) → str#

Return a write timestamp as an ISO-8601 UTC string.

Parameters#

valueAny: 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'

normalize_write_json_value(value: Any) → Any#

Return a value that can be encoded as strict JSON.

Parameters#

valueAny: 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.

normalize_write_record(record: collections.abc.Mapping[str, Any], *, method: str, site: str | None = None, location: str | None = None, omit_missing_metrics: bool = False) → dict[str, Any]#

Normalize one row for the DataSignals write endpoint.

Parameters#

recordMapping: Datasignal row containing timestamp, site, location, and metrics.
methodstr: Write method, either PUT or PATCH.
sitestr, optional: Site used when the record does not contain one.
locationstr, optional: Location used when the record does not contain one.
omit_missing_metricsbool, default False: Omit pandas missing metric values. This is intended for sparse DataFrame PATCH requests.

Returns#

dict: Normalized JSON-compatible datasignal row.

normalize_write_payload(data: Any, *, method: str, site: str | None = None, location: str | None = None) → list[dict[str, Any]]#

Normalize supported SDK write inputs into endpoint rows.

Parameters#

dataAny: Mapping, sequence of mappings, or pandas DataFrame.
methodstr: Write method, either PUT or PATCH.
sitestr, optional: Default site for rows that omit the field.
locationstr, 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.

plan_write_request(data: Any, *, method: str, site: str | None = None, location: str | None = None, on_conflict: str = 'replace', include_cyclecount: bool = True, profile: bool = False) → DatasignalWriteRequest#

Build a validated DataSignals write request.

Parameters#

dataAny: Mapping, sequence of mappings, or pandas DataFrame.
methodstr: Write method, either PUT or PATCH.
sitestr, optional: Default site for rows that omit the field.
locationstr, optional: Default location for rows that omit the field.
on_conflict{“replace”, “nothing”}, default “replace”: Conflict behavior defined by the backend endpoint.
include_cyclecountbool, default True: Whether metrics beginning with CC_ should be written.
profilebool, default False: Whether the backend should include timing information.

Returns#

DatasignalWriteRequest: Normalized method, query parameters, and payload.

parse_write_response(payload: Any) → dict[str, Any]#

Validate and return a DataSignals write response.

Parameters#

payloadAny: Decoded endpoint response.

Returns#

dict: Write result from the backend.

Raises#

ValueError: If the endpoint returns an unexpected successful response.