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 ¶
-
str
Return the current state as a string.
- Returns :
-
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.
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 ¶
-
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.
- Returns :
-
UUID4
- Type :
-
Event.id
- ts_event ¶
-
int
The UNIX timestamp (nanoseconds) when the event occurred.
- Returns :
-
int
- Type :
-
Event.ts_event
- ts_init ¶
-
int
The UNIX timestamp (nanoseconds) when the object was initialized.
- Returns :
-
int
- Type :
-
Event.ts_init
- 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 :
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
- value ¶
-
str
- Type :
-
UUID4.value