Core

The core subpackage groups core constants, functions and low-level components used throughout the framework.

The main focus here is on efficiency and re-usability as this forms the base layer of the entire framework. Message passing is a core design philosophy and the base massage types are contained here.

A generic FiniteStateMachine operates with C-level enums, ensuring correct state transitions for both domain entities and more complex components.

class UUID4

Bases: object

UUID4()

Represents a Universally Unique Identifier (UUID) version 4 based on a 128-bit label as specified in RFC 4122.

References

https://en.wikipedia.org/wiki/Universally_unique_identifier

static from_str(str value) → UUID4

Create a new UUID4 from the given string value.

Parameters:

value (str) – The UUID value.

Return type:

UUID4

Raises:

ValueError – If value is not a valid UUID version 4 RFC 4122 string.

value

str

Type:

UUID4.value

class Command

Bases: object

Command(UUID4 command_id, uint64_t ts_init, UUID4 correlation_id=None)

The base class for all command messages.

Parameters:

  • command_id (UUID4) – The command ID.

  • ts_init (uint64_t) – UNIX timestamp (nanoseconds) when the object was initialized.

  • correlation_id (UUID4, optional) – The correlation ID. If provided, this command is correlated to another command or request.

Warning

This class should not be used directly, but through a concrete subclass.

correlation_id

The command correlation ID.

Returns:

UUID4 or None

id

The command message ID.

Returns:

UUID4

ts_init

UNIX timestamp (nanoseconds) when the object was initialized.

Returns:

uint64_t

class Data

Bases: object

The abstract base class for all data.

Warning

This class should not be used directly, but through a concrete subclass.

classmethod fully_qualified_name(cls) → str

Return the fully qualified name for the Data class.

Return type:

str

References

https://www.python.org/dev/peps/pep-3155/

classmethod is_signal(cls, str name='') → bool

Determine if the current class is a signal type, optionally checking for a specific signal name.

Parameters:

name (str, optional) – The specific signal name to check. If name not provided or if an empty string is passed, the method checks whether the class name indicates a general signal type. If name is provided, the method checks if the class name corresponds to that specific signal.

Returns:

True if the class name matches the signal type or the specific signal name, otherwise False.

Return type:

bool

ts_event

int

UNIX timestamp (nanoseconds) when the data event occurred.

Return type:

int

Type:

Data.ts_event

ts_init

int

UNIX timestamp (nanoseconds) when the instance was created.

Return type:

int

Type:

Data.ts_init

class Document

Bases: object

Document(UUID4 document_id, uint64_t ts_init)

The base class for all document messages.

Parameters:

  • document_id (UUID4) – The command ID.

  • ts_init (uint64_t) – UNIX timestamp (nanoseconds) when the object was initialized.

Warning

This class should not be used directly, but through a concrete subclass.

id

The document message ID.

Returns:

UUID4

ts_init

UNIX timestamp (nanoseconds) when the object was initialized.

Returns:

uint64_t

class Event

Bases: object

The abstract base class for all event messages.

Warning

This class should not be used directly, but through a concrete subclass.

id

UUID4

The event message identifier.

Return type:

UUID4

Type:

Event.id

ts_event

int

UNIX timestamp (nanoseconds) when the event occurred.

Return type:

int

Type:

Event.ts_event

ts_init

int

UNIX timestamp (nanoseconds) when the object was initialized.

Return type:

int

Type:

Event.ts_init

class Request

Bases: object

Request(callback: Callable[[Any], None] | None, UUID4 request_id, uint64_t ts_init, UUID4 correlation_id=None)

The base class for all request messages.

Parameters:

  • callback (Callable[[Any], None]) – The delegate to call with the response.

  • request_id (UUID4) – The request ID.

  • ts_init (uint64_t) – UNIX timestamp (nanoseconds) when the object was initialized.

  • correlation_id (UUID4, optional) – The correlation ID. If provided, this request is correlated to another request.

Warning

This class should not be used directly, but through a concrete subclass.

callback

The callback for the response.

Returns:

Callable

correlation_id

The request correlation ID.

Returns:

UUID4 or None

id

The request message ID.

Returns:

UUID4

ts_init

UNIX timestamp (nanoseconds) when the object was initialized.

Returns:

uint64_t

class Response

Bases: object

Response(UUID4 correlation_id, UUID4 response_id, uint64_t ts_init)

The base class for all response messages.

Parameters:

  • correlation_id (UUID4) – The correlation ID.

  • response_id (UUID4) – The response ID.

  • ts_init (uint64_t) – UNIX timestamp (nanoseconds) when the object was initialized.

