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 = 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.publisher module

class sttp.publisher.Publisher[source]

Bases: object

Represents an STTP data publisher.

Notes

The Publisher class exists as a simplified implementation wrapping the DataPublisher class found in the transport namespace. This class maintains an internal instance of the DataPublisher class and is intended to simplify common uses of STTP data publication, similar to how Subscriber wraps DataSubscriber.

property clientconnected_receiver: Callable[[SubscriberConnection], None] | None

Gets or sets a function to handle client connected events.

Signature: def clientconnected_receiver(connection: SubscriberConnection)

property clientdisconnected_receiver: Callable[[SubscriberConnection], None] | None

Gets or sets a function to handle client disconnected events.

Signature: def clientdisconnected_receiver(connection: SubscriberConnection)

default_clientconnected_receiver(connection: SubscriberConnection)[source]: Default client connected handler.

default_clientdisconnected_receiver(connection: SubscriberConnection)[source]: Default client disconnected handler.

default_errormessage_logger(message: str)[source]: Default error message logger that writes to stderr.

default_statusmessage_logger(message: str)[source]: Default status message logger that writes to stdout.

define_metadata(metadata: DataSet)[source]

Defines the metadata for the publisher from a DataSet.

Parameters:: metadata (DataSet) – DataSet containing metadata tables (MeasurementDetail, DeviceDetail, etc.)

dispose()[source]: Cleanly shuts down a Publisher that is no longer being used, e.g., during a normal application exit.

property errormessage_logger: Callable[[str], None] | None

Gets or sets a function to handle error messages.

Signature: def errormessage_logger(message: str)

filter_metadata(filter_expression: str) → List[MeasurementRecord][source]

Filters metadata using a filter expression and returns matching measurement metadata.

Parameters:: filter_expression (str) – Filter expression to apply to metadata (e.g., “SignalAcronym <> ‘STAT’”)
Returns:: List of MeasurementRecord objects matching the filter
Return type:: List[MeasurementRecord]

property is_metadata_refresh_allowed: bool: Gets or sets flag that determines if metadata refresh is allowed by clients.

property is_nan_value_filter_allowed: bool: Gets or sets flag that determines if NaN value filtering is allowed.

property is_nan_value_filter_forced: bool: Gets or sets flag that determines if NaN value filtering is forced.

property maximum_allowed_connections: int: Gets or sets the maximum number of allowed client connections. Set to -1 for unlimited connections.

publish_measurements(measurements: List[Measurement])[source]

Publishes a list of measurements to subscribed clients.

Parameters:: measurements (List[Measurement]) – List of measurements to publish

start(port: int, ipv6: bool = False)[source]

Starts the publisher listening on the specified port.

Parameters:

port (int) – TCP port number to listen on
ipv6 (bool, optional) – Set to True to use IPv6, False for IPv4 (default)

property started: bool: Gets flag that determines if Publisher is currently started and listening for connections.

property statusmessage_logger: Callable[[str], None] | None

Gets or sets a function to handle status messages.

Signature: def statusmessage_logger(message: str)

stop()[source]: Stops the publisher and disconnects all clients.

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 = 10.0

DEFAULT_LEADTIME = 5.0

DEFAULT_PROCESSINGINTERVAL = -1

DEFAULT_PUBLISHINTERVAL = 1.0

DEFAULT_REQUEST_NANVALUEFILTER = False

DEFAULT_STARTTIME = ''

DEFAULT_STOPTIME = ''

DEFAULT_THROTTLED = False

DEFAULT_UDPINTERFACE = ''

DEFAULT_UDPPORT = 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.

property configurationchanged_receiver: Callable[[], None] | None

Gets or sets a function to handle configuration changed notifications.

Signature: def configurationchanged_receiver()

connect(address: str, config: Config | None = None) → 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.

property connectionestablished_receiver: Callable[[], None] | None

Gets or sets a function to handle connection established notifications.

Signature: def connectionestablished_receiver()

property connectionterminated_receiver: Callable[[], None] | None

Gets or sets a function to handle connection terminated notifications.

Signature: def connectionterminated_receiver()

property data_starttime_receiver: Callable[[int64], None] | None

Gets or sets a function to handle data start time notifications.

Signature: def data_starttime_receiver(starttime: np.int64)

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. Using user implementation with 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. Using user implementation with 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.

property errormessage_logger: Callable[[str], None] | None

Gets or sets a function to handle error messages.

Signature: def errormessage_logger(message: str)

property historicalreadcomplete_receiver: Callable[[], None] | None

Gets or sets a function to handle historical read complete notifications.

Signature: def historicalreadcomplete_receiver()

