pyhaystack.client package

Subpackages

Submodules

pyhaystack.client.loader module

Haystack Implementation loader and factory. This module provides a simplified wrapper around importlib to allow implementation of a near-consistent interface for fetching session instances.

pyhaystack.client.loader.get_implementation(implementation)

Get an implementation of Project Haystack session manager based on the class name.

pyhaystack.client.loader.get_instance(implementation, *args, **kwargs)

Get an instance of a Project Haystack client.

pyhaystack.client.niagara module

Tridium Niagara Client support (AX and N4)

class pyhaystack.client.niagara.Niagara4HaystackSession(uri, username, password, grid_format='json', **kwargs)

Bases: pyhaystack.client.session.HaystackSession, pyhaystack.client.mixins.vendor.niagara.bql.BQLMixin, pyhaystack.client.mixins.vendor.niagara.encoding.EncodingMixin

The Niagara4HaystackSession class implements some base support for Niagara4. This is mainly a convenience for collecting the username and password details.

Initialise a Nagara 4 Project Haystack session handler.

Parameters:
  • uri – Base URI for the Haystack installation.
  • username – Authentication user name.
  • password – Authentication password.
  • grid_format – the grid format to use in series (json, zinc)
is_logged_in

Return true if the user is logged in.

class pyhaystack.client.niagara.NiagaraHaystackSession(uri, username, password, **kwargs)

Bases: pyhaystack.client.session.HaystackSession, pyhaystack.client.mixins.vendor.niagara.bql.BQLMixin, pyhaystack.client.mixins.vendor.niagara.encoding.EncodingMixin

The NiagaraHaystackSession class implements some base support for NiagaraAX. This is mainly a convenience for collecting the username and password details.

Initialise a Nagara Project Haystack session handler.

Parameters:
  • uri – Base URI for the Haystack installation.
  • username – Authentication user name.
  • password – Authentication password.
is_logged_in

Return true if the user is logged in.

pyhaystack.client.session module

Core Haystack Session client object interface. This file defines an abstract interface for Project Haystack clients and is responsible for opening and maintaining a session with the server.

class pyhaystack.client.session.HaystackSession(uri, api_dir, grid_format='zinc', http_client=<class 'pyhaystack.client.http.sync.SyncHttpClient'>, http_args=None, tagging_model=<class 'pyhaystack.client.entity.models.haystack.HaystackTaggingModel'>, log=None, pint=False, cache_expiry=3600.0)

Bases: object

The Haystack Session handler is responsible for presenting an API for querying and controlling a Project Haystack server.

HaystackSession itself is the base class, which is then implemented by way of HaystackOperation subclasses which are instantiated by the session object before being started and returned.

These operations by default are specified by class member references to the classes concerned.

Methods for Haystack operations return an ‘Operation’ object, which may be used in any of two ways:

  • as a synchronous result placeholder by calling its wait method

followed by inspection of its result attribute. - as an asynchronous call manager by connecting a “slot” (callable that takes keyword arguments) to the done_sig signal.

The base class takes some arguments that control the default behaviour of the object.

Initialise a base Project Haystack session handler.

Parameters:
  • uri – Base URI for the Haystack installation.
  • api_dir – Subdirectory relative to URI where API calls are made.
  • grid_format – What format to use for grids in GET/POST requests?
  • http_client – HTTP client class to use.
  • http_args – Optional HTTP client arguments to configure.
  • tagging_model – Entity Tagging model in use.
  • log – Logging object for reporting messages.
  • pint – Configure hszinc to use basic quantity or Pint Quanity
  • cache_expiry – Number of seconds before cached data expires.

See : https://pint.readthedocs.io/ for details about pint

FEATURE_HISREAD_MULTI = 'hisRead/multi'
FEATURE_HISWRITE_MULTI = 'hisWrite/multi'
FEATURE_ID_UUID = 'id_uuid'
about(cache=True, callback=None)

