Subpackages¶

Submodules¶

pyhaystack.client.entity.entity module¶

High-level Entity interface.

class pyhaystack.client.entity.entity.DeletableEntity(session, entity_id)¶

Bases: pyhaystack.client.entity.entity.Entity

Class to represent entities that can be deleted from the Haystack server (the server implements the ‘delete’ operation).

Initialise a new high-level entity object.

Parameters:	session – The connection session object. entity_id – The entity’s fully qualified ID.

delete(callback=None)¶

Delete the entity.

class pyhaystack.client.entity.entity.Entity(session, entity_id)¶

Bases: object

A base class for Project Haystack entities. This is a base class that is then combined with mix-ins depending on the tags present for the entity and the tagging model in use (by default, we use the “Project Haystack” tagging model, but others such as ISA-95 may exist).

This base class just exposes the tags, and if supported by the server, may expose the ability to update those tags.

Initialise a new high-level entity object.

Parameters:	session – The connection session object. entity_id – The entity’s fully qualified ID.

dis¶

Return the description field of the entity.

id¶

Return the fully qualified ID of this entity.

tags¶

Return the tags of this entity.

exception pyhaystack.client.entity.entity.StaleEntityInstanceError¶

Bases: exceptions.Exception

Exception thrown when an entity instance is “stale”, that is, the entity class type no longer matches the tag set present in the entity.

pyhaystack.client.entity.model module¶

Tagging Model Interface.

class pyhaystack.client.entity.model.TaggingModel(session)¶

Bases: object

A base class for representing tagging models. The tagging model is responsible for considering the tags present on a new entity then instantiating an appropriate data type based on those tags seen.

Initialise a new tagging model.

create_entity(entity_id, tags)¶

Create an Entity instance based on the tags present.

pyhaystack.client.entity.tags module¶

Entity tag interface. This file implements the interfaces that will be used to access and store tags of an entity.

class pyhaystack.client.entity.tags.BaseEntityTags(entity)¶

Bases: object

A base class for storing entity tags.

Initialise a new high-level entity tag storage object.

Parameters:	session – The connection session object. entity_id – The entity’s fully qualified ID.

class pyhaystack.client.entity.tags.BaseMutableEntityTags(entity)¶

Bases: pyhaystack.client.entity.tags.BaseEntityTags

A base class for entity tags that supports modifications to the tag set.

commit(callback=None)¶

Commit any to-be-sent updates for this entity.

is_dirty¶

Returns true if there are modifications pending submission.

revert(tags=None)¶

Revert the named attribute changes, or all changes.

class pyhaystack.client.entity.tags.MutableEntityTags(entity)¶

Bases: pyhaystack.client.entity.tags.BaseMutableEntityTags, _abcoll.MutableMapping

class pyhaystack.client.entity.tags.ReadOnlyEntityTags(entity)¶

Bases: pyhaystack.client.entity.tags.BaseEntityTags, _abcoll.Mapping

Initialise a new high-level entity tag storage object.

Parameters:	session – The connection session object. entity_id – The entity’s fully qualified ID.

Module contents¶

Submodules¶

pyhaystack.client.http.auth module¶

Base HTTP client authentication classes. These classes simply act as containers for authentication methods defined in the HTTP spec.

class pyhaystack.client.http.auth.AuthenticationCredentials¶

Bases: object

A base class to represent authentication credentials.

class pyhaystack.client.http.auth.BasicAuthenticationCredentials(username, password)¶

Bases: pyhaystack.client.http.auth.UserPasswordAuthenticationCredentials

A class that represents Basic authentication.

class pyhaystack.client.http.auth.DigestAuthenticationCredentials(username, password)¶

Bases: pyhaystack.client.http.auth.UserPasswordAuthenticationCredentials

A class that represents Digest authentication.

class pyhaystack.client.http.auth.UserPasswordAuthenticationCredentials(username, password)¶

Bases: pyhaystack.client.http.auth.AuthenticationCredentials

A base class that represents username/password type authentication.

pyhaystack.client.http.base module¶

Base HTTP client handler class. This wraps a HTTP client library in a consistent interface to make processing and handling of requests more convenient and to aid portability of pyhaystack.

