Notes for Developers

Note

Contributions are welcome. If you want to add new functionality please

read through CONTRIBUTIONS.md in the root directory of the repository, and
familiarize yourself with the custom data types defined in FinQuant, and how type validation is achieved. You find relevant information below.

Data Types

Various custom data types are defined in finquant.data_types and used in FinQuant as type hints.

Description

finquant.data_types Module

This module defines type aliases and utility functions for working with arrays, data frames, and various numeric types in Python, utilizing the ‘numpy’, ‘numpy.typing’, and ‘pandas’ libraries.

Generic List Element Type

ELEMENT_TYPE: A type alias representing a generic element type

Array/List-Like Types

ARRAY_OR_LIST: A type alias representing either a NumPy ndarray or a Python List.
ARRAY_OR_DATAFRAME: A type alias representing either a NumPy ndarray or a pandas DataFrame.
ARRAY_OR_SERIES: A type alias representing either a NumPy ndarray or a pandas Series.
SERIES_OR_DATAFRAME: A type alias representing either a pandas Series or a pandas DataFrame.

Numeric Types

FLOAT: A type alias representing either a NumPy floating-point number or a Python float.
INT: A type alias representing either a NumPy integer or a Python int.
NUMERIC: A type alias representing either an INT or a FLOAT.

String/Datetime Types

STRING_OR_DATETIME: A type alias representing either a Python string or a datetime.datetime object.

Dependencies

This module requires the following external libraries:

numpy (imported as np)
pandas (imported as pd)

Usage Example

from finquant.data_types import ARRAY_OR_DATAFRAME, NUMERIC
# Use the defined type aliases
def process_data(data: ARRAY_OR_DATAFRAME) -> FLOAT:
    # Process the data and return a floating point number
    return 5.0

Code Definitions

Array/List-Like Types

finquant.data_types.ARRAY_OR_LIST: alias of Union[ndarray[ELEMENT_TYPE, Any], List[ELEMENT_TYPE]]

finquant.data_types.ARRAY_OR_DATAFRAME: alias of Union[ndarray[ELEMENT_TYPE, Any], DataFrame]

finquant.data_types.ARRAY_OR_SERIES: alias of Union[ndarray[ELEMENT_TYPE, Any], Series]

finquant.data_types.SERIES_OR_DATAFRAME: alias of Union[Series, DataFrame]

List of Dict keys

finquant.data_types.LIST_DICT_KEYS: alias of Union[ndarray[ELEMENT_TYPE, Any], List[ELEMENT_TYPE], KeysView[ELEMENT_TYPE]]

Numeric Types

finquant.data_types.FLOAT: alias of Union[floating, float]

finquant.data_types.INT: alias of Union[integer, int]

finquant.data_types.NUMERIC: alias of Union[integer, int, floating, float]

Type validation

This module provides a function type_validation that allow to effortlessly implement type validation.

Description

finquant.type_utilities Module

This module defines a type validation utility for working with various data types in Python, utilizing the ‘numpy’ and ‘pandas’ libraries.

Dependencies:

This module requires the following external libraries:

‘numpy’ (imported as ‘np’)
‘pandas’ (imported as ‘pd’)

Example usage:

Example:

type_validation(
    data=pd.DataFrame([1., 2.]),
    names=["name1", "name2"],
    start_date="2023-08-01",
    freq=10,
)

Code Definitions

finquant.type_utilities.type_validation(**kwargs)

Perform generic type validations on input variables.

This function performs various type validations on a set of input variables. It helps to ensure that the input values conform to the expected types and conditions, raising a TypeError with a descriptive error message if any type validation fails and a ValueError if a numpy.array or pd.Series/DataFrame is empty.

Parameters:: kwargs (Any) – Arbitrary keyword arguments representing the input variables to be checked.
Return type:: None

Raises:

TypeError:: If any of the type validations fail, a TypeError is raised with a descriptive error message indicating the expected type and conditions for each variable.
ValueError:: If any of the value validations fail, a ValueError is raised with a descriptive error message indicating the expected conditions for each variable.

Example usage:

type_validation(
    data=pd.DataFrame([1., 2.]),
    names=["name1", "name2"],
    start_date="2023-08-01",
    freq=10,
)