Skip to main content
Version: latest

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.

Datetime​

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

Functions include awareness/tz checks and conversions, as well as ISO 8601 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) – 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).

format_iso8601(datetime dt) → unicode​

Format the given datetime to a millisecond accurate ISO 8601 specification string.

  • Parameters: dt (datetime) – The datetime to format.
  • 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_str(date1: str | int | None = None, date2: str | int | None = None) → str | None​

Returns the maximum date as an ISO 8601 formatted string.

  • Parameters:
    • date1 (str | int | None , optional) – The first date to compare. Can be a string, integer (timestamp), or None. Default is None.
    • date2 (str | int | None , optional) – The second date to compare. Can be a string, integer (timestamp), or None. Default is None.
  • Returns: The maximum date as an ISO 8601 formatted string, or None if both input dates are None.
  • Return type: str | 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_str(date1: str | int | None = None, date2: str | int | None = None) → str | None​

Returns the minimum date as an ISO 8601 formatted string.

  • Parameters:
    • date1 (str | int | None , optional) – The first date to compare. Can be a string, integer (timestamp), or None. Default is None.
    • date2 (str | int | None , optional) – The second date to compare. Can be a string, integer (timestamp), or None. Default is None.
  • Returns: The minimum date as an ISO 8601 formatted string, or None if both input dates are None.
  • Return type: str | 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_str(uint64_t unix_nanos) → unicode​

Convert the given unix_nanos to an ISO 8601 formatted string.

  • Parameters: unix_nanos (int) – The UNIX timestamp (nanoseconds) to be converted.
  • 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()​

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

args​

with_traceback()​

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(unicode value=None)

Represents a pseudo-random UUID (universally unique identifier) version 4 based on a 128-bit label as specified in RFC 4122.

  • Parameters: value (str , optional) – The UUID value. If None then a value will be generated.

WARNING​

  • Panics at runtime if value is not None and not a valid UUID.

value​

str

  • Type: UUID4.value
© 2024 Nautech Systems Pty Ltd. All rights reserved.