sttp package

Subpackages

Submodules

sttp.config module

class sttp.config.Config(maxretries: int = Ellipsis, retryinterval: float = Ellipsis, maxretryinterval: float = Ellipsis, autoreconnect: bool = Ellipsis, autorequestmetadata: bool = Ellipsis, autosubscribe: bool = Ellipsis, compress_payloaddata: bool = Ellipsis, compress_metadata: bool = Ellipsis, compress_signalindexcache: bool = Ellipsis, metadatafilters: str = Ellipsis, socket_timeout: float = Ellipsis, version: int8 = Ellipsis)[source]

Bases: object

Defines the STTP connection related configuration parameters.

DEFAULT_AUTORECONNECT = True
DEFAULT_AUTOREQUESTMETADATA = True
DEFAULT_AUTOSUBSCRIBE = True
DEFAULT_COMPRESS_METADATA = True
DEFAULT_COMPRESS_PAYLOADDATA = True
DEFAULT_COMPRESS_SIGNALINDEXCACHE = True
DEFAULT_MAXRETRIES = -1
DEFAULT_MAXRETRYINTERVAL = 30.0
DEFAULT_METADATAFILTERS = ''
DEFAULT_RETRYINTERVAL = 1.0
DEFAULT_SOCKET_TIMEOUT = 2.0
DEFAULT_VERSION = np.int8(2)
autoreconnect

Defines flag that determines if connections should be automatically reattempted.

autorequestmetadata

Defines the flag that determines if metadata should be automatically requested upon successful connection. When True, metadata will be requested upon connection before subscription; otherwise, any metadata operations must be handled manually.

autosubscribe

Defines the flag that determines if subscription should be handled automatically upon successful connection. When autorequestmetadata is True and autosubscribe is True, subscription will occur after reception of metadata. When autorequestmetadata is False and autosubscribe is True, subscription will occur at successful connection. When autosubscribe is False, any subscribe operations must be handled manually.

compress_metadata

Determines whether the metadata transfer is compressed.

compress_payloaddata

Determines whether payload data is compressed.

compress_signalindexcache

Determines whether the signal index cache is compressed.

maxretries

Defines the maximum number of times to retry a connection. Set value to -1 to retry infinitely.

maxretryinterval

Defines the maximum retry interval, in seconds.

metadatafilters

Defines any filters to be applied to incoming metadata to reduce total received metadata. Each filter expression should be separated by semi-colon.

retryinterval

Defines the base retry interval, in seconds. Retries will exponentially back-off starting from this interval.

socket_timeout

Defines the timeout in seconds for all socket connections.

version

Defines the target STTP protocol version. This currently defaults to 2.

sttp.reader module

class sttp.reader.MeasurementReader(subscriber: Subscriber)[source]

Bases: object

Defines an STTP measurement reader.

dispose()[source]

Cleanly shuts down a MeasurmentReader that is no longer being used. This method will release any waiting threads.

next_measurement() → Tuple[Measurement | None, bool][source]

Blocks current thread until a new measurement arrived.

sttp.settings module

class sttp.settings.Settings(throttled: bool = Ellipsis, publishinterval: float = Ellipsis, udpport: uint16 = Ellipsis, udpinterface: str = Ellipsis, includetime: bool = Ellipsis, enabletimereasonabilitycheck: bool = Ellipsis, lagtime: float64 = Ellipsis, leadtime: float64 = Ellipsis, uselocalclockasrealtime: bool = Ellipsis, usemillisecondresolution: bool = Ellipsis, requestnanvaluefilter: bool = Ellipsis, starttime: str = Ellipsis, stoptime: str = Ellipsis, constraintparameters: str = Ellipsis, processinginterval: int = Ellipsis, extra_connectionstring_parameters: str = Ellipsis)[source]

Bases: object

Defines the STTP subscription related settings.

Notes

The Settings class exists as a simplified implementation of the SubscriptionInfo class found in the transport namespace. Internally, the Subscriber class maps Settings values to a SubscriptionInfo instance for use with a DataSubscriber.

DEFAULT_CONSTRAINTPARAMETERS = ''
DEFAULT_ENABLE_TIME_REASONABILITY_CHECK = False
DEFAULT_EXTRA_CONNECTIONSTRING_PARAMETERS = ''
DEFAULT_INCLUDETIME = True
DEFAULT_LAGTIME = np.float64(10.0)
DEFAULT_LEADTIME = np.float64(5.0)
DEFAULT_PROCESSINGINTERVAL = np.int32(-1)
DEFAULT_PUBLISHINTERVAL = np.float64(1.0)
DEFAULT_REQUEST_NANVALUEFILTER = False
DEFAULT_STARTTIME = ''
DEFAULT_STOPTIME = ''
DEFAULT_THROTTLED = False
DEFAULT_UDPINTERFACE = ''
DEFAULT_UDPPORT = np.uint16(0)
DEFAULT_USE_LOCALCLOCK_AS_REALTIME = False
DEFAULT_USE_MILLISECONDRESOLUTION = False
constraintparameters

