smax package

Submodules

smax.cli module

smax.cli.main()

smax.smax_client module

class smax.smax_client.SmaxClient(*args, **kwargs)

Bases: ABC

abstract smax_connect_to(*args, **kwargs)

abstract smax_create_coordinate_system(n_axis)

abstract smax_disconnect()

abstract smax_get_coordinate_system(table)

abstract smax_get_description(table)

abstract smax_get_units(table)

abstract smax_pull(table, key)

abstract smax_pull_meta(table, meta)

abstract smax_push_meta(meta, table, value)

abstract smax_set_coordinate_system(table, coordinate_system)

abstract smax_set_description(table, description)

abstract smax_set_units(table, unit)

abstract smax_share(table, key, value)

abstract smax_subscribe(pattern)

abstract smax_unsubscribe(pattern)

abstract smax_wait_on_any_subscribed()

abstract smax_wait_on_subscribed(pattern)

exception smax.smax_client.SmaxConnectionError

Bases: RuntimeError

exception smax.smax_client.SmaxKeyError

Bases: RuntimeError

exception smax.smax_client.SmaxUnderflowWarning

Bases: RuntimeWarning

smax.smax_client.join(*args)

Join SMA-X tables and keys. We use this method to avoid the TypeErrors from string.join()

params:

*args : SMA-X key elements to join

smax.smax_client.normalize_pair(*args)

Return a SMA-X table, key pair with exactly one level in the key

params:

*args : SMA-X key elements to join and split

smax.smax_client.print_smax(smax_value, verbose=False, indent=0)

Print a SMA-X value

smax.smax_client.print_tree(d, verbose=False, indent=0)

Walk through a tree of SMA-X values, printing the leaf nodes

smax.smax_data_types module

class smax.smax_data_types.SmaxArray(*args, **kwargs)

Bases: UserArray, SmaxVarBase

Class for holding SMA-X array objects, with their metadata

asdict()

property data

Python buffer object pointing to the start of the array’s data.

type: str | None = None

class smax.smax_data_types.SmaxBool(*args, **kwargs)

Bases: UserBool, SmaxVarBase

Class for holding SMA-X boolean objects, with their metadata.

This class is not an exact subclass for bool - e.g.:

In [1]: SmaxBool(True) is True Out[1]: False

asdict()

property data

type: str = 'boolean'

class smax.smax_data_types.SmaxData(data, type, dim, date, origin, seq, smaxname)

Bases: tuple

data

Alias for field number 0

date

Alias for field number 3

dim

Alias for field number 2

origin

Alias for field number 4

seq

Alias for field number 5

smaxname

Alias for field number 6

type

Alias for field number 1

class smax.smax_data_types.SmaxFloat(data: dataclasses.InitVar[float] = <property object>, *, timestamp: ~datetime.datetime | None = None, origin: str | None = None, seq: int = 1, smaxname: str | None = None, dim: int | tuple = 1, description: str | None = None, unit: str | None = None, coords: ~typing.Any | None = None, type: str = 'float')

Bases: float, SmaxVarBase

Class for holding SMA-X float objects, with their metadata

asdict()

type: str = 'float'

class smax.smax_data_types.SmaxFloat32(*args, **kwargs)

Bases: UserFloat32, SmaxVarBase

Class for holding SMA-X float objects, with their metadata

asdict()

property data

Pointer to start of data.

type: str = 'float32'

class smax.smax_data_types.SmaxFloat64(*args, **kwargs)

Bases: UserFloat64, SmaxVarBase

Class for holding SMA-X float objects, with their metadata

asdict()

property data

Pointer to start of data.

type: str = 'float64'

class smax.smax_data_types.SmaxInt(*args, **kwargs)

Bases: UserInt, SmaxVarBase

Class for holding SMA-X integer objects, with their metadata

asdict()

type: str = 'integer'

class smax.smax_data_types.SmaxInt16(*args, **kwargs)

Bases: UserInt16, SmaxVarBase

Class for holding SMA-X integer objects, with their metadata