class pyhaystack.client.http.base.HTTPClient(uri=None, params=None, headers=None, cookies=None, auth=None, timeout=None, proxies=None, tls_verify=None, tls_cert=None, log=None)¶

Bases: object

The base HTTP client interface. This class defines methods for making HTTP requests in a unified manner. The interface presented is an asynchronous one, even for synchronous implementations.

Instantiate a HTTP client instance with some default parameters. These parameters are made accessible as properties to be modified at will by the caller as needed.

Parameters:

uri – Base URI for all requests. If given, this string will be pre-pended to all requests passed through this client. params – A dictionary of key-value pairs to be passed as URI query parameters. headers – A dictionary of key-value pairs to be passed as HTTP headers. cookies – A dictionary of key-value pairs to be passed as cookies. auth – An instance of a HttpAuth object. timeout – An integer or float giving the default maximum time duration for requests before timing out. proxies – A dictionary mapping the hostname and protocol to a proxy server URI. tls_verify – For TLS servers, this determines whether the server is validated or not. It should be the path to the CA certificate file for this server, or alternatively can be set to ‘True’ to verify against CAs known to the client. (e.g. OS certificate store) tls_cert – For TLS servers, this specifies the certificate used by the client to authenticate itself with the server. log – If not None, then it’s a logging object that will be used for debugging HTTP operations.

PROTO_RE = <_sre.SRE_Pattern object>¶

get(uri, callback, **kwargs)¶

Convenience function: perform a HTTP GET operation. Arguments are the same as for request.

post(uri, callback, body=None, body_type=None, body_size=None, headers=None, **kwargs)¶

Convenience function: perform a HTTP POST operation. Arguments are the same as for request.

Parameters:	body – Body data to be posted in this request as a string. body_type – Body MIME data type. This is a convenience for setting the Content-Type header. body_size – Length of the body to be sent. If None, the length is autodetected. Set to False to avoid this.

request(method, uri, callback, body=None, params=None, headers=None, cookies=None, auth=None, timeout=None, proxies=None, tls_verify=None, tls_cert=None, exclude_params=None, exclude_headers=None, exclude_cookies=None, exclude_proxies=None)¶

Perform a request with this client. Most parameters here exist to either add to or override the defaults given by the client attributes. The parameters exclude_... serve to allow selective removal of defaults.

Parameters:

method – The HTTP method to request. uri – URL for this request. If this is a relative URL, it will be relative to the URL given by the ‘uri’ attribute. callback – A callback function that will be presented with the result of this request. body – An optional body for the request. params – A dictionary of key-value pairs to be passed as URI query parameters. headers – A dictionary of key-value pairs to be passed as HTTP headers. cookies – A dictionary of key-value pairs to be passed as cookies. auth – An instance of a HttpAuth object. timeout – An integer or float giving the default maximum time duration for requests before timing out. proxies – A dictionary mapping the hostname and protocol to a proxy server URI. tls_verify – For TLS servers, this determines whether the server is validated or not. It should be the path to the CA certificate file for this server, or alternatively can be set to ‘True’ to verify against CAs known to the client. (e.g. OS certificate store) tls_cert – For TLS servers, this specifies the certificate used by the client to authenticate itself with the server. exclude_params – If True, exclude all default parameters and use only the parameters given. Otherwise, this is an iterable of parameter names to be excluded. exclude_headers – If True, exclude all default headers and use only the headers given. Otherwise, this is an iterable of header names to be excluded. exclude_cookies – If True, exclude all default cookies and use only the cookies given. Otherwise, this is an iterable of cookie names to be excluded. exclude_proxies – If True, exclude all default proxies and use only the proxies given. Otherwise, this is an iterable of proxy names to be excluded.

class pyhaystack.client.http.base.HTTPResponse(status_code, headers, body, cookies=None)¶

Bases: object

A class that represents the raw response from a HTTP request.

content_type¶

Return the content type of the body.

content_type_args¶

Return the content type arguments of the body.

text¶

Attempt to decode the raw body into text based on the encoding given.

pyhaystack.client.http.exceptions module¶

HTTP client exception classes.

exception pyhaystack.client.http.exceptions.HTTPBaseError¶

Bases: exceptions.IOError