Warning

This class should not be used directly, but through a concrete subclass.

correlation_id

The response correlation ID.

Returns:

UUID4

id

The response message ID.

Returns:

UUID4

ts_init

UNIX timestamp (nanoseconds) when the object was initialized.

Returns:

uint64_t

Datetime

This module provides efficient functions for performing standard datetime related operations.

Functions include awareness/tz checks and conversions, as well as ISO 8601 (RFC 3339) conversion.

as_utc_index(data: pd.DataFrame)

Ensure the given data has a DateTimeIndex which is tz-aware UTC.

Parameters:

data (pd.Series or pd.DataFrame.) – The object to ensure is UTC.

Return type:

pd.Series, pd.DataFrame or None

as_utc_timestamp(datetime dt) → datetime

Ensure the given timestamp is tz-aware UTC.

Parameters:

dt (datetime) – The timestamp to check.

Return type:

datetime

dt_to_unix_nanos(dt: pd.Timestamp)

Return the UNIX timestamp (nanoseconds) from the given datetime (UTC).

Parameters:

dt (pd.Timestamp | str | int) – The datetime to convert.

Return type:

uint64_t

Warning

This function expects a pandas Timestamp as standard Python datetime objects are only accurate to 1 microsecond (μs).

ensure_pydatetime_utc(timestamp: pd.Timestamp) → dt.datetime | None

Convert an optional pandas.Timestamp to a timezone-aware datetime in UTC.

The underlying Python datetime type only supports microsecond precision. When the provided timestamp contains non-zero nanoseconds these cannot be represented and are therefore truncated to microseconds before the conversion takes place. This avoids the “Discarding nonzero nanoseconds in conversion” UserWarning raised by pandas when calling Timestamp.to_pydatetime().

Parameters:

timestamp (pd.Timestamp, optional) – The timestamp to convert. If None the function immediately returns None.

Returns:

The converted timestamp with tz-info set to UTC or None if the input was None.

Return type:

datetime.datetime | None

format_iso8601(datetime dt, bool nanos_precision=True) → str

Format the given datetime as an ISO 8601 (RFC 3339) specification string.

Parameters:

  • dt (pd.Timestamp) – The datetime to format.

  • nanos_precision (bool, default True) – If True, use nanosecond precision. If False, use millisecond precision.

Return type:

str

format_optional_iso8601(datetime dt, bool nanos_precision=True) → str

Format the given optional datetime as an ISO 8601 (RFC 3339) specification string.

If value is None then will return the string “None”.

Parameters:

  • dt (pd.Timestamp, optional) – The datetime to format.

  • nanos_precision (bool, default True) – If True, use nanosecond precision. If False, use millisecond precision.

Return type:

str

is_datetime_utc(datetime dt) → bool

Return a value indicating whether the given timestamp is timezone aware UTC.

Parameters:

dt (datetime) – The datetime to check.

Returns:

True if timezone aware UTC, else False.

Return type:

bool

is_tz_aware(time_object) → bool

Return a value indicating whether the given object is timezone aware.

Parameters:

time_object (datetime, pd.Timestamp, pd.Series, pd.DataFrame) – The time object to check.

Returns:

True if timezone aware, else False.

Return type:

bool

is_tz_naive(time_object) → bool

Return a value indicating whether the given object is timezone naive.

Parameters:

time_object (datetime, pd.Timestamp, pd.DataFrame) – The time object to check.

Returns:

True if object timezone naive, else False.

Return type:

bool

max_date(date1: pd.Timestamp | str | int | None = None, date2: str | int | None = None) → pd.Timestamp | None

Return the maximum date as a datetime (UTC).

Parameters:

  • date1 (pd.Timestamp | str | int | None, optional) – The first date to compare. Can be a string, integer (timestamp), or None. Default is None.

  • date2 (pd.Timestamp | str | int | None, optional) – The second date to compare. Can be a string, integer (timestamp), or None. Default is None.

Returns:

The maximum date, or None if both input dates are None.

Return type:

pd.Timestamp | None

maybe_dt_to_unix_nanos(dt: pd.Timestamp)

Return the UNIX timestamp (nanoseconds) from the given datetime, or None.

If dt is None, then will return None.

Parameters:

dt (pd.Timestamp, optional) – The datetime to convert.

Return type:

int64 or None

Warning

If the input is not None then this function expects a pandas Timestamp as standard Python datetime objects are only accurate to 1 microsecond (μs).

maybe_unix_nanos_to_dt(nanos)

Return the datetime (UTC) from the given UNIX timestamp (nanoseconds), or None.

If nanos is None, then will return None.