Retrieve the version information of this Project Haystack server.

authenticate(callback=None)

Authenticate with the Project Haystack server. If an authentication attempt is in progress, we return it, otherwise we instantiate a new one.

config_pint(value=False)
find_entity(filter_expr, limit=None, single=False, callback=None)

Retrieve instances of entities that match a filter expression.

Parameters:
  • filter_expr – The filter expression to search for.
  • limit – Optional limit to number of entities retrieved.
  • single – Are we expecting a single entity? Defaults to True if ids is not a list.
  • callback – Asynchronous result callback.
formats(cache=True, callback=None)

Retrieve the grid formats supported by this Project Haystack server.

get_entity(ids, refresh=False, single=None, callback=None)

Retrieve instances of entities, possibly refreshing them.

Parameters:
  • ids – A single entity ID, or a list of entity IDs.
  • refresh – Do we refresh the tags on those entities?
  • single – Are we expecting a single entity? Defaults to True if ids is not a list.
  • callback – Asynchronous result callback.
has_features(features, cache=True, callback=None)

Determine if a given feature is supported. This is a helper function for determining if the server implements a given feature. The feature is given as a string in the form of “base_feature/extension”.

Result is a dict of features and the states (boolean).

Parameters:features – Features to check for.
his_read(point, rng, callback=None)

point is either the ID of the historical point entity, or an instance of the historical point entity to read historical from. rng is either a string describing a time range (e.g. “today”, “yesterday”), a datetime.date object (providing all samples on the nominated day), a datetime.datetime (providing all samples since the nominated time) or a slice of datetime.dates or datetime.datetimes.

his_read_frame(columns, rng, tz=None, frame_format=None, callback=None)

Read the historical data of multiple given points and return them as a data frame.

Parameters:
  • columns – A list of Haystack ‘point’ instances or a dict mapping the column label to the Haystack ‘point’ instance.
  • rng – Historical read range for the ‘point’
  • tz – Optional timezone to translate timestamps to
  • frame_format – Optional desired format for the data frame
his_read_series(point, rng, tz=None, series_format=None, callback=None)

Read the historical data of the given point and return it as a series.

Parameters:
  • point – Haystack ‘point’ entity to read the data from
  • rng – Historical read range for the ‘point’
  • tz – Optional timezone to translate timestamps to
  • series_format – Optional desired format for the series
his_write(point, timestamp_records, callback=None)

point is either the ID of the writeable historical point entity, or an instance of the writeable historical point entity to write historical data to. timestamp_records should be a dict mapping timestamps (datetime.datetime) to the values to be written at those times, or a Pandas Series object.

his_write_frame(frame, columns=None, tz=None, callback=None)

Write the historical data of multiple given points.

Parameters:
  • frame – Data frame to write to. Columns either list explicit entity IDs or column aliases which are mapped in the columns parameter.
  • columns – If frame does not list explicit IDs, this should be a dict mapping the column names to either entity IDs or entity instances.
  • tz – Reference timestamp to use for writing, default is UTC.
his_write_series(point, series, tz=None, callback=None)

Write the historical data of the given point.

Parameters:
  • point – Haystack ‘point’ entity to read the data from
  • series – Historical series data to write
  • tz – Optional timezone to translate timestamps to
invoke_action(entity, action, callback=None, **kwargs)

entity is either the ID of the entity, or an instance of the entity to invoke the named action on. Keyword arguments give any additional parameters required for the user action.

nav(nav_id=None, callback=None)

The nav op is used navigate a project for learning and discovery. This operation allows servers to expose the database in a human-friendly tree (or graph) that can be explored.

ops(cache=True, callback=None)

Retrieve the operations supported by this Project Haystack server.

point_write(point, level=None, val=None, who=None, duration=None, callback=None)

point is either the ID of the writeable point entity, or an instance of the writeable point entity to retrieve the write status of or write a value to.