Defines any custom constraint parameters for a requested temporal data playback. This can include parameters that may be needed to initiate, filter, or control historical data access.

enabletimereasonabilitycheck

Determines if publisher should perform time reasonability checks. When enabled lagtime and leadtime will be used to determine if a measurement timestamp is reasonable.

extra_connectionstring_parameters

Defines any extra custom connection string parameters that may be needed for a subscription.

includetime

Determines if time should be included in non-compressed, compact measurements.

lagtime

Defines defines the allowed past time deviation tolerance in seconds (can be sub-second). Value is used to determine if a measurement timestamp is reasonable. Only applicable when enabletimereasonabilitycheck is true.

leadtime

Defines defines the allowed future time deviation tolerance in seconds (can be sub-second). Value is used to determine if a measurement timestamp is reasonable. Only applicable when enabletimereasonabilitycheck is true.

processinginterval

Defines the initial playback speed, in milliseconds, for a requested temporal data playback. With the exception of the values of -1 and 0, this value specifies the desired processing interval for data, i.e., basically a delay, or timer interval, over which to process data. A value of -1 means to use the default processing interval while a value of 0 means to process data as fast as possible.

publishinterval

Defines the down-sampling publish interval, in seconds, to use when throttled is True.

request_nanvaluefilter

Requests that the publisher filter, i.e., does not send, any NaN values.

starttime

Defines the start time for a requested temporal data playback, i.e., a historical subscription. Simply by specifying a starttime and stoptime, a subscription is considered a historical subscription. Note that the publisher may not support historical subscriptions, in which case the subscribe will fail.

stoptime

Defines the stop time for a requested temporal data playback, i.e., a historical subscription. Simply by specifying a starttime and stoptime, a subscription is considered a historical subscription. Note that the publisher may not support historical subscriptions, in which case the subscribe will fail.

throttled

Determines if data will be published using down-sampling.

udpinterface

Defines the desired UDP binding interface to use for publication. Empty string means to bind to all interfaces.

udpport

Defines the desired UDP port to use for publication. Zero value means do not receive data on UDP, i.e., data will be delivered to the STTP client via TCP.

use_millisecondresolution

Determines if time should be restricted to milliseconds in non-compressed, compact measurements.

uselocalclockasrealtime

Determines if publisher should use local clock as real time. If false, the timestamp of the latest measurement will be used as real-time. Only applicable when enabletimereasonabilitycheck is true.

sttp.subscriber module

class sttp.subscriber.Subscriber[source]

Bases: object

Represents an STTP data subscriber.

Notes

The Subscriber class exists as a simplified implementation of the DataSubscriber class found in the transport namespace. This class maintains an internal instance of the DataSubscriber class for subscription based functionality and is intended to simplify common uses of STTP data reception.

property activesignalindexcache: SignalIndexCache

Gets the active signal index cache.

adjustedvalue(measurement: Measurement) → float64[source]

Gets the Value of a Measurement with any linear adjustments applied from the measurement’s Adder and Multiplier metadata, if found.

connect(address: str, config: Config = Ellipsis) → Exception | None[source]

Starts the client-based connection cycle to an STTP publisher. Config parameter controls connection related settings. When the config defines AutoReconnect as True, the connection will automatically be retried when the connection drops. If the config parameter defines AutoRequestMetadata as True, then upon successful connection, meta-data will be requested. When the config defines both AutoRequestMetadata and AutoSubscribe as True, subscription will occur after reception of metadata. When the config defines AutoRequestMetadata as False and AutoSubscribe as True, subscription will occur at successful connection.

property connected: bool

Gets flag that determines if Subscriber is currently connected to a data publisher.

default_connectionestablished_receiver()[source]

Implements the default handler for the connection established callback. Default implementation simply writes connection feedback to status message callback.

default_connectionterminated_receiver()[source]

Implements the default handler for the connection terminated callback. Default implementation simply writes connection terminated feedback to error message callback.

default_errormessage_logger(message: str)[source]

Implements the default handler for the error message callback. Default implementation synchronously writes output to stderr. Logging is recommended.

default_statusmessage_logger(message: str)[source]