measurement_metadata(measurement: Measurement) → MeasurementRecord | None[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.

property metadatanotification_receiver: Callable[[DataSet], None] | None

Gets or sets a function to handle metadata received notifications.

Signature: def metadatanotification_receiver(metadata: DataSet)

property newbufferblock_receiver: Callable[[List[BufferBlock]], None] | None

Gets or sets a function to handle new buffer blocks.

Signature: def newbufferblock_receiver(bufferblocks: List[BufferBlock])

property newmeasurements_receiver: Callable[[List[Measurement]], None] | None

Gets or sets a function to handle new measurements.

Signature: def newmeasurements_receiver(measurements: List[Measurement])

property notification_receiver: Callable[[str], None] | None

Gets or sets a function to handle notifications.

Signature: def notification_receiver(notification: str)

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.

Deprecated since version Prefer: using configurationchanged_receiver property setter for consistency with Publisher API.

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.

Deprecated since version Prefer: using connectionestablished_receiver property setter for consistency with Publisher API.

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.

Deprecated since version Prefer: using connectionterminated_receiver property setter for consistency with Publisher API.

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.

Deprecated since version Prefer: using data_starttime_receiver property setter for consistency with Publisher API.

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.

Deprecated since version Prefer: using errormessage_logger property setter for consistency with Publisher API.

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.

Deprecated since version Prefer: using historicalreadcomplete_receiver property setter for consistency with Publisher API.

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.

Deprecated since version Prefer: using metadatanotification_receiver property setter for consistency with Publisher API.

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.

Deprecated since version Prefer: using newbufferblock_receiver property setter for consistency with Publisher API.

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.

Deprecated since version Prefer: using newmeasurements_receiver property setter for consistency with Publisher API.

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.

Deprecated since version Prefer: using notification_receiver property setter for consistency with Publisher API.

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.

Deprecated since version Prefer: using statusmessage_logger property setter for consistency with Publisher API.

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.

Deprecated since version Prefer: using subscriptionupdated_receiver property setter for consistency with Publisher API.

statusmessage(message: str)[source]: Executes the defined status message logger callback.

property statusmessage_logger: Callable[[str], None] | None

Gets or sets a function to handle status messages.

Signature: def statusmessage_logger(message: str)

subscribe(filterexpression: str, settings: Settings | None = None)[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 subscriptionupdated_receiver: Callable[[SignalIndexCache], None] | None

Gets or sets a function to handle subscription updated notifications.

Signature: def subscriptionupdated_receiver(signalindexcache: 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 = 4611686018427387904: Flag (63rd bit) that indicates if leap second is positive or negative; 0 for add, 1 for delete.

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

PERDAY = 864000000000: Number of Ticks that occur in a day.

PERHOUR = 36000000000: Number of Ticks that occur in an hour.

PERMICROSECOND = 10: Number of Ticks that occur in a microsecond.

PERMILLISECOND = 10000: Number of Ticks that occur in a millisecond.

PERMINUTE = 600000000: Number of Ticks that occur in a minute.

PERSECOND = 10000000: Number of Ticks that occur in a second.

UNIXBASEOFFSET = 621355968000000000: Ticks representation of the Unix epoch timestamp starting at January 1, 1970.

VALUEMASK = 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 = '2026-01-11': Defines when the STTP library API was last updated used for data subscriber identification.

STTP_VERSION = '0.7.2': 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

class sttp.Publisher[source]

Bases: object

Represents an STTP data publisher.

Notes

The Publisher class exists as a simplified implementation wrapping the DataPublisher class found in the transport namespace. This class maintains an internal instance of the DataPublisher class and is intended to simplify common uses of STTP data publication, similar to how Subscriber wraps DataSubscriber.

property clientconnected_receiver: Callable[[SubscriberConnection], None] | None

Gets or sets a function to handle client connected events.

Signature: def clientconnected_receiver(connection: SubscriberConnection)

property clientdisconnected_receiver: Callable[[SubscriberConnection], None] | None

Gets or sets a function to handle client disconnected events.

Signature: def clientdisconnected_receiver(connection: SubscriberConnection)

default_clientconnected_receiver(connection: SubscriberConnection)[source]: Default client connected handler.

default_clientdisconnected_receiver(connection: SubscriberConnection)[source]: Default client disconnected handler.

default_errormessage_logger(message: str)[source]: Default error message logger that writes to stderr.

default_statusmessage_logger(message: str)[source]: Default status message logger that writes to stdout.

define_metadata(metadata: DataSet)[source]

Defines the metadata for the publisher from a DataSet.

Parameters:: metadata (DataSet) – DataSet containing metadata tables (MeasurementDetail, DeviceDetail, etc.)

dispose()[source]: Cleanly shuts down a Publisher that is no longer being used, e.g., during a normal application exit.

property errormessage_logger: Callable[[str], None] | None

Gets or sets a function to handle error messages.

Signature: def errormessage_logger(message: str)

filter_metadata(filter_expression: str) → List[MeasurementRecord][source]

Filters metadata using a filter expression and returns matching measurement metadata.

Parameters:: filter_expression (str) – Filter expression to apply to metadata (e.g., “SignalAcronym <> ‘STAT’”)
Returns:: List of MeasurementRecord objects matching the filter
Return type:: List[MeasurementRecord]

property is_metadata_refresh_allowed: bool: Gets or sets flag that determines if metadata refresh is allowed by clients.

property is_nan_value_filter_allowed: bool: Gets or sets flag that determines if NaN value filtering is allowed.

property is_nan_value_filter_forced: bool: Gets or sets flag that determines if NaN value filtering is forced.

property maximum_allowed_connections: int: Gets or sets the maximum number of allowed client connections. Set to -1 for unlimited connections.

publish_measurements(measurements: List[Measurement])[source]

Publishes a list of measurements to subscribed clients.

Parameters:: measurements (List[Measurement]) – List of measurements to publish

start(port: int, ipv6: bool = False)[source]

Starts the publisher listening on the specified port.

Parameters:

port (int) – TCP port number to listen on
ipv6 (bool, optional) – Set to True to use IPv6, False for IPv4 (default)

property started: bool: Gets flag that determines if Publisher is currently started and listening for connections.

property statusmessage_logger: Callable[[str], None] | None

Gets or sets a function to handle status messages.

Signature: def statusmessage_logger(message: str)

stop()[source]: Stops the publisher and disconnects all clients.

class sttp.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.

property configurationchanged_receiver: Callable[[], None] | None

Gets or sets a function to handle configuration changed notifications.

Signature: def configurationchanged_receiver()

connect(address: str, config: Config | None = None) → 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.

property connectionestablished_receiver: Callable[[], None] | None

Gets or sets a function to handle connection established notifications.

Signature: def connectionestablished_receiver()

property connectionterminated_receiver: Callable[[], None] | None

Gets or sets a function to handle connection terminated notifications.

Signature: def connectionterminated_receiver()

property data_starttime_receiver: Callable[[int64], None] | None

Gets or sets a function to handle data start time notifications.

Signature: def data_starttime_receiver(starttime: np.int64)

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. Using user implementation with 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. Using user implementation with 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.

property errormessage_logger: Callable[[str], None] | None

Gets or sets a function to handle error messages.

Signature: def errormessage_logger(message: str)

property historicalreadcomplete_receiver: Callable[[], None] | None

Gets or sets a function to handle historical read complete notifications.

Signature: def historicalreadcomplete_receiver()

measurement_metadata(measurement: Measurement) → MeasurementRecord | None[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.

property metadatanotification_receiver: Callable[[DataSet], None] | None

Gets or sets a function to handle metadata received notifications.

Signature: def metadatanotification_receiver(metadata: DataSet)

property newbufferblock_receiver: Callable[[List[BufferBlock]], None] | None

Gets or sets a function to handle new buffer blocks.

Signature: def newbufferblock_receiver(bufferblocks: List[BufferBlock])

property newmeasurements_receiver: Callable[[List[Measurement]], None] | None

Gets or sets a function to handle new measurements.

Signature: def newmeasurements_receiver(measurements: List[Measurement])

property notification_receiver: Callable[[str], None] | None

Gets or sets a function to handle notifications.

Signature: def notification_receiver(notification: str)

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.

Deprecated since version Prefer: using configurationchanged_receiver property setter for consistency with Publisher API.

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.

Deprecated since version Prefer: using connectionestablished_receiver property setter for consistency with Publisher API.

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.

Deprecated since version Prefer: using connectionterminated_receiver property setter for consistency with Publisher API.

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.

Deprecated since version Prefer: using data_starttime_receiver property setter for consistency with Publisher API.

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.

Deprecated since version Prefer: using errormessage_logger property setter for consistency with Publisher API.

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.

Deprecated since version Prefer: using historicalreadcomplete_receiver property setter for consistency with Publisher API.

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.

Deprecated since version Prefer: using metadatanotification_receiver property setter for consistency with Publisher API.

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.

Deprecated since version Prefer: using newbufferblock_receiver property setter for consistency with Publisher API.

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.

Deprecated since version Prefer: using newmeasurements_receiver property setter for consistency with Publisher API.

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.

Deprecated since version Prefer: using notification_receiver property setter for consistency with Publisher API.

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.

Deprecated since version Prefer: using statusmessage_logger property setter for consistency with Publisher API.

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.

Deprecated since version Prefer: using subscriptionupdated_receiver property setter for consistency with Publisher API.

statusmessage(message: str)[source]: Executes the defined status message logger callback.

property statusmessage_logger: Callable[[str], None] | None

Gets or sets a function to handle status messages.

Signature: def statusmessage_logger(message: str)

subscribe(filterexpression: str, settings: Settings | None = None)[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 subscriptionupdated_receiver: Callable[[SignalIndexCache], None] | None

Gets or sets a function to handle subscription updated notifications.

Signature: def subscriptionupdated_receiver(signalindexcache: 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.