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

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

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.

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

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

Message ¶

class Command ( UUID4 command_id , uint64_t ts_init ) ¶

Bases: object

The base class for all command messages.

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.

id ¶

The command 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 ) ¶

Bases: object

The base class for all document messages.

Parameters :

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

id ¶

The document 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 ) ¶

Bases: object

The base class for all event messages.

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.

id ¶

The event 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 Request ( callback: Callable[[Any], None], UUID4 request_id, uint64_t ts_init ) ¶

Bases: object

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

id ¶

The request 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 ) ¶

Bases: object

The base class for all response messages.

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.

correlation_id ¶

The response correlation ID.

Returns :: UUID4

id ¶

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

Warning

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

References

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