Error class to represent a HTTP errors.

exception pyhaystack.client.http.exceptions.HTTPConnectionError¶

Bases: pyhaystack.client.http.exceptions.HTTPBaseError

Error class to represent a failed attempt to connect to a host.

exception pyhaystack.client.http.exceptions.HTTPRedirectError¶

Bases: pyhaystack.client.http.exceptions.HTTPBaseError

Error class to represent that the server’s redirections are looping.

exception pyhaystack.client.http.exceptions.HTTPStatusError(message, status, headers=None, body=None)¶

Bases: pyhaystack.client.http.exceptions.HTTPBaseError

Error class to represent a returned failed status from the host.

exception pyhaystack.client.http.exceptions.HTTPTimeoutError¶

Bases: pyhaystack.client.http.exceptions.HTTPConnectionError

Error class to represent that a request timed out.

pyhaystack.client.http.sync module¶

Synchronous HTTP client using Python Requests.

class pyhaystack.client.http.sync.SyncHttpClient(**kwargs)¶

Bases: pyhaystack.client.http.base.HTTPClient

Module contents¶

Subpackages¶

Module contents¶

Subpackages¶

Submodules¶

pyhaystack.client.ops.entity module¶

Entity state machines. These are state machines that perform CRUD operations on entities.

class pyhaystack.client.ops.entity.EntityRetrieveOperation(session, single)¶

Bases: pyhaystack.util.state.HaystackOperation

Base class for retrieving entity instances.

Initialise a request for the named IDs.

Parameters:	session – Haystack HTTP session object.

class pyhaystack.client.ops.entity.FindEntityOperation(session, filter_expr, limit, single)¶

Bases: pyhaystack.client.ops.entity.EntityRetrieveOperation

Operation for retrieving entity instances by filter. This operation peforms the following steps:

Issue a read instruction with the given filter:
    For each row returned in grid:
        If entity is not in cache:
            Create new Entity instances for each row returned.
        Else:
            Update existing Entity instance with new row data.
        Add the new entity instances to cache and store.
    Return the stored entities. 
    # State: done              

Initialise a request for the named IDs.

Parameters:	session – Haystack HTTP session object. filter_expr – Filter expression. limit – Maximum number of entities to fetch.

go()¶

Start the request, check cache for existing entities.

class pyhaystack.client.ops.entity.GetEntityOperation(session, entity_ids, refresh_all, single)¶

Bases: pyhaystack.client.ops.entity.EntityRetrieveOperation

Operation for retrieving entity instances by ID. This operation peforms the following steps:

If refresh_all is False:                  
# State: init
    For each entity_id in entity_ids:
        If entity_id exists in cache:
            Retrieve and store entity from cache.
            Add entity_id to list got_ids.
    For each entity_id in got_ids:
        Discard entity_id from entity_ids.
If entity_ids is not empty:               
# State: read
    Perform a low-level read of the IDs.
    For each row returned in grid:
        If entity is not in cache:
            Create new Entity instances for each row returned.
        Else:
            Update existing Entity instance with new row data.
    Add the new entity instances to cache and store.
Return the stored entities.                      
# State: done

Initialise a request for the named IDs.

Parameters:	session – Haystack HTTP session object. entity_ids – A list of IDs to request. refresh_all – Refresh all entities, ignore existing content.

go()¶

Start the request, check cache for existing entities.

pyhaystack.client.ops.grid module¶

Low-level grid state machines. These are state machines that perform GET or POST requests involving Haystack ZINC grids.

class pyhaystack.client.ops.grid.BaseGridOperation(session, uri, args=None, expect_format='zinc', multi_grid=False, raw_response=False, retries=2)¶

Bases: pyhaystack.util.state.HaystackOperation

A base class for GET and POST operations involving grids.

Initialise a request for the grid with the given URI and arguments.

Parameters:

session – Haystack HTTP session object. uri – Possibly partial URI relative to the server base address to perform a query. No arguments shall be given here. expect_format – Request that the grid be sent in the given format. args – Dictionary of key-value pairs to be given as arguments. multi_grid – Boolean indicating if we are to expect multiple grids or not. If True, then the operation will _always_ return a list, otherwise, it will _always_ return a single grid. raw_response – Boolean indicating if we should try to parse the result. If True, then we should just pass back the raw HTTPResponse object. retries – Number of retries permitted in case of failure.