Implements the default handler for the status message callback. Default implementation synchronously writes output to stdio. Logging is recommended.

disconnect()[source]

Disconnects from an STTP publisher.

dispose()[source]

Cleanly shuts down a Subscriber that is no longer being used, e.g., during a normal application exit.

errormessage(message: str)[source]

Executes the defined error message logger callback.

measurement_metadata(measurement: Measurement) → MeasurementRecord[source]

Gets the MeasurementRecord for the specified measurement, based on its signal ID, from the local metadata cache; or, None if the measurement cannot be found.

property metadatacache: MetadataCache

Gets the current metadata cache.

read_measurements() → MeasurementReader[source]

Sets up a new MeasurementReader to start reading measurements.

request_metadata()[source]

Sends a request to the data publisher indicating that the Subscriber would like new metadata. Any defined MetadataFilters will be included in request.

set_configurationchanged_receiver(callback: Callable[[], None] | None)[source]

Defines the callback that handles notifications that the data publisher configuration has changed. Assignment will take effect immediately, even while subscription is active.

set_connectionestablished_receiver(callback: Callable[[], None] | None)[source]

Defines the callback that handles notification that a connection has been established. Default implementation simply writes connection feedback to status message handler. Assignment will take effect immediately, even while subscription is active.

set_connectionterminated_receiver(callback: Callable[[], None] | None)[source]

Defines the callback that handles notification that a connection has been terminated. Default implementation simply writes connection terminated feedback to error message handler. Assignment will take effect immediately, even while subscription is active.

set_data_starttime_receiver(callback: Callable[[int64], None] | None)[source]

Defines the callback that handles notification of first received measurement. Assignment will take effect immediately, even while subscription is active.

set_errormessage_logger(callback: Callable[[str], None] | None)[source]

Defines the callback that handles error message logging. Assignment will take effect immediately, even while subscription is active.

set_historicalreadcomplete_receiver(callback: Callable[[], None] | None)[source]

Defines the callback that handles notification that temporal processing has completed, i.e., the end of a historical playback data stream has been reached. Assignment will take effect immediately, even while subscription is active.

set_metadatanotification_receiver(callback: Callable[[DataSet], None] | None)[source]

Defines the callback that handles reception of the metadata received notification response. Receiver parameter defines full XML response received from publisher. Parsed metadata available via Subscriber.metadatacache property. Assignment will take effect immediately, even while subscription is active.

set_newbufferblock_receiver(callback: Callable[[List[BufferBlock]], None] | None)[source]

Defines the callback that handles reception of new buffer blocks. Assignment will take effect immediately, even while subscription is active.

set_newmeasurements_receiver(callback: Callable[[List[Measurement]], None] | None)[source]

Defines the callback that handles reception of new measurements. Assignment will take effect immediately, even while subscription is active.

set_notification_receiver(callback: Callable[[str], None] | None)[source]

Defines the callback that handles reception of a notification. Assignment will take effect immediately, even while subscription is active.

set_statusmessage_logger(callback: Callable[[str], None] | None)[source]

Defines the callback that handles informational message logging. Assignment will take effect immediately, even while subscription is active.

set_subscriptionupdated_receiver(callback: Callable[[SignalIndexCache], None] | None)[source]

Defines the callback that handles notifications that a new SignalIndexCache has been received. Assignment will take effect immediately, even while subscription is active.

statusmessage(message: str)[source]

Executes the defined status message logger callback.

subscribe(filterexpression: str, settings: Settings = Ellipsis)[source]

Subscribe sets up a request indicating that the Subscriber would like to start receiving streaming data from a data publisher. If the subscriber is already connected, the updated filter expression and subscription settings will be requested immediately; otherwise, the settings will be used when the connection to the data publisher is established.

The filterExpression defines the desired measurements for a subscription. Examples include:

  • Directly specified signal IDs (UUID values in string format):

    38A47B0-F10B-4143-9A0A-0DBC4FFEF1E8; E4BBFE6A-35BD-4E5B-92C9-11FF913E7877

  • Directly specified tag names:

    DOM_GPLAINS-BUS1:VH; TVA_SHELBY-BUS1:VH

  • Directly specified identifiers in “measurement key” format:

    PPA:15; STAT:20

  • A filter expression against a selection view:

    FILTER ActiveMeasurements WHERE Company=’GPA’ AND SignalType=’FREQ’

Settings parameter controls subscription related settings.

property subscribed: bool

Gets flag that determines if Subscriber is currently subscribed to a data stream.

property subscriberid: UUID

Gets the subscriber ID as assigned by the data publisher upon receipt of the SignalIndexCache.

property total_commandchannel_bytesreceived: uint64