asdict()

type: str = 'int16'

class smax.smax_data_types.SmaxInt32(*args, **kwargs)

Bases: UserInt32, SmaxVarBase

Class for holding SMA-X integer objects, with their metadata

asdict()

type: str = 'int32'

class smax.smax_data_types.SmaxInt64(*args, **kwargs)

Bases: UserInt64, SmaxVarBase

Class for holding SMA-X integer objects, with their metadata

asdict()

type: str = 'int64'

class smax.smax_data_types.SmaxInt8(*args, **kwargs)

Bases: UserInt8, SmaxVarBase

Class for holding SMA-X integer objects, with their metadata

asdict()

type: str = 'int8'

class smax.smax_data_types.SmaxStr(*args, **kwargs)

Bases: UserStr, SmaxVarBase

Class for holding SMA-X string objects, with their metadata

asdict()

type: str = 'string'

class smax.smax_data_types.SmaxStrArray(*args, **kwargs)

Bases: UserList, SmaxVarBase

Class for holding SMA-X string arrays, with their metadata

asdict()

type: str = 'string'

class smax.smax_data_types.SmaxStruct(*args, **kwargs)

Bases: UserDict, SmaxVarBase

Class for holding SMA-X string objects, with their metadata

asdict()

type: str = 'struct'

class smax.smax_data_types.SmaxVarBase(*, timestamp: datetime | None = None, origin: str | None = None, seq: int = 1, smaxname: str | None = None, dim: int | tuple = 1, description: str | None = None, unit: str | None = None, coords: Any | None = None)

Bases: object

Class defining the metadata for SMA-X data types.

We define all the metadata except data and type here.

coords: Any | None = None

property data

description: str | None = None

dim: int | tuple = 1

property metadata

origin: str | None = None

seq: int = 1

smaxname: str | None = None

timestamp: datetime | None = None

unit: str | None = None

class smax.smax_data_types.UserArray(*args, **kwargs)

Bases: ndarray

class smax.smax_data_types.UserBool(*args, **kwargs)

Bases: int

class smax.smax_data_types.UserDict(*args, **kwargs)

Bases: dict

class smax.smax_data_types.UserFloat32(*args, **kwargs)

Bases: float32

class smax.smax_data_types.UserFloat64(*args, **kwargs)

Bases: float64

class smax.smax_data_types.UserInt(*args, **kwargs)

Bases: int

class smax.smax_data_types.UserInt16(*args, **kwargs)

Bases: int16

class smax.smax_data_types.UserInt32(*args, **kwargs)

Bases: int32

class smax.smax_data_types.UserInt64(*args, **kwargs)

Bases: int64

class smax.smax_data_types.UserInt8(*args, **kwargs)

Bases: int8

class smax.smax_data_types.UserList(*args, **kwargs)

Bases: list

class smax.smax_data_types.UserStr(*args, **kwargs)

Bases: str

smax.smax_redis_client module

class smax.smax_redis_client.SmaxRedisClient(redis_ip='localhost', redis_port=6379, redis_db=0, program_name=None, hostname=None, debug=False, logger=None)

Bases: SmaxClient

smax_connect_to(redis_ip, redis_port, redis_db)

Uses the redis-py library to establish a connection to redis, then obtains and stores the LUA scripts in the object (ex self._getSHA). This function is called automatically by the SmaxClient parent class, so there shouldn’t be a need to call this explicitly.

Parameters:

• redis_ip (str) – IP address of redis-server.

• redis_port (int) – Port of redis-server.

• redis_db (int) – Database index to connect to.

Returns:

A Redis client object configured from the given args.

Return type:

Redis

smax_create_coordinate_system(n_axis)

smax_disconnect()

Python manages a connection pool automatically, if somehow that fails release the connection, this disconnect function will do it.

smax_dsm_get_table(target, key, host=None)

Get the SMA-X name that maps to a DSM target, key, and (optionally) host.

Parameters:

• target (str) – DSM target or caller

• key (str) – DSM key

