Skip to main content
Version: nightly

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.

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)

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.

WARNING​

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

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

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], UUID4 request_id, uint64_t ts_init)

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.

WARNING​

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

callback​

The callback for the response.

  • Returns: Callable

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.

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)

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.

WARNING​

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

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], UUID4 request_id, uint64_t ts_init)

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.

WARNING​

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

callback​

The callback for the response.

  • Returns: Callable

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

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

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

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

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

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.

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
© 2025 Nautech Systems Pty Ltd. All rights reserved.