Parameters:

nanos (int, optional) – The UNIX timestamp (nanoseconds) to convert.

Return type:

pd.Timestamp or None

min_date(date1: pd.Timestamp | str | int | None = None, date2: str | int | None = None) → pd.Timestamp | None

Return the minimum date as a datetime (UTC).

Parameters:

  • date1 (pd.Timestamp | str | int | None, optional) – The first date to compare. Can be a string, integer (timestamp), or None. Default is None.

  • date2 (pd.Timestamp | str | int | None, optional) – The second date to compare. Can be a string, integer (timestamp), or None. Default is None.

Returns:

The minimum date, or None if both input dates are None.

Return type:

pd.Timestamp | None

time_object_to_dt(time_object) → datetime

Return the datetime (UTC) from the given UNIX timestamp as integer (nanoseconds), string or pd.Timestamp.

Parameters:

time_object (pd.Timestamp | str | int | None) – The time object to convert.

Returns:

Returns None if the input is None.

Return type:

pd.Timestamp or None

unix_nanos_to_dt(uint64_t nanos)

Return the datetime (UTC) from the given UNIX timestamp (nanoseconds).

Parameters:

nanos (uint64_t) – The UNIX timestamp (nanoseconds) to convert.

Return type:

pd.Timestamp

unix_nanos_to_iso8601(uint64_t unix_nanos, bool nanos_precision=True) → str

Convert the given unix_nanos to an ISO 8601 (RFC 3339) format string.

Parameters:

  • unix_nanos (int) – The UNIX timestamp (nanoseconds) to be converted.

  • nanos_precision (bool, default True) – If True, use nanosecond precision. If False, use millisecond precision.

Return type:

str

Finite-State Machine (FSM)

Defines a generic Finite-State Machine (FSM).

The FSM operates with a state-transition table of tuples and C-level enums. The intended use case is to ensure correct state transitions, as well as holding a deterministic state value.

References

https://en.wikipedia.org/wiki/Finite-state_machine

class FiniteStateMachine

Bases: object

FiniteStateMachine(dict state_transition_table, int initial_state, trigger_parser: Callable[[int], str] = str, state_parser: Callable[[int], str] = str)

Provides a generic finite state machine.

Parameters:

  • state_transition_table (dict of tuples and states) – The state-transition table for the FSM consisting of a tuple of starting state and trigger as keys, and resulting states as values.

  • initial_state (int / C Enum) – The initial state for the FSM.

  • trigger_parser (Callable[[int], str], optional) – The trigger parser needed to convert C Enum ints into strings. If None then will just print the integer.

  • state_parser (Callable[[int], str], optional) – The state parser needed to convert C Enum ints into strings. If None then will just print the integer.

Raises:

  • ValueError – If state_transition_table is empty.

  • ValueError – If state_transition_table key not tuple.

  • ValueError – If trigger_parser not of type Callable or None.

  • ValueError – If state_parser not of type Callable or None.

state

The current state of the FSM.

Returns:

int / C Enum

state_string

str

Return the current state as a string.

Return type:

str

Type:

FiniteStateMachine.state_string

trigger(self, int trigger) → void

Process the FSM with the given trigger. The trigger must be valid for the FSMs current state.

Parameters:

trigger (int / C Enum) – The trigger to combine with the current state providing the key for the transition table lookup.

Raises:

InvalidStateTrigger – If the state and trigger combination is not found in the transition table.

exception InvalidStateTrigger

Bases: Exception

Represents an invalid trigger for the current state.

add_note(object, /)

Exception.add_note(note) – add a note to the exception

args
with_traceback(object, /)

Exception.with_traceback(tb) – set self.__traceback__ to tb and return self.

Message

class Command

Bases: object

Command(UUID4 command_id, uint64_t ts_init, UUID4 correlation_id=None)

The base class for all command messages.

Parameters:

  • command_id (UUID4) – The command ID.

  • ts_init (uint64_t) – UNIX timestamp (nanoseconds) when the object was initialized.

  • correlation_id (UUID4, optional) – The correlation ID. If provided, this command is correlated to another command or request.

Warning

This class should not be used directly, but through a concrete subclass.

correlation_id

The command correlation ID.

Returns:

UUID4 or None

id

The command message ID.

Returns:

UUID4

ts_init

UNIX timestamp (nanoseconds) when the object was initialized.

Returns:

uint64_t

class Document

Bases: object

Document(UUID4 document_id, uint64_t ts_init)

The base class for all document messages.

Parameters:

  • document_id (UUID4) – The command ID.

  • ts_init (uint64_t) – UNIX timestamp (nanoseconds) when the object was initialized.