• host (str, optional) – DSM host (caller). If not set, defaults to target.

Returns:

SMA-X table where the key can be found.

Return type:

str

smax_get_coordinate_system(table)

smax_get_description(table)

smax_get_units(table)

smax_lazy_end(table, key)

smax_lazy_pull(table, key, value)

smax_list_higher_than(table, value)

List all SMA-X fields in table with values higher than the value.

Parameters:

• table (str) – table, struct or meta name

• value (int or float) – cutoff value.

Returns:

list of pairs of SMA-X fields and values higher than value

Return type:

list[(str, smax.SmaxData)]

smax_list_newer_than(dt)

List all SMA-X keys newer than the datetime object.

Parameters:

dt (datetime.datetime) – cutoff time.

Returns:

list of pairs of SMA-X keys and values newer than dt

Return type:

list[(str, smax.SmaxData)]

smax_list_older_than(dt)

List all SMA-X keys older than the datetime object.

Parameters:

dt (datetime.datetime) – cutoff time.

Returns:

list of pairs of SMA-X keys and values older than dt

Return type:

list[(str, smax.SmaxData)]

smax_list_zeroes(key)

List all fields in key equal to zero.

Parameters:

key (str) – Redis key to test.

Returns:

list of all fields equal to zero.

Return type:

list(str)

smax_pull(table, key, pull_meta=False)

Get data which was stored with the smax macro HSetWithMeta along with the associated metadata. The return value will an SmaxData object containing the data, typeName, dataDimension(s), dataDate, source of the data, and a sequence number. If you pulled a struct, you will get a nested dictionary back, with each leaf being an SmaxData object. :param table: SMAX table name :type table: str :param key: SMAX key name :type key: str :param pull_meta: Flag whether to pull optional metadata :type pull_meta: bool

Returns:

Populated Smax<type> dataclass object.

Return type:

Smax<type>

smax_pull_meta(meta, table)

Pulls specified metadata field from a given table. :param table: Name of the table to pull metadata from. :type table: str :param meta: Metadata field name to pull. :type meta: str

Returns:

Result of redis-py hget function.

smax_purge(table, key=None)

Purges a table or key from Redis. Use with ultimate caution.

Parameters:

• table (str) – SMA-X table to purge. Can include wild cards to purge by pattern matching.

• key (str, optional) – Specific SMA-X key in table to purge. Defaults to None.

Returns:

number of SMA-X keys purged from Redis

Return type:

int

smax_purge_volatile()

Purges all volatile tables and keys from Redis. Use with ultimate caution.

smax_push_meta(meta, table, value)

Sets additional metadata for a given table. :param meta: Key for the metadata field. :type meta: str :param table: Name of the table to set metadata for. :type table: str :param value: Metadata value to store in redis, note this

needs to be a string int.

Returns:

Result of redis-py hset function.

smax_set_coordinate_system(table, coordinate_system)

smax_set_description(table, description)

Creates a <description> metadata field for specified table. :param table: Full SMAX table name (with key included). :type table: str :param description: String for the description of this smax field. :type description: str

smax_set_units(table, unit)

smax_share(table, key, value, push_meta=False, smax_type=None)

Send data to redis using the smax macro HSetWithMeta to include metadata. The metadata is typeName, dataDimension(s), dataDate, source of the data, and a sequence number. The first two are determined from the data and the source from this computer’s name plus the program name if given when this class is instantiated. Date and sequence number are added by the redis macro. :param table: SMAX table name :type table: str :param key: SMAX key name :type key: str :param value: data to store, takes supported types, including (nested) dicts. :param push_meta: Push optional metadata if present in object

(does not work for SmaxStructs and is not atomic).

Parameters:

type_name (str) – Force casting to type_name before sharing.

Returns:

return value from redis-py’s evalsha() function.

smax_subscribe(pattern, callback=None, pubsub_sleep=0.01)

Subscribe to a redis field or group of fields. You can type the full name of the field you’d like to subscribe too, or use a wildcard “*” character as a suffix to specify a pattern. Use a callback for asynchronous processing of notifications, or use one of the smax_wait_on functions.

