# 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 message base types are contained here.

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

## Collections ¶

bisect_left ( list a , double x , int lo=0 , hi=None ) int

Return the index where to insert item x in list a, assuming a is sorted. The return value i is such that all e in a[:i] have e <= x, and all e in a[i:] have e > x. So if x already appears in the list, a.insert(i, x) will insert just after the rightmost x already there. Optional args lo (default 0) and hi (default len(a)) bound the slice of a to be searched.

Returns

int

Raises

ValueError – If lo is negative (< 0).

bisect_right ( list a , double x , int lo=0 , hi=None ) int

Return the index where to insert item x in list a, assuming a is sorted. The return value i is such that all e in a[:i] have e <= x, and all e in a[i:] have e > x. So if x already appears in the list, a.insert(i, x) will insert just after the rightmost x already there. Optional args lo (default 0) and hi (default len(a)) bound the slice of a to be searched.

Returns

int

Raises

ValueError – If lo is negative (< 0).

## 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.

Returns

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.

Returns

datetime

dt_to_unix_nanos ( dt : pd.Timestamp )

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

Parameters

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

Returns

uint64_t or  None 

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 input datetime to format.

Returns

str – The formatted string.

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

bool – True if timezone aware UTC, else False.

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

bool – True if timezone aware, else False.

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

bool – True if object timezone naive, else False.

maybe_dt_to_unix_nanos ( dt : pd.Timestamp )

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

If dt is  None  , then will return None.

Parameters

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

Returns

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 time (nanoseconds), or  None  .

If nanos is  None  , then will return None.

Parameters

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

Returns

pd.Timestamp or  None 

micros_to_nanos ( double micros ) uint64_t

Return round nanoseconds (ns) converted from the given microseconds (μs).

Parameters

micros ( double ) – The microseconds to convert.

Returns

uint64_t

millis_to_nanos ( double millis ) uint64_t

Return round nanoseconds (ns) converted from the given milliseconds (ms).

Parameters

millis ( double ) – The milliseconds to convert.

Returns

uint64_t

nanos_to_micros ( uint64_t nanos ) uint64_t

Return round microseconds (μs) converted from the given nanoseconds (ns).

Parameters

nanos ( uint64_t ) – The nanoseconds to convert.

Returns

uint64_t

nanos_to_millis ( uint64_t nanos ) uint64_t

Return round milliseconds (ms) converted from the given nanoseconds (ns).

Parameters

nanos ( uint64_t ) – The nanoseconds to convert.

Returns

uint64_t

nanos_to_secs ( uint64_t nanos ) double

Return seconds converted from the given nanoseconds (ns).

Parameters

nanos ( uint64_t ) – The nanoseconds to convert.

Returns

double

secs_to_millis ( double secs ) uint64_t

Return round milliseconds (ms) converted from the given seconds.

Parameters

secs ( double ) – The seconds to convert.

Returns

uint64_t

secs_to_nanos ( double secs ) uint64_t

Return round nanoseconds (ns) converted from the given seconds.

Parameters

secs ( double ) – The seconds to convert.

Returns

uint64_t

unix_nanos_to_dt ( uint64_t nanos )

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

Parameters

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

Returns

pd.Timestamp

## 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

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

Bases:  object 

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

Return the current state as a string.

Returns

str

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.

with_traceback ( )

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

## Message ¶

class Command ( UUID4 command_id , uint64_t ts_init )

The abstract base class for all commands.

Parameters
• command_id ( UUID4 ) – The command ID.

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

Warning

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

category

The message category.

Returns

MessageCategory

id

The message ID.

Returns

UUID4

ts_init

The UNIX timestamp (nanoseconds) when the object was initialized.

Returns

uint64_t

class Document ( UUID4 document_id , uint64_t ts_init )

The abstract base class for all documents.

Parameters
• document_id ( UUID4 ) – The document ID.

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

Warning

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

category

The message category.

Returns

MessageCategory

id

The message ID.

Returns

UUID4

ts_init

The UNIX timestamp (nanoseconds) when the object was initialized.

Returns

uint64_t

class Event ( UUID4 event_id , uint64_t ts_event , uint64_t ts_init )

The abstract base class for all events.

Parameters
• event_id ( UUID4 ) – The event ID.

• ts_event ( uint64_t ) – The UNIX timestamp (nanoseconds) when the event occurred.

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

Warning

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

category

The message category.

Returns

MessageCategory

id

The message ID.

Returns

UUID4

ts_event

The UNIX timestamp (nanoseconds) when the event occurred.

Returns

uint64_t

ts_init

The UNIX timestamp (nanoseconds) when the object was initialized.

Returns

uint64_t

class Message ( MessageCategory category , UUID4 message_id , uint64_t ts_init )

Bases:  object 

The abstract base class for all messages.

Parameters
• category ( MessageCategory ) – The message category.

• message_id ( UUID4 ) – The message ID.

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

Warning

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

category

The message category.

Returns

MessageCategory

id

The message ID.

Returns

UUID4

ts_init

The UNIX timestamp (nanoseconds) when the object was initialized.

Returns

uint64_t

class Request ( callback: Callable[[Any], None], UUID4 request_id, uint64_t ts_init )

The abstract base class for all requests.

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

• request_id ( UUID4 ) – The request ID.

• ts_init ( uint64_t ) – The 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

category

The message category.

Returns

MessageCategory

id

The message ID.

Returns

UUID4

ts_init

The UNIX timestamp (nanoseconds) when the object was initialized.

Returns

uint64_t

class Response ( UUID4 correlation_id , UUID4 response_id , uint64_t ts_init )

The abstract base class for all responses.

Parameters
• correlation_id ( UUID4 ) – The correlation ID.

• response_id ( UUID4 ) – The response ID.

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

Warning

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

category

The message category.

Returns

MessageCategory

correlation_id

The response correlation ID.

Returns

UUID4

id

The message ID.

Returns

UUID4

ts_init

The 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.

Returns

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.

Returns

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.

Returns

double

fast_mean ( ndarray values ) double

Return the average value for numpy.ndarray values.

Parameters

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

Returns

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).

Returns

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.

Returns

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.

Returns

double

Notes

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

## UUID ¶

class UUID4 ( unicode value=None )

Bases:  object 

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.

Raises

ValueError – If value is not  None  and not a valid UUID.

References