Warning

This class should not be used directly, but through a concrete subclass.

id

The document message ID.

Returns:

UUID4

ts_init

UNIX timestamp (nanoseconds) when the object was initialized.

Returns:

uint64_t

class Event

Bases: object

The abstract base class for all event messages.

Warning

This class should not be used directly, but through a concrete subclass.

id

UUID4

The event message identifier.

Return type:

UUID4

Type:

Event.id

ts_event

int

UNIX timestamp (nanoseconds) when the event occurred.

Return type:

int

Type:

Event.ts_event

ts_init

int

UNIX timestamp (nanoseconds) when the object was initialized.

Return type:

int

Type:

Event.ts_init

class Request

Bases: object

Request(callback: Callable[[Any], None] | None, UUID4 request_id, uint64_t ts_init, UUID4 correlation_id=None)

The base class for all request messages.

Parameters:

  • callback (Callable[[Any], None]) – The delegate to call with the response.

  • request_id (UUID4) – The request ID.

  • ts_init (uint64_t) – UNIX timestamp (nanoseconds) when the object was initialized.

  • correlation_id (UUID4, optional) – The correlation ID. If provided, this request is correlated to another request.

Warning

This class should not be used directly, but through a concrete subclass.

callback

The callback for the response.

Returns:

Callable

correlation_id

The request correlation ID.

Returns:

UUID4 or None

id

The request message ID.

Returns:

UUID4

ts_init

UNIX timestamp (nanoseconds) when the object was initialized.

Returns:

uint64_t

class Response

Bases: object

Response(UUID4 correlation_id, UUID4 response_id, uint64_t ts_init)

The base class for all response messages.

Parameters:

  • correlation_id (UUID4) – The correlation ID.

  • response_id (UUID4) – The response ID.

  • ts_init (uint64_t) – UNIX timestamp (nanoseconds) when the object was initialized.

Warning

This class should not be used directly, but through a concrete subclass.

correlation_id

The response correlation ID.

Returns:

UUID4

id

The response message ID.

Returns:

UUID4

ts_init

UNIX timestamp (nanoseconds) when the object was initialized.

Returns:

uint64_t

Stats

basis_points_as_percentage(double basis_points) → double

Return the given basis points expressed as a percentage where 100% = 1.0.

Parameters:

basis_points (double) – The basis points to convert to percentage.

Return type:

double

Notes

1 basis point = 0.01%.

fast_mad(ndarray values) → double

Return the mean absolute deviation from the given values.

Parameters:

values (numpy.ndarray) – The array for the calculation.

Return type:

double

fast_mad_with_mean(ndarray values, double mean) → double

Return the mean absolute deviation from the given values and mean.

Parameters:

  • values (numpy.ndarray) – The array for the calculation.

  • mean (double) – The pre-calculated mean of the given values.

Return type:

double

fast_mean(ndarray values) → double

Return the average value for numpy.ndarray values.

Parameters:

values (numpy.ndarray) – The array to evaluate.

Return type:

double

Notes

> 10x faster than np.mean if the array length < ~200.

fast_mean_iterated(ndarray values, double next_value, double current_value, int expected_length, bool drop_left=True) → double

Return the calculated average from the given inputs.

Parameters:

  • values (list[double]) – The values for the calculation.

  • next_value (double) – The next input value for the average.

  • current_value (double) – The current value for the average.

  • expected_length (int) – The expected length of the inputs.

  • drop_left (bool) – If the value to be dropped should be from the left side of the inputs (index 0).

Return type:

double

Notes

> 10x faster than np.mean.

fast_std(ndarray values) → double

Return the standard deviation from the given values.

Parameters:

values (numpy.ndarray) – The array for the calculation.

Return type:

double

Notes

> 10x faster than np.std.

fast_std_with_mean(ndarray values, double mean) → double

Return the standard deviation from the given values and mean.

Parameters:

  • values (numpy.ndarray) – The array for the calculation.

  • mean (double) – The pre-calculated mean of the given values.

Return type:

double

Notes

> 25x faster than np.std if the array length < ~200.

UUID

class UUID4

Bases: object

UUID4()

Represents a Universally Unique Identifier (UUID) version 4 based on a 128-bit label as specified in RFC 4122.

References

https://en.wikipedia.org/wiki/Universally_unique_identifier

static from_str(str value) → UUID4

Create a new UUID4 from the given string value.

Parameters:

value (str) – The UUID value.

Return type:

UUID4

Raises:

ValueError – If value is not a valid UUID version 4 RFC 4122 string.

value

str

Type:

UUID4.value