Internal to the HSET* and HMSET*, notifications for pub/sub are generated with the prefix smax:. This needs to be added/removed within smax_subscribe, etc.

Parameters:

• pattern (str) – Either full name of smax field, or use a wildcard ‘*’ at the end of the pattern to be notified for anything underneath.

• callback (func) – Function that takes a single argument (Default=None). The message in your callback will be an SmaData object, or a nested dictionary for a struct.

• pubsub_sleep (float) – Sleep time within each loop of the pubsub event handling thread

smax_unsubscribe(pattern=None)

Unsubscribe from all subscribed channels, or pass a pattern argument to unsubscribe from specific channels. :param pattern: Either full name of smax field, or use a wildcard ‘*’

at the end of the pattern to be notified for anything underneath.

smax_wait_on_any_subscribed(timeout=None, notification_only=False)

If you use smax_subscribe without a callback, you can use this function to block until a message is received from any channel you are subscribed to. :param timeout: Value in seconds to wait before raising timeout exception. :type timeout: float :param notification_only: If True, only returns the notification from redis. :type notification_only: bool

Returns:

Either a (list) notification, or the actual pulled data.

smax_wait_on_subscribed(pattern, timeout=None, notification_only=False)

If you use smax_subscribe without a callback, you can use this function to specify with channel to listen to, and block until a message is received. :param pattern: SMAX table/key pattern to listen on. :type pattern: str :param timeout: Value in seconds to wait before raising timeout exception. :type timeout: int :param notification_only: If True, only returns the notification from redis. :type notification_only: bool

Returns:

Either a (list) notification, or the actual pulled data.

smax.smax_redis_client_old module

class smax.smax_redis_client_old.SmaxRedisClient(redis_ip='localhost', redis_port=6379, redis_db=0, program_name=None, hostname=None)

Bases: SmaxClient

smax_connect_to(redis_ip, redis_port, redis_db)

Uses the redis-py library to establish a connection to redis, then obtains and stores the LUA scripts in the object (ex self._getSHA). This function is called automatically by the SmaxClient parent class, so there shouldn’t be a need to call this explicitly.

Parameters:

• redis_ip (str) – IP address of redis-server.

• redis_port (int) – Port of redis-server.

• redis_db (int) – Database index to connect to.

Returns:

A Redis client object configured from the given args.

Return type:

Redis

smax_create_coordinate_system(n_axis)

smax_disconnect()

Python manages a connection pool automatically, if somehow that fails release the connection, this disconnect function will do it.

smax_dsm_get_table(target, key, host=None)

Get the SMA-X name that maps to a DSM target, key, and (optionally) host.

Parameters:

• target (str) – DSM target or caller

• key (str) – DSM key

• host (str, optional) – DSM host (caller). If not set, defaults to target.

Returns:

SMA-X table where the key can be found.

Return type:

str

smax_get_coordinate_system(table)

smax_get_description(table)

smax_get_units(table)

smax_lazy_end(table, key)

smax_lazy_pull(table, key, value)

smax_list_higher_than(table, value)

List all SMA-X fields in table with values higher than the value.

Parameters:

• table (str) – table, struct or meta name

• value (int or float) – cutoff value.

Returns:

list of pairs of SMA-X fields and values higher than value

Return type:

list[(str, smax.SmaxData)]

smax_list_newer_than(dt)

List all SMA-X keys newer than the datetime object.

Parameters:

dt (datetime.datetime) – cutoff time.

Returns:

list of pairs of SMA-X keys and values newer than dt

Return type:

list[(str, smax.SmaxData)]

smax_list_older_than(dt)

List all SMA-X keys older than the datetime object.

Parameters:

dt (datetime.datetime) – cutoff time.

Returns:

list of pairs of SMA-X keys and values older than dt

Return type:

list[(str, smax.SmaxData)]

smax_list_zeroes(key)

List all fields in key equal to zero.

Parameters:

