Types¶

Haystack value types and the server operations layer.

Kinds¶

Haystack value types as frozen dataclasses. Includes Marker, Number, Ref, Coord, Symbol, Uri, XStr, Na, and Remove with singleton instances MARKER, NA, and REMOVE.

Haystack data type kinds.

Implements all Project Haystack scalar and singleton value types as immutable Python objects. Collection types (list, dict) and passthrough types (bool, str, datetime.date, datetime.time, datetime.datetime) use their native Python equivalents directly.

See: https://project-haystack.org/doc/docHaystack/Kinds

hs_py.kinds.MARKER: Marker = Marker¶: Canonical Marker instance.

hs_py.kinds.NA: Na = Na¶: Canonical NA instance.

hs_py.kinds.REMOVE: Remove = Remove¶: Canonical Remove instance.

class hs_py.kinds.Coord(lat, lng)[source]¶

Bases: object

Geographic coordinate as latitude/longitude in decimal degrees.

Parameters:

lat (float)
lng (float)

lat: float¶: Latitude in decimal degrees (-90 to 90).

lng: float¶: Longitude in decimal degrees (-180 to 180).

class hs_py.kinds.Marker[source]¶

Bases: _Singleton

Marker tag singleton.

Marker is a label type used to express typing information.

Return type:: _Singleton

class hs_py.kinds.Na[source]¶

Bases: _Singleton

NA (not available) singleton.

Represents missing or invalid data, analogous to R’s NA.

Return type:: _Singleton

class hs_py.kinds.Number(val, unit=None)[source]¶

Bases: object

Numeric value with optional unit of measurement.

Supports special IEEE 754 values: NaN, INF, -INF.

Parameters:

val (float)
unit (str | None)

val: float¶: Numeric value (may be NaN, INF, or -INF).

unit: str | None¶: Optional unit of measurement (e.g. "°F", "kW").

class hs_py.kinds.Ref(val, dis=None)[source]¶

Bases: object

Entity reference identifier.

val is an opaque identifier string containing only ASCII letters, digits, underbar, colon, dash, period, and tilde.

Parameters:

val (str)
dis (str | None)

val: str¶: Opaque identifier string (ASCII letters, digits, _:-.~).

dis: str | None¶: Optional human-readable display name.

class hs_py.kinds.Remove[source]¶

Bases: _Singleton

Remove singleton.

Indicates a tag should be removed from a dict.

Return type:: _Singleton

class hs_py.kinds.Symbol(val)[source]¶

Bases: object

Definition name constant (e.g. ^elec-meter).

Parameters:: val (str)

val: str¶: Symbol name without the leading ^.

class hs_py.kinds.Uri(val)[source]¶

Bases: object

Universal Resource Identifier per RFC 3986.

Parameters:: val (str)

val: str¶: URI string value.

class hs_py.kinds.XStr(type_name, val)[source]¶

Bases: object

Extended string: a typed string tuple.

type_name must start with an uppercase ASCII letter.

Parameters:

type_name (str)
val (str)

type_name: str¶: Type name (must start with an uppercase ASCII letter).

val: str¶: String payload.

hs_py.kinds.is_haystack_type(val)[source]¶

Return True if val is a valid Haystack value kind.

Parameters:: val (Any) – Value to check.
Return type:: bool
Returns:: Whether val is None or an instance of a Haystack kind.

hs_py.kinds.sym_name(s)[source]¶

Normalize a symbol argument to its string name.

Parameters:: s (str | Symbol) – A Symbol or plain string.
Return type:: str
Returns:: The bare symbol name string.

Watch¶

Watch state tracking and delta encoding for subscription-based data updates.

Watch state tracking with delta encoding and server-side filtering.

Provides WatchState for server-side delta computation and WatchAccumulator for client-side delta merging. Both classes track entity state per watch subscription to minimise push payload size.

Server-side filtering evaluates a Haystack filter expression against entities before pushing, so clients only receive matching changes.

class hs_py.watch.WatchAccumulator[source]¶

Bases: object

Client-side state accumulator for delta watch pushes.

Merges incoming delta grids into a full entity state cache.

apply_delta(delta)[source]¶

Merge a delta grid into the accumulated state.

New entities are added.
Changed tags are updated.
Tags with REMOVE value are deleted.
Rows with _removed marker are removed entirely.

Parameters:: delta (Grid) – Delta grid from the server.
Return type:: None

property entities: dict[str, dict[str, Any]]¶: Return the current accumulated entity state.

to_grid()[source]¶

Return the accumulated state as a Grid.

Return type:: Grid

get(entity_id)[source]¶

Look up a single entity by ID.