go()¶

Start the request.

class pyhaystack.client.ops.grid.GetGridOperation(session, uri, args=None, multi_grid=False, **kwargs)¶

Bases: pyhaystack.client.ops.grid.BaseGridOperation

A state machine that performs a GET operation then reads back a ZINC grid.

Initialise a GET request for the grid with the given URI and arguments.

Parameters:

session – Haystack HTTP session object. uri – Possibly partial URI relative to the server base address to perform a query. No arguments shall be given here. args – Dictionary of key-value pairs to be given as arguments. multi_grid – Boolean indicating if we are to expect multiple grids or not. If true, then the operation will _always_ return a list, otherwise, it will _always_ return a single grid.

class pyhaystack.client.ops.grid.PostGridOperation(session, uri, grid, args=None, post_format='zinc', **kwargs)¶

Bases: pyhaystack.client.ops.grid.BaseGridOperation

A state machine that performs a POST operation with a ZINC grid then may read back a ZINC grid.

Initialise a POST request for the grid with the given grid, URI and arguments.

Parameters:	session – Haystack HTTP session object. uri – Possibly partial URI relative to the server base address to perform a query. No arguments shall be given here. grid – Grid (or grids) to be posted to the server. post_format – What format to post grids in? args – Dictionary of key-value pairs to be given as arguments.

pyhaystack.client.ops.his module¶

High-level history functions. These wrap the basic his_read function to allow some alternate representations of the historical data.

class pyhaystack.client.ops.his.HisReadFrameOperation(session, columns, rng, tz, frame_format)¶

Bases: pyhaystack.util.state.HaystackOperation

Read the series data from several ‘point’ entities and present them in a concise format.

Read the series data and return it.

Parameters:	session – Haystack HTTP session object. columns – IDs of historical point objects to read. rng – Range to read from ‘point’ tz – Timezone to translate timezones to. May be None. frame_format – What format to present the frame in.

FORMAT_DICT = 'dict'¶

FORMAT_FRAME = 'frame'¶

FORMAT_LIST = 'list'¶

go()¶

class pyhaystack.client.ops.his.HisReadSeriesOperation(session, point, rng, tz, series_format)¶

Bases: pyhaystack.util.state.HaystackOperation

Read the series data from a ‘point’ entity and present it in a concise format.

Read the series data and return it.

Parameters:	session – Haystack HTTP session object. point – ID of historical ‘point’ object to read. rng – Range to read from ‘point’ tz – Timezone to translate timezones to. May be None. series_format – What format to present the series in.

FORMAT_DICT = 'dict'¶

FORMAT_LIST = 'list'¶

FORMAT_SERIES = 'series'¶

go()¶

class pyhaystack.client.ops.his.HisWriteFrameOperation(session, columns, frame, tz)¶

Bases: pyhaystack.util.state.HaystackOperation

Write the series data to several ‘point’ entities.

Write the series data.

Parameters:	session – Haystack HTTP session object. columns – IDs of historical point objects to read. frame – Range to read from ‘point’ tz – Timezone to translate timezones to.

go()¶

class pyhaystack.client.ops.his.HisWriteSeriesOperation(session, point, series, tz)¶

Bases: pyhaystack.util.state.HaystackOperation

Write the series data to a ‘point’ entity.

Write the series data to the point.

Parameters:	session – Haystack HTTP session object. point – ID of historical ‘point’ object to write. series – Series data to be written to the point. tz – If not None, a datetime.tzinfo instance for this write.

go()¶

class pyhaystack.client.ops.his.MetaDataFrame(*args, **kw)¶

Bases: pandas.core.frame.DataFrame

Custom Pandas Dataframe with meta data Made from MetaSeries

add_meta(key, value)¶

meta = {}¶

class pyhaystack.client.ops.his.MetaSeries(data=None, index=None, dtype=None, name=None, copy=False, fastpath=False)¶

Bases: pandas.core.series.Series

Custom Pandas Serie with meta data

add_meta(key, value)¶

meta = {}¶

Module contents¶