Gets the total number of bytes received via the command channel since last connection.

property total_datachannel_bytesreceived: uint64

Gets the total number of bytes received via the data channel since last connection.

property total_measurementsreceived: uint64

Gets the total number of measurements received since last subscription.

unsubscribe()[source]

Sends a request to the data publisher indicating that the Subscriber would like to stop receiving streaming data.

sttp.ticks module

class sttp.ticks.Ticks[source]

Bases: object

Defines constants and functions for tick values, 64-bit integers used to designate time in STTP. A tick value represents the number of 100-nanosecond intervals that have elapsed since 12:00:00 midnight, January 1, 0001 UTC, Gregorian calendar. A single tick represents one hundred nanoseconds, or one ten-millionth of a second. There are 10,000 ticks in a millisecond and 10 million ticks in a second. Only bits 01 to 62 (0x3FFFFFFFFFFFFFFF) are used to represent the timestamp value. Bit 64 (0x8000000000000000) is used to denote leap second, i.e., second 60, where actual second value would remain at 59. Bit 63 (0x4000000000000000) is used to denote leap second direction, 0 for add, 1 for delete.

LEAPSECOND_DIRECTION = np.uint64(4611686018427387904)

Flag (63rd bit) that indicates if leap second is positive or negative; 0 for add, 1 for delete.

LEAPSECOND_FLAG = np.uint64(9223372036854775808)

Flag (64th bit) that marks a Ticks value as a leap second, i.e., second 60 (one beyond normal second 59).

PERDAY = np.uint64(864000000000)

Number of Ticks that occur in a day.

PERHOUR = np.uint64(36000000000)

Number of Ticks that occur in an hour.

PERMICROSECOND = np.uint64(10)

Number of Ticks that occur in a microsecond.

PERMILLISECOND = np.uint64(10000)

Number of Ticks that occur in a millisecond.

PERMINUTE = np.uint64(600000000)

Number of Ticks that occur in a minute.

PERSECOND = np.uint64(10000000)

Number of Ticks that occur in a second.

UNIXBASEOFFSET = np.uint64(621355968000000000)

Ticks representation of the Unix epoch timestamp starting at January 1, 1970.

VALUEMASK = np.uint64(4611686018427387903)

All bits (bits 1 to 62) that make up the value portion of a Ticks that represent time.

static from_datetime(dt: datetime) → uint64[source]

Converts a standard Python dattime value to a Ticks value.

static from_timedelta(td: timedelta) → uint64[source]

Converts a standard Python timedelta value to a Ticks value.

static is_leapsecond(ticks: uint64) → bool[source]

Determines if the deserialized Ticks value represents a leap second, i.e., second 60.

static is_negative_leapsecond(ticks: uint64) → bool[source]

Determines if the deserialized Ticks value represents a negative leap second, i.e., checks flag on second 58 to see if second 59 will be missing.

static now() → uint64[source]

Gets the current local time as a Ticks value.

static set_leapsecond(ticks: uint64) → uint64[source]

Flags a Ticks value to represent a leap second, i.e., second 60, before wire serialization.

static set_negative_leapsecond(ticks: uint64) → uint64[source]

Flags a Ticks value to represent a negative leap second, i.e., sets flag on second 58 to mark that second 59 will be missing, before wire serialization.

static timestampvalue(ticks: uint64) → uint64[source]

Gets the timestamp portion of the Ticks value, i.e., the 62-bit time value excluding any leap second flags.

static to_datetime(ticks: uint64) → datetime[source]

Converts a Ticks value to standard Python datetime value.

Note: Python datetime values have a maximum resolution of 1 microsecond, so any Ticks values, which have 100 nanosecond resolution, will be rounded to the nearest microsecond.

static to_shortstring(ticks: uint64) → str[source]

Shows just the timestamp portion of a Ticks value with milliseconds, e.g., 15:04:05.999.

static to_string(ticks: uint64, timespec: str = 'microseconds') → str[source]

Standard timestamp representation for a Ticks value, e.g., 2006-01-02 15:04:05.999999999.

static utcnow() → uint64[source]

Gets the current time in UTC as a Ticks value.

sttp.version module

class sttp.version.Version[source]

Bases: object

STTP_SOURCE = 'STTP Python Library'

Defines the STTP library API title used for data subscriber identification.

STTP_UPDATEDON = '2024-10-16'

Defines when the STTP library API was last updated used for data subscriber identification.

STTP_VERSION = '0.6.4'

Defines the STTP library API version used for data subscriber identification. Note: This is not the STTP protocol version, but the version of the STTP library API.

Module contents