Parameters:: entity_id (str) – Entity identifier string.
Return type:: dict[str, Any] | None
Returns:: Tag dict, or None if not present.

class hs_py.watch.WatchState(watch_id, *, filter_ast=None)[source]¶

Bases: object

Server-side entity state tracker for a single watch.

Maintains a cache of the last-sent entity state so that compute_delta() can emit only changed, new, or removed tags on each push cycle.

Parameters:

watch_id (str) – The watch identifier.
filter_ast (Has | Missing | Cmp | And | Or | None (default: None)) – Optional parsed filter AST for server-side filtering.

compute_delta(current)[source]¶

Compute a delta grid from the current full state.

New entities (not in cache) are included in full.
Changed tags are included with their new values.
Removed tags are represented as REMOVE.
Entities in the cache but absent from current get an _removed marker row.

Parameters:: current (Grid) – Full current state of watched entities.
Return type:: Grid
Returns:: Grid with only the changes since last push.

update(current)[source]¶

Update the cache with the current full entity state.

Call this after compute_delta() to keep the cache in sync.

Parameters:: current (Grid) – Full current state of watched entities.
Return type:: None

apply_filter(grid)[source]¶

Filter a grid using the watch’s filter expression.

If no filter is configured, returns the grid unchanged.

Parameters:: grid (Grid) – Grid of entities to filter.
Return type:: Grid
Returns:: Filtered grid with only matching rows.

Ops¶

Server-side Haystack operation dispatch layer.

Haystack server operations base class and op registry.

Provides HaystackOps, the abstract base for all server-side operation dispatchers, and the op-name-to-method-name mappings used by HTTP and WebSocket handlers.

class hs_py.ops.HaystackOps(storage=None, namespace=None)[source]¶

Bases: object

Base class for Haystack server operations.

Subclass and override the operations you support. When a storage adapter is provided the base-class implementations automatically parse the request Grid, delegate to the adapter, and wrap the result back into a Grid. Without an adapter, unimplemented POST ops return an error grid. The ops() and formats() methods have useful defaults.

Parameters:

storage (StorageAdapter | None)
namespace (Namespace | None)

async about()[source]¶

Return server information.

The default implementation returns minimal metadata. Subclasses may override this to include richer details such as serverName or vendorUri.

Return type:: Grid

async ops()[source]¶

Return the list of supported operations.

Auto-discovers which methods the subclass has overridden, plus storage-backed ops (when a storage adapter is present) and namespace-backed ops (when a namespace is present).

Return type:: Grid

async formats()[source]¶

Return supported data formats per Haystack filetypes op.

Reports all MIME types this server can send and/or receive.

Return type:: Grid

async on_close()[source]¶

Handle server close request. Default: no-op.

Return type:: None

async read(grid)[source]¶

Read entities by id or filter.

Return type:: Grid
Parameters:: grid (Grid)

async nav(grid)[source]¶

Navigate the entity tree.

Return type:: Grid
Parameters:: grid (Grid)

async his_read(grid)[source]¶

Read time-series data.

Return type:: Grid
Parameters:: grid (Grid)

async his_write(grid)[source]¶

Write time-series data.

Return type:: Grid
Parameters:: grid (Grid)

async point_write(grid)[source]¶

Write to a point’s priority array.

Return type:: Grid
Parameters:: grid (Grid)

async watch_sub(grid)[source]¶

Subscribe to a watch.

Return type:: Grid
Parameters:: grid (Grid)

async watch_unsub(grid)[source]¶

Unsubscribe from a watch.

Return type:: Grid
Parameters:: grid (Grid)

async watch_poll(grid)[source]¶

Poll a watch for changes.

Return type:: Grid
Parameters:: grid (Grid)

async invoke_action(grid)[source]¶

Invoke an action on an entity.

Return type:: Grid
Parameters:: grid (Grid)

async defs(grid)[source]¶

Query ontology definitions.

Return type:: Grid
Parameters:: grid (Grid)

async libs(grid)[source]¶

Query ontology libraries.

Return type:: Grid
Parameters:: grid (Grid)

async filetypes(grid)[source]¶

Query supported file types.

Return type:: Grid
Parameters:: grid (Grid)

set_push_handler(handler)[source]¶

Set the push handler for watch notifications.

Called by the server framework to wire up push delivery. Subclasses should not override this method.

Parameters:: handler (Callable[[str, Grid], Awaitable[None]]) – Async callable invoked with (watch_id, grid).
Return type:: None

async push_watch(watch_id, grid)[source]¶

Push changed entities to subscribed watch clients.

Parameters:

watch_id (str) – The watch identifier.
grid (Grid) – Grid of changed entities.

Return type:

None