If level is None, the other parameters are required to be None too, the write status of the point is retrieved. Otherwise, a write is performed to the nominated point.

read(ids=None, filter_expr=None, limit=None, callback=None)

Retrieve information on entities matching the given criteria. Either ids or filter_expr may be given. ids may be given as a list or as a single ID string/reference.

filter_expr is given as a string. pyhaystack.util.filterbuilder may be useful for generating these programatically.

Parameters:
  • id – ID of a single entity to retrieve
  • ids – IDs of many entities to retrieve as a list
  • filter_expr – A filter expression that describes the entities of interest.
  • limit – A limit on the number of entities to return.
site

This helper will return the first site found on the server. This case is typical : having one site per server.

sites

This helper will return all sites found on the server.

watch_poll(watch, refresh=False, callback=None)

watch is either the value of watch_id given when creating a watch, or an instance of a Watch object.

If refresh is True, then all points on the watch will be updated, not just those that have changed since the last poll.

watch_sub(points, watch_id=None, watch_dis=None, lease=None, callback=None)

This creates a new watch with debug string watch_dis, identifier watch_id (string) and a lease time of lease (integer) seconds. points is a list of strings, Entity objects or hszinc.Ref objects.

watch_unsub(watch, points=None, callback=None)

watch is either the value of watch_id given when creating a watch, or an instance of a Watch object.

If points is not None, it is a list of strings, Entity objects or hszinc.Ref objects which will be removed from the Watch object. Otherwise, it closes the Watch object.

pyhaystack.client.skyspark module

Skyspark Client support

class pyhaystack.client.skyspark.SkysparkHaystackSession(uri, username, password, project='', **kwargs)

Bases: pyhaystack.client.session.HaystackSession, pyhaystack.client.mixins.vendor.skyspark.evalexpr.EvalOpsMixin

The SkysparkHaystackSession class implements some base support for Skyspark servers.

Initialise a Skyspark Project Haystack session handler.

Parameters:
  • uri – Base URI for the Haystack installation.
  • username – Authentication user name.
  • password – Authentication password.
  • project – Skyspark project name
is_logged_in

Return true if the user is logged in.

class pyhaystack.client.skyspark.SkysparkScramHaystackSession(uri, username, password, project, **kwargs)

Bases: pyhaystack.client.session.HaystackSession, pyhaystack.client.mixins.vendor.skyspark.evalexpr.EvalOpsMixin

The SkysparkHaystackSession class implements some base support for Skyspark servers.

Initialise a Skyspark Project Haystack session handler.

Parameters:
  • uri – Base URI for the Haystack installation.
  • username – Authentication user name.
  • password – Authentication password.
  • project – Skyspark project name
is_logged_in

Return true if the user is logged in.

pyhaystack.client.widesky module

VRT Widesky Client support

class pyhaystack.client.widesky.WideskyHaystackSession(uri, username, password, client_id, client_secret, api_dir='api', auth_dir='oauth2/token', **kwargs)

Bases: pyhaystack.client.mixins.vendor.widesky.crud.CRUDOpsMixin, pyhaystack.client.mixins.vendor.widesky.multihis.MultiHisOpsMixin, pyhaystack.client.session.HaystackSession

The WideskyHaystackSession class implements some base support for Widesky servers. This is mainly a convenience for collecting the username and password details.

Initialise a VRT Widesky Project Haystack session handler.

Parameters:
  • uri – Base URI for the Haystack installation.
  • username – Authentication user name.
  • password – Authentication password.
  • client_id – Authentication client ID.
  • client_secret – Authentication client secret.
is_logged_in

Return true if the user is logged in.

Module contents

Haystack Client interface

pyhaystack.client.get_implementation(implementation)

Get an implementation of Project Haystack session manager based on the class name.

pyhaystack.client.get_instance(implementation, *args, **kwargs)

Get an instance of a Project Haystack client.