key (str) – Redis key to test.

Returns:

list of all fields equal to zero.

Return type:

list(str)

smax_pull(table, key)

Get data which was stored with the smax macro HSetWithMeta along with the associated metadata. The return value will an SmaxData object containing the data, typeName, dataDimension(s), dataDate, source of the data, and a sequence number. If you pulled a struct, you will get a nested dictionary back, with each leaf being an SmaxData object. :param table: SMAX table name :type table: str :param key: SMAX key name :type key: str

Returns:

Populated SmaxData NamedTuple object. dict: If a struct is pulled, this returns a nested dictionary.

Return type:

SmaxData

smax_pull_meta(table, meta)

Pulls specified metadata field from a given table. :param table: Name of the table to pull metadata from. :type table: str :param meta: Metadata field name to pull. :type meta: str

Returns:

Result of redis-py hget function.

smax_purge(table, key=None)

Purges a table or key from Redis. Use with ultimate caution.

Parameters:

• table (str) – SMA-X table to purge. Can include wild cards to purge by pattern matching.

• key (str, optional) – Specific SMA-X key in table to purge. Defaults to None.

Returns:

number of SMA-X keys purged from Redis

Return type:

int

smax_purge_volatile()

Purges all volatile tables and keys from Redis. Use with ultimate caution.

smax_push_meta(meta, table, value)

Sets additional metadata for a given table. :param meta: Key for the metadata field. :type meta: str :param table: Name of the table to set metadata for. :type table: str :param value: Metadata value to store in redis, note this

needs to be a string int.

Returns:

Result of redis-py hset function.

smax_set_coordinate_system(table, coordinate_system)

smax_set_description(table, description)

Creates a <description> metadata field for specified table. :param table: Full SMAX table name (with key included). :type table: str :param description: String for the description of this smax field. :type description: str

smax_set_units(table, unit)

smax_share(table, key, value)

Send data to redis using the smax macro HSetWithMeta to include metadata. The metadata is typeName, dataDimension(s), dataDate, source of the data, and a sequence number. The first two are determined from the data and the source from this computer’s name plus the program name if given when this class is instantiated. Date and sequence number are added by the redis macro. :param table: SMAX table name :type table: str :param key: SMAX key name :type key: str :param value: data to store, takes supported types, including (nested) dicts.

Returns:

return value from redis-py’s evalsha() function.

smax_subscribe(pattern, callback=None)

Subscribe to a redis field or group of fields. You can type the full name of the field you’d like to subscribe too, or use a wildcard “*” character as a suffix to specify a pattern. Use a callback for asynchronous processing of notifications, or use one of the smax_wait_on functions. :param pattern: Either full name of smax field, or use a wildcard ‘*’

at the end of the pattern to be notified for anything underneath.

Parameters:

callback (func) – Function that takes a single argument (Default=None). The message in your callback will be an SmaData object, or a nested dictionary for a struct.

smax_unsubscribe(pattern=None)

Unsubscribe from all subscribed channels, or pass a pattern argument to unsubscribe from specific channels. :param pattern: Either full name of smax field, or use a wildcard ‘*’

at the end of the pattern to be notified for anything underneath.

smax_wait_on_any_subscribed(timeout=None, notification_only=False)

If you use smax_subscribe without a callback, you can use this function to block until a message is received from any channel you are subscribed to. :param timeout: Value in seconds to wait before raising timeout exception. :type timeout: float :param notification_only: If True, only returns the notification from redis. :type notification_only: bool

Returns:

Either a (list) notification, or the actual pulled data.

smax_wait_on_subscribed(pattern, timeout=None, notification_only=False)

If you use smax_subscribe without a callback, you can use this function to specify with channel to listen to, and block until a message is received. :param pattern: SMAX table/key pattern to listen on. :type pattern: str :param timeout: Value in seconds to wait before raising timeout exception. :type timeout: int :param notification_only: If True, only returns the notification from redis. :type notification_only: bool

Returns:

Either a (list) notification, or the actual pulled data.

Module contents