forex_data.data_management package

Submodules

forex_data.data_management.common module

Created on Sat Apr 30 09:23:19 2022

@author: fiora

class forex_data.data_management.common.DEFAULT_PATHS

Bases: object

BASE_PATH = '/home/runner/.database'

HIST_DATA_FOLDER = 'HistoricalData'

REALTIME_DATA_FOLDER = 'RealtimeData'

class forex_data.data_management.common.DATA_TYPE

Bases: object

CSV_FILETYPE = 'csv'

PARQUET_FILETYPE = 'parquet'

class forex_data.data_management.common.BASE_DATA_COLUMN_NAME

Bases: object

TIMESTAMP = 'timestamp'

OPEN = 'open'

HIGH = 'high'

LOW = 'low'

CLOSE = 'close'

ASK = 'ask'

BID = 'bid'

VOL = 'vol'

P_VALUE = 'p'

TRANSACTIONS = 'transactions'

VWAP = 'vwap'

OTC = 'otc'

class forex_data.data_management.common.DATA_FILE_COLUMN_INDEX

Bases: object

TIMESTAMP = 0

class forex_data.data_management.common.ASSET_TYPE

Bases: object

STOCK = 'STOCK'

ETF = 'ETF'

FOREX = 'FOREX'

class forex_data.data_management.common.DTYPE_DICT

Bases: object

TICK_DTYPE = {'ask': 'float32', 'bid': 'float32', 'p': 'float32', 'vol': 'float32'}

TF_DTYPE = {'close': 'float32', 'high': 'float32', 'low': 'float32', 'open': 'float32'}

TIME_TICK_DTYPE = {'ask': 'float32', 'bid': 'float32', 'p': 'float32', 'timestamp': 'datetime64[ms]', 'vol': 'float32'}

TIME_TF_DTYPE = {'close': 'float32', 'high': 'float32', 'low': 'float32', 'open': 'float32', 'timestamp': 'datetime64[ms]'}

class forex_data.data_management.common.PYARROW_DTYPE_DICT

Bases: object

TICK_DTYPE = {'ask': DataType(float), 'bid': DataType(float), 'p': DataType(float), 'vol': DataType(float)}

TF_DTYPE = {'close': DataType(float), 'high': DataType(float), 'low': DataType(float), 'open': DataType(float)}

TIME_TICK_DTYPE = {'ask': DataType(float), 'bid': DataType(float), 'p': DataType(float), 'timestamp': TimestampType(timestamp[ms]), 'vol': DataType(float)}

TIME_TF_DTYPE = {'close': DataType(float), 'high': DataType(float), 'low': DataType(float), 'open': DataType(float), 'timestamp': TimestampType(timestamp[ms])}

class forex_data.data_management.common.POLARS_DTYPE_DICT

Bases: object

TICK_DTYPE = {'ask': Float32, 'bid': Float32, 'p': Float32, 'vol': Float32}

TF_DTYPE = {'close': Float32, 'high': Float32, 'low': Float32, 'open': Float32}

TIME_TICK_DTYPE = {'ask': Float32, 'bid': Float32, 'p': Float32, 'timestamp': Datetime(time_unit='ms', time_zone=None), 'vol': Float32}

TIME_TF_DTYPE = {'close': Float32, 'high': Float32, 'low': Float32, 'open': Float32, 'timestamp': Datetime(time_unit='ms', time_zone=None)}

class forex_data.data_management.common.DATA_COLUMN_NAMES

Bases: object

TICK_DATA_NO_PVALUE = ['timestamp', 'ask', 'bid', 'vol']

TICK_DATA = ['timestamp', 'ask', 'bid', 'vol', 'p']

TF_DATA = ['timestamp', 'open', 'high', 'low', 'close']

TICK_DATA_TIME_INDEX = ['ask', 'bid', 'vol', 'p']

TF_DATA_TIME_INDEX = ['open', 'high', 'low', 'close']

class forex_data.data_management.common.FILENAME_TEMPLATE

Bases: object

TICKER_INDEX = 0

YEAR_INDEX = 1

YEAR_NUMERICAL_CHAR = 1

TF_INDEX = 2

FILETYPE_INDEX = 3

class forex_data.data_management.common.DATA_KEY

Bases: object

MARKET = 0

TICKER_INDEX = 1

TF_INDEX = 2

YEAR_INDEX = 3

class forex_data.data_management.common.SQL_COMPARISON_OPERATORS

Bases: object

GREATER_THAN = '>'

LESS_THAN = '<'

GREATER_THAN_OR_EQUAL = '>='

LESS_THAN_OR_EQUAL = '<='

EQUAL = '=='

NOT_EQUAL = '!='

class forex_data.data_management.common.SQL_CONDITION_AGGREGATION_MODES

Bases: object

AND = 'AND'

OR = 'OR'

forex_data.data_management.common.SUPPORTED_HISTORICAL_DATA_PROVIDERS = ['Histdata', 'Dukascopy']

REALTIME DATA PROVIDERS

forex_data.data_management.common.validator_file_path(file_ext=None)

forex_data.data_management.common.validator_dir_path(create_if_missing=False)

forex_data.data_management.common.validate_timedelta_str(instance, attribute, value)

forex_data.data_management.common.get_attrs_names(instance_object, **kwargs)

forex_data.data_management.common.check_timeframe_str(tf, engine='pandas')

forex_data.data_management.common.any_date_to_datetime64(any_date, date_format='ISO8601', unit=None, to_pydatetime=False)

forex_data.data_management.common.empty_dataframe(engine)

forex_data.data_management.common.is_empty_dataframe(dataframe)

forex_data.data_management.common.shape_dataframe(dataframe)

forex_data.data_management.common.get_dataframe_column(dataframe, column)

forex_data.data_management.common.get_dataframe_row(dataframe, row)

forex_data.data_management.common.get_dataframe_element(dataframe, column, row)

forex_data.data_management.common.astype(dataframe, dtype_dict)

forex_data.data_management.common.read_csv(engine, file, **kwargs)

forex_data.data_management.common.sort_dataframe(dataframe, column)

forex_data.data_management.common.concat_data(data_list=_CountingAttr(counter=27, _default=NOTHING, repr=True, eq=True, order=True, hash=None, init=True, on_setattr=None, alias=None, metadata={}))

forex_data.data_management.common.list_remove_duplicates(list_in)

forex_data.data_management.common.reframe_data(dataframe, tf)

Parameters

dataTYPE

DESCRIPTION.

tfTYPE

DESCRIPTION.

Raises

ValueError

DESCRIPTION.

Returns

Dataframe

DESCRIPTION.

forex_data.data_management.common.write_csv(dataframe, file, **kwargs)

forex_data.data_management.common.write_parquet(dataframe, filepath)

forex_data.data_management.common.read_parquet(engine, filepath)

forex_data.data_management.common.to_pandas_dataframe(dataframe)

forex_data.data_management.common.get_pair_symbols(ticker)

forex_data.data_management.common.to_source_symbol(ticker, source)

forex_data.data_management.common.get_date_interval(start=None, end=None, interval_start_mode=None, interval_end_mode='now', interval_timespan=None, freq=None, normalize=False, bdays=False)

forex_data.data_management.common.random_date_between(start_date, end_date)

Get a random datetime between two datetime objects.

Parameters:

• start_date (datetime) – The start date.

• end_date (datetime) – The end date.

Returns:

A random datetime between start_date and end_date.

Return type:

datetime

forex_data.data_management.common.get_histdata_tickers(verify=True)

Get all available tickers from HistData.com.

Return type:

List[str]

Parameters

verifybool, optional

Whether to verify SSL certificates. Default is True.

Returns

List[str]

List of all available tickers (e.g., [‘EURUSD’, ‘GBPUSD’, …]).

exception forex_data.data_management.common.TickerNotFoundError

Bases: Exception

exception forex_data.data_management.common.TickerDataNotFoundError

Bases: Exception

exception forex_data.data_management.common.TickerDataBadTypeException

Bases: Exception

exception forex_data.data_management.common.TickerDataInvalidException

Bases: Exception

forex_data.data_management.common.business_days_data(dataframe)

Remove non-business days data from the input dataframe. Filter out weekends data: saturday and sunday. Use holidays to get list of country holidays. Consider dataframe always have a column named ‘timestamp’ of type datetime.

Return type:

DataFrame | LazyFrame

forex_data.data_management.common.update_ticker_years_dict(ticker_years_dict, ticker, timeframe, years_to_add)

Update a ticker years dictionary with new years for a specific ticker and timeframe.

This function modifies the dictionary in place and returns whether any changes were made.

Return type:

bool

Parameters

ticker_years_dictDict[str, Dict[str, List[int]]]

Dictionary containing ticker years data, structured as: {ticker: {timeframe: [year1, year2, …]}}

tickerstr

The ticker symbol to update

timeframestr

The timeframe for the ticker data

years_to_addList[int]

List of years to add to the years list

Returns

bool

True if any changes were made, False otherwise

forex_data.data_management.common.get_class_attr_keys(var)

forex_data.data_management.common.get_class_attr_values(var)

forex_data.data_management.common.get_class_attr_dict(var)

forex_data.data_management.common.get_forex_holidays(years)

Generates standard Global Forex closure dates (Dec 25 & Jan 1) for a range of years.

forex_data.data_management.common.adjust_end_date_to_business_days(start, timeframe, periods, holidays, end=None)

Calculate if timeframe can fit exactly periods times in the timespan between start and end dates. If not, recursively calculates a new end by advancing forwards with business days. Start date remains always unmodified.

Return type:

Tuple[int, datetime]

forex_data.data_management.common.adjust_start_date_to_business_days(end, timeframe, periods, holidays, start=None)

Calculate if timeframe con fit exactly periods times in the timespan between start and end dates. If not, recursively calculates a new start by advancing backwards with business days. End date remains always unmodified.

Return type:

Tuple[int, datetime]

forex_data.data_management.common.estimate_start_date_to_business_days(end_date, timeframe, window_size, holidays=[])

Estimate start date needed to cover a window size of timeframe periods.

Return type:

datetime

forex_data.data_management.common.estimate_end_date_to_business_days(start_date, timeframe, window_size, holidays=[])

Estimate end date needed to cover a window size of timeframe periods.

Return type:

datetime

class forex_data.data_management.common.Timestamp(ts_input=<object object>, year=None, month=None, day=None, hour=None, minute=None, second=None, microsecond=None, tzinfo=None, *, nanosecond=None, tz=<object object>, unit=None, fold=None)

Bases: _Timestamp

Pandas replacement for python datetime.datetime object.

Timestamp is the pandas equivalent of python’s Datetime and is interchangeable with it in most cases. It’s the type used for the entries that make up a DatetimeIndex, and other timeseries oriented data structures in pandas.

Parameters

ts_inputdatetime-like, str, int, float

Value to be converted to Timestamp.

yearint

Value of year.

monthint

Value of month.

dayint

Value of day.

hourint, optional, default 0

Value of hour.

minuteint, optional, default 0

Value of minute.

secondint, optional, default 0

Value of second.

microsecondint, optional, default 0

Value of microsecond.

tzinfodatetime.tzinfo, optional, default None

Timezone info.

nanosecondint, optional, default 0

Value of nanosecond.

tzstr, zoneinfo.ZoneInfo, pytz.timezone, dateutil.tz.tzfile or None

Time zone for time which Timestamp will have.

unitstr

Unit used for conversion if ts_input is of type int or float. The valid values are ‘W’, ‘D’, ‘h’, ‘m’, ‘s’, ‘ms’, ‘us’, and ‘ns’. For example, ‘s’ means seconds and ‘ms’ means milliseconds.

For float inputs, the result will be stored in nanoseconds, and the unit attribute will be set as 'ns'.

fold{0, 1}, default None, keyword-only

Due to daylight saving time, one wall clock time can occur twice when shifting from summer to winter time; fold describes whether the datetime-like corresponds to the first (0) or the second time (1) the wall clock hits the ambiguous time.

See Also

Timedelta : Represents a duration, the difference between two dates or times. datetime.datetime : Python datetime.datetime object.

Notes

There are essentially three calling conventions for the constructor. The primary form accepts four parameters. They can be passed by position or keyword.

The other two forms mimic the parameters from datetime.datetime. They can be passed by either position or keyword, but not both mixed together.

Examples

Using the primary calling convention:

This converts a datetime-like string

>>> pd.Timestamp('2017-01-01T12')
Timestamp('2017-01-01 12:00:00')

This converts a float representing a Unix epoch in units of seconds

>>> pd.Timestamp(1513393355.5, unit='s')
Timestamp('2017-12-16 03:02:35.500000')

This converts an int representing a Unix-epoch in units of weeks

>>> pd.Timestamp(1535, unit='W')
Timestamp('1999-06-03 00:00:00')

This converts an int representing a Unix-epoch in units of seconds and for a particular timezone

>>> pd.Timestamp(1513393355, unit='s', tz='US/Pacific')
Timestamp('2017-12-15 19:02:35-0800', tz='US/Pacific')

Using the other two forms that mimic the API for datetime.datetime:

>>> pd.Timestamp(2017, 1, 1, 12)
Timestamp('2017-01-01 12:00:00')

>>> pd.Timestamp(year=2017, month=1, day=1, hour=12)
Timestamp('2017-01-01 12:00:00')

astimezone(tz)

Convert timezone-aware Timestamp to another time zone.

This method is used to convert a timezone-aware Timestamp object to a different time zone. The original UTC time remains the same; only the time zone information is changed. If the Timestamp is timezone-naive, a TypeError is raised.

Return type:

Self

Parameters

tzstr, zoneinfo.ZoneInfo, pytz.timezone, dateutil.tz.tzfile or None

Time zone for time which Timestamp will be converted to. None will remove timezone holding UTC time.

Returns

converted : Timestamp

Raises

TypeError

If Timestamp is tz-naive.

See Also

Timestamp.tz_localize : Localize the Timestamp to a timezone. DatetimeIndex.tz_convert : Convert a DatetimeIndex to another time zone. DatetimeIndex.tz_localize : Localize a DatetimeIndex to a specific time zone. datetime.datetime.astimezone : Convert a datetime object to another time zone.

Examples

Create a timestamp object with UTC timezone:

>>> ts = pd.Timestamp('2020-03-14T15:32:52.192548651', tz='UTC')
>>> ts
Timestamp('2020-03-14 15:32:52.192548651+0000', tz='UTC')

Change to Tokyo timezone:

>>> ts.tz_convert(tz='Asia/Tokyo')
Timestamp('2020-03-15 00:32:52.192548651+0900', tz='Asia/Tokyo')

Can also use astimezone:

>>> ts.astimezone(tz='Asia/Tokyo')
Timestamp('2020-03-15 00:32:52.192548651+0900', tz='Asia/Tokyo')

Analogous for pd.NaT:

>>> pd.NaT.tz_convert(tz='Asia/Tokyo')
NaT

ceil(freq, ambiguous='raise', nonexistent='raise')

Return a new Timestamp ceiled to this resolution.

Return type:

Self

Parameters

freqstr

Frequency string indicating the ceiling resolution.

ambiguousbool or {‘raise’, ‘NaT’}, default ‘raise’

The behavior is as follows:

• bool contains flags to determine if time is dst or not (note that this flag is only applicable for ambiguous fall dst dates).

• ‘NaT’ will return NaT for an ambiguous time.

• ‘raise’ will raise a ValueError for an ambiguous time.

nonexistent{‘raise’, ‘shift_forward’, ‘shift_backward’, ‘NaT’, timedelta}, default ‘raise’

A nonexistent time does not exist in a particular timezone where clocks moved forward due to DST.

• ‘shift_forward’ will shift the nonexistent time forward to the closest existing time.

• ‘shift_backward’ will shift the nonexistent time backward to the closest existing time.

• ‘NaT’ will return NaT where there are nonexistent times.

• timedelta objects will shift nonexistent times by the timedelta.

• ‘raise’ will raise a ValueError if there are nonexistent times.

Raises

ValueError if the freq cannot be converted.

See Also

Timestamp.floor : Round down a Timestamp to the specified resolution. Timestamp.round : Round a Timestamp to the specified resolution. Series.dt.ceil : Ceil the datetime values in a Series.

Notes

If the Timestamp has a timezone, ceiling will take place relative to the local (“wall”) time and re-localized to the same timezone. When ceiling near daylight savings time, use nonexistent and ambiguous to control the re-localization behavior.

Examples

Create a timestamp object:

>>> ts = pd.Timestamp('2020-03-14T15:32:52.192548651')

A timestamp can be ceiled using multiple frequency units:

>>> ts.ceil(freq='h')  # hour
Timestamp('2020-03-14 16:00:00')

>>> ts.ceil(freq='min')  # minute
Timestamp('2020-03-14 15:33:00')

>>> ts.ceil(freq='s')  # seconds
Timestamp('2020-03-14 15:32:53')

>>> ts.ceil(freq='us')  # microseconds
Timestamp('2020-03-14 15:32:52.192549')

freq can also be a multiple of a single unit, like ‘5min’ (i.e. 5 minutes):

>>> ts.ceil(freq='5min')
Timestamp('2020-03-14 15:35:00')

or a combination of multiple units, like ‘1h30min’ (i.e. 1 hour and 30 minutes):

>>> ts.ceil(freq='1h30min')
Timestamp('2020-03-14 16:30:00')

Analogous for pd.NaT:

>>> pd.NaT.ceil()
NaT

When rounding near a daylight savings time transition, use ambiguous or nonexistent to control how the timestamp should be re-localized.

>>> ts_tz = pd.Timestamp("2021-10-31 01:30:00").tz_localize("Europe/Amsterdam")

>>> ts_tz.ceil("h", ambiguous=False)
Timestamp('2021-10-31 02:00:00+0100', tz='Europe/Amsterdam')

>>> ts_tz.ceil("h", ambiguous=True)
Timestamp('2021-10-31 02:00:00+0200', tz='Europe/Amsterdam')

classmethod combine(date, time)

Combine a date and time into a single Timestamp object.

This method takes a date object and a time object and combines them into a single Timestamp that has the same date and time fields.

Return type:

datetime

Parameters

datedatetime.date

The date part of the Timestamp.

timedatetime.time

The time part of the Timestamp.

Returns

Timestamp

A new Timestamp object representing the combined date and time.

See Also

Timestamp : Represents a single timestamp, similar to datetime. to_datetime : Converts various types of data to datetime.

Examples

>>> from datetime import date, time
>>> pd.Timestamp.combine(date(2020, 3, 14), time(15, 30, 15))
Timestamp('2020-03-14 15:30:15')

ctime()

Return a ctime() style string representing the Timestamp.

This method returns a string representing the date and time in the format returned by the standard library’s time.ctime() function, which is typically in the form ‘Day Mon DD HH:MM:SS YYYY’.

If the Timestamp is outside the range supported by Python’s standard library, a NotImplementedError is raised.

Return type:

str

Returns

str

A string representing the Timestamp in ctime format.

See Also

time.ctime : Return a string representing time in ctime format. Timestamp : Represents a single timestamp, similar to datetime. datetime.datetime.ctime : Return a ctime style string from a datetime object.

Examples

>>> ts = pd.Timestamp('2023-01-01 10:00:00.00')
>>> ts
Timestamp('2023-01-01 10:00:00')
>>> ts.ctime()
'Sun Jan  1 10:00:00 2023'

date()

Returns datetime.date with the same year, month, and day.

This method extracts the date component from the Timestamp and returns it as a datetime.date object, discarding the time information.

Return type:

date

Returns

datetime.date

The date part of the Timestamp.

See Also

Timestamp : Represents a single timestamp, similar to datetime. datetime.datetime.date : Extract the date component from a datetime object.

Examples

Extract the date from a Timestamp:

>>> ts = pd.Timestamp('2023-01-01 10:00:00.00')
>>> ts
Timestamp('2023-01-01 10:00:00')
>>> ts.date()
datetime.date(2023, 1, 1)

daysinmonth

Return the number of days in the month.

Returns

int

See Also

Timestamp.month_nameReturn the month name of the Timestamp with

specified locale.

Examples

>>> ts = pd.Timestamp(2020, 3, 14)
>>> ts.days_in_month
31

dst()

Return the daylight saving time (DST) adjustment.

This method returns the DST adjustment as a datetime.timedelta object if the Timestamp is timezone-aware and DST is applicable.

Return type:

timedelta | None

See Also

Timestamp.tz_localize : Localize the Timestamp to a timezone. Timestamp.tz_convert : Convert timezone-aware Timestamp to another time zone.

Examples

>>> ts = pd.Timestamp('2000-06-01 00:00:00', tz='Europe/Brussels')
>>> ts
Timestamp('2000-06-01 00:00:00+0200', tz='Europe/Brussels')
>>> ts.dst()
datetime.timedelta(seconds=3600)

floor(freq, ambiguous='raise', nonexistent='raise')

Return a new Timestamp floored to this resolution.

Return type:

Self

Parameters

freqstr

Frequency string indicating the flooring resolution.

ambiguousbool or {‘raise’, ‘NaT’}, default ‘raise’

The behavior is as follows:

• bool contains flags to determine if time is dst or not (note that this flag is only applicable for ambiguous fall dst dates).

• ‘NaT’ will return NaT for an ambiguous time.

• ‘raise’ will raise a ValueError for an ambiguous time.

nonexistent{‘raise’, ‘shift_forward’, ‘shift_backward’, ‘NaT’, timedelta}, default ‘raise’

A nonexistent time does not exist in a particular timezone where clocks moved forward due to DST.

• ‘shift_forward’ will shift the nonexistent time forward to the closest existing time.

• ‘shift_backward’ will shift the nonexistent time backward to the closest existing time.

• ‘NaT’ will return NaT where there are nonexistent times.

• timedelta objects will shift nonexistent times by the timedelta.

• ‘raise’ will raise a ValueError if there are nonexistent times.

Raises

ValueError if the freq cannot be converted.

See Also

Timestamp.ceil : Round up a Timestamp to the specified resolution. Timestamp.round : Round a Timestamp to the specified resolution. Series.dt.floor : Round down the datetime values in a Series.

Notes

If the Timestamp has a timezone, flooring will take place relative to the local (“wall”) time and re-localized to the same timezone. When flooring near daylight savings time, use nonexistent and ambiguous to control the re-localization behavior.

Examples

Create a timestamp object:

>>> ts = pd.Timestamp('2020-03-14T15:32:52.192548651')

A timestamp can be floored using multiple frequency units:

>>> ts.floor(freq='h')  # hour
Timestamp('2020-03-14 15:00:00')

>>> ts.floor(freq='min')  # minute
Timestamp('2020-03-14 15:32:00')

>>> ts.floor(freq='s')  # seconds
Timestamp('2020-03-14 15:32:52')

>>> ts.floor(freq='ns')  # nanoseconds
Timestamp('2020-03-14 15:32:52.192548651')

freq can also be a multiple of a single unit, like ‘5min’ (i.e. 5 minutes):

>>> ts.floor(freq='5min')
Timestamp('2020-03-14 15:30:00')

or a combination of multiple units, like ‘1h30min’ (i.e. 1 hour and 30 minutes):

>>> ts.floor(freq='1h30min')
Timestamp('2020-03-14 15:00:00')

Analogous for pd.NaT:

>>> pd.NaT.floor()
NaT

When rounding near a daylight savings time transition, use ambiguous or nonexistent to control how the timestamp should be re-localized.

>>> ts_tz = pd.Timestamp("2021-10-31 03:30:00").tz_localize("Europe/Amsterdam")

>>> ts_tz.floor("2h", ambiguous=False)
Timestamp('2021-10-31 02:00:00+0100', tz='Europe/Amsterdam')

>>> ts_tz.floor("2h", ambiguous=True)
Timestamp('2021-10-31 02:00:00+0200', tz='Europe/Amsterdam')

classmethod fromordinal(ordinal, tz=None)

Construct a timestamp from a proleptic Gregorian ordinal.

This method creates a Timestamp object corresponding to the given proleptic Gregorian ordinal, which is a count of days from January 1, 0001 (using the proleptic Gregorian calendar). The time part of the Timestamp is set to midnight (00:00:00) by default.

Return type:

Self

Parameters

ordinalint

Date corresponding to a proleptic Gregorian ordinal.

tzstr, zoneinfo.ZoneInfo, pytz.timezone, dateutil.tz.tzfile or None

Time zone for the Timestamp.

Returns

Timestamp

A Timestamp object representing the specified ordinal date.

See Also

Timestamp : Represents a single timestamp, similar to datetime. to_datetime : Converts various types of data to datetime.

Notes

By definition there cannot be any tz info on the ordinal itself.

Examples

Convert an ordinal to a Timestamp:

>>> pd.Timestamp.fromordinal(737425)
Timestamp('2020-01-01 00:00:00')

Create a Timestamp from an ordinal with timezone information:

>>> pd.Timestamp.fromordinal(737425, tz='UTC')
Timestamp('2020-01-01 00:00:00+0000', tz='UTC')

classmethod fromtimestamp(ts, tz=None)

Create a Timestamp object from a POSIX timestamp.

This method converts a POSIX timestamp (the number of seconds since January 1, 1970, 00:00:00 UTC) into a Timestamp object. The resulting Timestamp can be localized to a specific time zone if provided.

Return type:

Self

Parameters

tsfloat

The POSIX timestamp to convert, representing seconds since the epoch (1970-01-01 00:00:00 UTC).

tzstr, zoneinfo.ZoneInfo, pytz.timezone, dateutil.tz.tzfile, optional

Time zone for the Timestamp. If not provided, the Timestamp will be timezone-naive (i.e., without time zone information).

Returns

Timestamp

A Timestamp object representing the given POSIX timestamp.

See Also

Timestamp : Represents a single timestamp, similar to datetime. to_datetime : Converts various types of data to datetime. datetime.datetime.fromtimestamp : Returns a datetime from a POSIX timestamp.

Examples

Convert a POSIX timestamp to a Timestamp:

>>> pd.Timestamp.fromtimestamp(1584199972)
Timestamp('2020-03-14 15:32:52')

Note that the output may change depending on your local time and time zone:

>>> pd.Timestamp.fromtimestamp(1584199972, tz='UTC')
Timestamp('2020-03-14 15:32:52+0000', tz='UTC')

isocalendar()

Return a named tuple containing ISO year, week number, and weekday.

Return type:

tuple[int, int, int]

See Also

DatetimeIndex.isocalendarReturn a 3-tuple containing ISO year,

week number, and weekday for the given DatetimeIndex object.

datetime.date.isocalendar : The equivalent method for datetime.date objects.

Examples

>>> ts = pd.Timestamp('2023-01-01 10:00:00')
>>> ts
Timestamp('2023-01-01 10:00:00')
>>> ts.isocalendar()
datetime.IsoCalendarDate(year=2022, week=52, weekday=7)

isoweekday()

Return the day of the week represented by the date.

Monday == 1 … Sunday == 7.

Return type:

int

See Also

Timestamp.weekday : Return the day of the week with Monday=0, Sunday=6. Timestamp.isocalendar : Return a tuple containing ISO year, week number

and weekday.

datetime.date.isoweekday : Equivalent method in datetime module.

Examples

>>> ts = pd.Timestamp('2023-01-01 10:00:00')
>>> ts
Timestamp('2023-01-01 10:00:00')
>>> ts.isoweekday()
7

classmethod now(tz=None)

Return new Timestamp object representing current time local to tz.

This method returns a new Timestamp object that represents the current time. If a timezone is provided, either through a timezone object or an IANA standard timezone identifier, the current time will be localized to that timezone. Otherwise, it returns the current local time.

Return type:

Self

Parameters

tzstr or timezone object, default None

Timezone to localize to.

See Also

to_datetime : Convert argument to datetime. Timestamp.utcnow : Return a new Timestamp representing UTC day and time. Timestamp.today : Return the current time in the local timezone.

Examples

>>> pd.Timestamp.now()
Timestamp('2020-11-16 22:06:16.378782')

If you want a specific timezone, in this case ‘Brazil/East’:

>>> pd.Timestamp.now('Brazil/East')
Timestamp('2025-11-11 22:17:59.609943-03:00)

Analogous for pd.NaT:

>>> pd.NaT.now()
NaT

replace(year=None, month=None, day=None, hour=None, minute=None, second=None, microsecond=None, nanosecond=None, tzinfo=<class 'object'>, fold=None)

Implements datetime.replace, handles nanoseconds.

This method creates a new Timestamp object by replacing the specified fields with new values. The new Timestamp retains the original fields that are not explicitly replaced. This method handles nanoseconds, and the tzinfo parameter allows for timezone replacement without conversion.

Return type:

Self

Parameters

yearint, optional

The year to replace. If None, the year is not changed.

monthint, optional

The month to replace. If None, the month is not changed.

dayint, optional

The day to replace. If None, the day is not changed.

hourint, optional

The hour to replace. If None, the hour is not changed.

minuteint, optional

The minute to replace. If None, the minute is not changed.

secondint, optional

The second to replace. If None, the second is not changed.

microsecondint, optional

The microsecond to replace. If None, the microsecond is not changed.

nanosecondint, optional

The nanosecond to replace. If None, the nanosecond is not changed.

tzinfotz-convertible, optional

The timezone information to replace. If None, the timezone is not changed.

foldint, optional

The fold information to replace. If None, the fold is not changed.

Returns

Timestamp

A new Timestamp object with the specified fields replaced.

See Also

Timestamp : Represents a single timestamp, similar to datetime. to_datetime : Converts various types of data to datetime.

Notes

The replace method does not perform timezone conversions. If you need to convert the timezone, use the tz_convert method instead.

Examples

Create a timestamp object:

>>> ts = pd.Timestamp('2020-03-14T15:32:52.192548651', tz='UTC')
>>> ts
Timestamp('2020-03-14 15:32:52.192548651+0000', tz='UTC')

Replace year and the hour:

>>> ts.replace(year=1999, hour=10)
Timestamp('1999-03-14 10:32:52.192548651+0000', tz='UTC')

Replace timezone (not a conversion):

>>> import zoneinfo
>>> ts.replace(tzinfo=zoneinfo.ZoneInfo('US/Pacific'))
Timestamp('2020-03-14 15:32:52.192548651-0700', tz='US/Pacific')

Analogous for pd.NaT:

>>> pd.NaT.replace(tzinfo=zoneinfo.ZoneInfo('US/Pacific'))
NaT

round(freq, ambiguous='raise', nonexistent='raise')

Round the Timestamp to the specified resolution.

This method rounds the given Timestamp down to a specified frequency level. It is particularly useful in data analysis to normalize timestamps to regular frequency intervals. For instance, rounding to the nearest minute, hour, or day can help in time series comparisons or resampling operations.

Return type:

Self

Parameters

freqstr

Frequency string indicating the rounding resolution.

ambiguousbool or {‘raise’, ‘NaT’}, default ‘raise’

The behavior is as follows:

• bool contains flags to determine if time is dst or not (note that this flag is only applicable for ambiguous fall dst dates).

• ‘NaT’ will return NaT for an ambiguous time.

• ‘raise’ will raise a ValueError for an ambiguous time.

nonexistent{‘raise’, ‘shift_forward’, ‘shift_backward’, ‘NaT’, timedelta}, default ‘raise’

A nonexistent time does not exist in a particular timezone where clocks moved forward due to DST.

• ‘shift_forward’ will shift the nonexistent time forward to the closest existing time.

• ‘shift_backward’ will shift the nonexistent time backward to the closest existing time.

• ‘NaT’ will return NaT where there are nonexistent times.

• timedelta objects will shift nonexistent times by the timedelta.

• ‘raise’ will raise a ValueError if there are nonexistent times.

Returns

a new Timestamp rounded to the given resolution of freq

Raises

ValueError if the freq cannot be converted

See Also

datetime.round : Similar behavior in native Python datetime module. Timestamp.floor : Round the Timestamp downward to the nearest multiple

of the specified frequency.

Timestamp.ceilRound the Timestamp upward to the nearest multiple of

the specified frequency.

Notes

If the Timestamp has a timezone, rounding will take place relative to the local (“wall”) time and re-localized to the same timezone. When rounding near daylight savings time, use nonexistent and ambiguous to control the re-localization behavior.

Examples

Create a timestamp object:

>>> ts = pd.Timestamp('2020-03-14T15:32:52.192548651')

A timestamp can be rounded using multiple frequency units:

>>> ts.round(freq='h')  # hour
Timestamp('2020-03-14 16:00:00')

>>> ts.round(freq='min')  # minute
Timestamp('2020-03-14 15:33:00')

>>> ts.round(freq='s')  # seconds
Timestamp('2020-03-14 15:32:52')

>>> ts.round(freq='ms')  # milliseconds
Timestamp('2020-03-14 15:32:52.193000')

freq can also be a multiple of a single unit, like ‘5min’ (i.e. 5 minutes):

>>> ts.round(freq='5min')
Timestamp('2020-03-14 15:35:00')

or a combination of multiple units, like ‘1h30min’ (i.e. 1 hour and 30 minutes):

>>> ts.round(freq='1h30min')
Timestamp('2020-03-14 15:00:00')

Analogous for pd.NaT:

>>> pd.NaT.round()
NaT

When rounding near a daylight savings time transition, use ambiguous or nonexistent to control how the timestamp should be re-localized.

>>> ts_tz = pd.Timestamp("2021-10-31 01:30:00").tz_localize("Europe/Amsterdam")

>>> ts_tz.round("h", ambiguous=False)
Timestamp('2021-10-31 02:00:00+0100', tz='Europe/Amsterdam')

>>> ts_tz.round("h", ambiguous=True)
Timestamp('2021-10-31 02:00:00+0200', tz='Europe/Amsterdam')

strftime(format)

Return a formatted string of the Timestamp.

Return type:

str

Parameters

formatstr

Format string to convert Timestamp to string. See strftime documentation for more information on the format string: https://docs.python.org/3/library/datetime.html#strftime-and-strptime-behavior.

See Also

Timestamp.isoformat : Return the time formatted according to ISO 8601. pd.to_datetime : Convert argument to datetime. Period.strftime : Format a single Period.

Examples

>>> ts = pd.Timestamp('2020-03-14T15:32:52.192548651')
>>> ts.strftime('%Y-%m-%d %X')
'2020-03-14 15:32:52'

classmethod strptime(date_string, format)

Convert string argument to datetime.

This method is not implemented; calling it will raise NotImplementedError. Use pd.to_datetime() instead.

Return type:

Self

Parameters

date_stringstr

String to convert to a datetime.

formatstr, default None

The format string to parse time, e.g. “%d/%m/%Y”.

See Also

pd.to_datetime : Convert argument to datetime. datetime.datetime.strptime : Return a datetime corresponding to a string

representing a date and time, parsed according to a separate format string.

datetime.datetime.strftimeReturn a string representing the date and

time, controlled by an explicit format string.

Timestamp.isoformat : Return the time formatted according to ISO 8601.

Examples

>>> pd.Timestamp.strptime("2023-01-01", "%d/%m/%y")
Traceback (most recent call last):
NotImplementedError

time()

Return time object with same time but with tzinfo=None.

This method extracts the time part of the Timestamp object, excluding any timezone information. It returns a datetime.time object which only represents the time (hours, minutes, seconds, and microseconds).

Return type:

time

See Also

Timestamp.date : Return date object with same year, month and day. Timestamp.tz_convert : Convert timezone-aware Timestamp to another time zone. Timestamp.tz_localize : Localize the Timestamp to a timezone.

Examples

>>> ts = pd.Timestamp('2023-01-01 10:00:00')
>>> ts
Timestamp('2023-01-01 10:00:00')
>>> ts.time()
datetime.time(10, 0)

timetuple()

Return time tuple, compatible with time.localtime().

This method converts the Timestamp into a time tuple, which is compatible with functions like time.localtime(). The time tuple is a named tuple with attributes such as year, month, day, hour, minute, second, weekday, day of the year, and daylight savings indicator.

Return type:

struct_time

See Also

time.localtime : Converts a POSIX timestamp into a time tuple. Timestamp : The Timestamp that represents a specific point in time. datetime.datetime.timetuple : Equivalent method in the datetime module.

Examples

>>> ts = pd.Timestamp('2023-01-01 10:00:00')
>>> ts
Timestamp('2023-01-01 10:00:00')
>>> ts.timetuple()
time.struct_time(tm_year=2023, tm_mon=1, tm_mday=1,
tm_hour=10, tm_min=0, tm_sec=0, tm_wday=6, tm_yday=1, tm_isdst=-1)

timetz()

Return time object with same time and tzinfo.

This method returns a datetime.time object with the time and tzinfo corresponding to the pd.Timestamp object, ignoring any information about the day/date.

Return type:

time

See Also

datetime.datetime.timetzReturn datetime.time object with the

same time attributes as the datetime object.

datetime.timeClass to represent the time of day, independent

of any particular day.

datetime.datetime.tzinfoAttribute of datetime.datetime objects

representing the timezone of the datetime object.

Examples

>>> ts = pd.Timestamp('2023-01-01 10:00:00', tz='Europe/Brussels')
>>> ts
Timestamp('2023-01-01 10:00:00+0100', tz='Europe/Brussels')
>>> ts.timetz()
datetime.time(10, 0, tzinfo=<DstTzInfo 'Europe/Brussels' CET+1:00:00 STD>)

to_julian_date()

Convert TimeStamp to a Julian Date.

This method returns the number of days as a float since 0 Julian date, which is noon January 1, 4713 BC.

Return type:

float64

See Also

Timestamp.toordinal : Return proleptic Gregorian ordinal. Timestamp.timestamp : Return POSIX timestamp as float. Timestamp : Represents a single timestamp.

Examples

>>> ts = pd.Timestamp('2020-03-14T15:32:52')
>>> ts.to_julian_date()
2458923.147824074

classmethod today(tz=None)

Return the current time in the local timezone.

This differs from datetime.today() in that it can be localized to a passed timezone.

Return type:

Self

Parameters

tzstr or timezone object, default None

Timezone to localize to.

See Also

datetime.datetime.today : Returns the current local date. Timestamp.now : Returns current time with optional timezone. Timestamp : A class representing a specific timestamp.

Examples

>>> pd.Timestamp.today()
Timestamp('2020-11-16 22:37:39.969883')

Analogous for pd.NaT:

>>> pd.NaT.today()
NaT

toordinal()

Return proleptic Gregorian ordinal. January 1 of year 1 is day 1.

The proleptic Gregorian ordinal is a continuous count of days since January 1 of year 1, which is considered day 1. This method converts the Timestamp to its equivalent ordinal number, useful for date arithmetic and comparison operations.

Return type:

int

See Also

datetime.datetime.toordinal : Equivalent method in the datetime module. Timestamp : The Timestamp that represents a specific point in time. Timestamp.fromordinal : Create a Timestamp from an ordinal.

Examples

>>> ts = pd.Timestamp('2023-01-01 10:00:50')
>>> ts
Timestamp('2023-01-01 10:00:50')
>>> ts.toordinal()
738521

property tz

Alias for tzinfo.

The tz property provides a simple and direct way to retrieve the timezone information of a Timestamp object. It is particularly useful when working with time series data that includes timezone information, allowing for easy access and manipulation of the timezone context.

See Also

Timestamp.tzinfo : Returns the timezone information of the Timestamp. Timestamp.tz_convert : Convert timezone-aware Timestamp to another time zone. Timestamp.tz_localize : Localize the Timestamp to a timezone.

Examples

>>> ts = pd.Timestamp(1584226800, unit='s', tz='Europe/Stockholm')
>>> ts.tz
zoneinfo.ZoneInfo(key='Europe/Stockholm')

tz_convert(tz)

Convert timezone-aware Timestamp to another time zone.

This method is used to convert a timezone-aware Timestamp object to a different time zone. The original UTC time remains the same; only the time zone information is changed. If the Timestamp is timezone-naive, a TypeError is raised.

Return type:

Self

Parameters

tzstr, zoneinfo.ZoneInfo, pytz.timezone, dateutil.tz.tzfile or None

Time zone for time which Timestamp will be converted to. None will remove timezone holding UTC time.

Returns

converted : Timestamp

Raises

TypeError

If Timestamp is tz-naive.

See Also

Timestamp.tz_localize : Localize the Timestamp to a timezone. DatetimeIndex.tz_convert : Convert a DatetimeIndex to another time zone. DatetimeIndex.tz_localize : Localize a DatetimeIndex to a specific time zone. datetime.datetime.astimezone : Convert a datetime object to another time zone.

Examples

Create a timestamp object with UTC timezone:

>>> ts = pd.Timestamp('2020-03-14T15:32:52.192548651', tz='UTC')
>>> ts
Timestamp('2020-03-14 15:32:52.192548651+0000', tz='UTC')

Change to Tokyo timezone:

>>> ts.tz_convert(tz='Asia/Tokyo')
Timestamp('2020-03-15 00:32:52.192548651+0900', tz='Asia/Tokyo')

Can also use astimezone:

>>> ts.astimezone(tz='Asia/Tokyo')
Timestamp('2020-03-15 00:32:52.192548651+0900', tz='Asia/Tokyo')

Analogous for pd.NaT:

>>> pd.NaT.tz_convert(tz='Asia/Tokyo')
NaT

tz_localize(tz, ambiguous='raise', nonexistent='raise')

Localize the Timestamp to a timezone.

Convert naive Timestamp to local time zone or remove timezone from timezone-aware Timestamp.

Return type:

Self

Parameters

tzstr, zoneinfo.ZoneInfo, pytz.timezone, dateutil.tz.tzfile or None

Time zone for time which Timestamp will be converted to. None will remove timezone holding local time.

ambiguousbool, ‘NaT’, default ‘raise’

When clocks moved backward due to DST, ambiguous times may arise. For example in Central European Time (UTC+01), when going from 03:00 DST to 02:00 non-DST, 02:30:00 local time occurs both at 00:30:00 UTC and at 01:30:00 UTC. In such a situation, the ambiguous parameter dictates how ambiguous times should be handled.

The behavior is as follows:

• bool contains flags to determine if time is dst or not (note that this flag is only applicable for ambiguous fall dst dates).

• ‘NaT’ will return NaT for an ambiguous time.

• ‘raise’ will raise a ValueError for an ambiguous time.

nonexistent‘shift_forward’, ‘shift_backward’, ‘NaT’, timedelta, default ‘raise’

A nonexistent time does not exist in a particular timezone where clocks moved forward due to DST.

The behavior is as follows:

• ‘shift_forward’ will shift the nonexistent time forward to the closest existing time.

• ‘shift_backward’ will shift the nonexistent time backward to the closest existing time.

• ‘NaT’ will return NaT where there are nonexistent times.

• timedelta objects will shift nonexistent times by the timedelta.

• ‘raise’ will raise a ValueError if there are nonexistent times.

Returns

localized : Timestamp

Raises

TypeError

If the Timestamp is tz-aware and tz is not None.

See Also

Timestamp.tzinfo : Returns the timezone information of the Timestamp. Timestamp.tz_convert : Convert timezone-aware Timestamp to another time zone. DatetimeIndex.tz_localize : Localize a DatetimeIndex to a specific time zone. datetime.datetime.astimezone : Convert a datetime object to another time zone.

Examples

Create a naive timestamp object:

>>> ts = pd.Timestamp('2020-03-14T15:32:52.192548651')
>>> ts
Timestamp('2020-03-14 15:32:52.192548651')

Add ‘Europe/Stockholm’ as timezone:

>>> ts.tz_localize(tz='Europe/Stockholm')
Timestamp('2020-03-14 15:32:52.192548651+0100', tz='Europe/Stockholm')

Analogous for pd.NaT:

>>> pd.NaT.tz_localize()
NaT

property tzinfo

Returns the timezone info of the Timestamp.

This property returns a datetime.tzinfo object if the Timestamp is timezone-aware. If the Timestamp has no timezone, it returns None. If the Timestamp is in UTC or a fixed-offset timezone, it returns datetime.timezone. If the Timestamp uses an IANA timezone (e.g., “America/New_York”), it returns zoneinfo.ZoneInfo.

See Also

Timestamp.tz : Alias for tzinfo, may return a zoneinfo.ZoneInfo object. Timestamp.tz_convert : Convert timezone-aware Timestamp to another time zone. Timestamp.tz_localize : Localize the Timestamp to a specific timezone.

Examples

>>> ts = pd.Timestamp("2023-01-01 12:00:00", tz="UTC")
>>> ts.tzinfo
datetime.timezone.utc

>>> ts_naive = pd.Timestamp("2023-01-01 12:00:00")
>>> ts_naive.tzinfo

tzname()

Return time zone name.

This method returns the name of the Timestamp’s time zone as a string.

Return type:

str | None

See Also

Timestamp.tzinfo : Returns the timezone information of the Timestamp. Timestamp.tz_convert : Convert timezone-aware Timestamp to another time zone.

Examples

>>> ts = pd.Timestamp('2023-01-01 10:00:00', tz='Europe/Brussels')
>>> ts
Timestamp('2023-01-01 10:00:00+0100', tz='Europe/Brussels')
>>> ts.tzname()
'CET'

classmethod utcfromtimestamp(ts)

Construct a timezone-aware UTC datetime from a POSIX timestamp.

This method creates a datetime object from a POSIX timestamp, keeping the Timestamp object’s timezone.

Return type:

Self

Parameters

tsfloat

POSIX timestamp.

See Also

Timezone.tzname : Return time zone name. Timestamp.utcnow : Return a new Timestamp representing UTC day and time. Timestamp.fromtimestamp : Transform timestamp[, tz] to tz’s local

time from POSIX timestamp.

Notes

Timestamp.utcfromtimestamp behavior differs from datetime.utcfromtimestamp in returning a timezone-aware object.

Examples

>>> pd.Timestamp.utcfromtimestamp(1584199972)
Timestamp('2020-03-14 15:32:52+0000', tz='UTC')

classmethod utcnow()

Return a new Timestamp representing UTC day and time.

Return type:

Self

See Also

Timestamp : Constructs an arbitrary datetime. Timestamp.now : Return the current local date and time, which

can be timezone-aware.

Timestamp.todayReturn the current local date and time with

timezone information set to None.

to_datetime : Convert argument to datetime. date_range : Return a fixed frequency DatetimeIndex. Timestamp.utctimetuple : Return UTC time tuple, compatible with

time.localtime().

Examples

>>> pd.Timestamp.utcnow()
Timestamp('2020-11-16 22:50:18.092888+0000', tz='UTC')

utcoffset()

Return utc offset.

This method returns the difference between UTC and the local time as a timedelta object. It is useful for understanding the time difference between the current timezone and UTC.

Return type:

timedelta | None

Returns

timedelta

The difference between UTC and the local time as a timedelta object.

See Also

datetime.datetime.utcoffset :

Standard library method to get the UTC offset of a datetime object.

Timestamp.tzname : Return the name of the timezone. Timestamp.dst : Return the daylight saving time (DST) adjustment.

Examples

>>> ts = pd.Timestamp('2023-01-01 10:00:00', tz='Europe/Brussels')
>>> ts
Timestamp('2023-01-01 10:00:00+0100', tz='Europe/Brussels')
>>> ts.utcoffset()
datetime.timedelta(seconds=3600)

utctimetuple()

Return UTC time tuple, compatible with time.localtime().

This method converts the Timestamp to UTC and returns a time tuple containing 9 components: year, month, day, hour, minute, second, weekday, day of year, and DST flag. This is particularly useful for converting a Timestamp to a format compatible with time module functions.

Return type:

struct_time

Returns

time.struct_time

A time.struct_time object representing the UTC time.

See Also

datetime.datetime.utctimetuple :

Return UTC time tuple, compatible with time.localtime().

Timestamp.timetuple : Return time tuple of local time. time.struct_time : Time tuple structure used by time functions.

Examples

>>> ts = pd.Timestamp('2023-01-01 10:00:00', tz='Europe/Brussels')
>>> ts
Timestamp('2023-01-01 10:00:00+0100', tz='Europe/Brussels')
>>> ts.utctimetuple()
time.struct_time(tm_year=2023, tm_mon=1, tm_mday=1, tm_hour=9,
tm_min=0, tm_sec=0, tm_wday=6, tm_yday=1, tm_isdst=0)

weekday()

Return the day of the week represented by the date.

Monday == 0 … Sunday == 6.

Return type:

int

See Also

Timestamp.dayofweek : Return the day of the week with Monday=0, Sunday=6. Timestamp.isoweekday : Return the day of the week with Monday=1, Sunday=7. datetime.date.weekday : Equivalent method in datetime module.

Examples

>>> ts = pd.Timestamp('2023-01-01')
>>> ts
Timestamp('2023-01-01  00:00:00')
>>> ts.weekday()
6

weekofyear

Return the week number of the year.

Returns

int

See Also

Timestamp.weekday : Return the day of the week. Timestamp.quarter : Return the quarter of the year.

Examples

>>> ts = pd.Timestamp(2020, 3, 14)
>>> ts.week
11

cls: type[Self]

ts_input: integer | float | str | date | datetime | datetime64

return: Self | NaTType

forex_data.data_management.common.PolarsDatetime

alias of Datetime

forex_data.data_management.common.PolarsFloat32

alias of Float32

forex_data.data_management.common.PolarsDataFrame

alias of DataFrame

forex_data.data_management.common.PolarsLazyFrame

alias of LazyFrame

forex_data.data_management.database module

Created on Sun Feb 23 00:02:36 2025

@author: fiora

class forex_data.data_management.database.DatabaseConnector(**kwargs)

Bases: object

data_path: str | Path

data_type: str

engine: str

__init__(**kwargs)

connect()

Connect to database - must be implemented by subclasses.

Return type:

Any

check_connection()

Check database connection - must be implemented by subclasses.

Return type:

bool

write_data(target_table, dataframe, clean=False)

Write data to database - must be implemented by subclasses.

Return type:

None

read_data(market, ticker, timeframe, start, end)

Read data from database - must be implemented by subclasses.

Return type:

LazyFrame

read_data_year(market, ticker, timeframe, years)

Read data for specific year(s) - must be implemented by subclasses.

Return type:

LazyFrame

read_data_window(market, ticker, timeframe, date, periods, direction, comparison_column_name=None, check_level=None, comparison_operator=None, comparison_aggregation_mode=None)

Read window of data - must be implemented by subclasses.

Return type:

LazyFrame

read_last_timestamp(market, ticker, timeframe=None)

Read last timestamp from database - must be implemented by subclasses.

Return type:

datetime

get_tickers_list()

Return type:

List[str]

get_ticker_keys(ticker, timeframe=None)

Return type:

List[str]

get_ticker_timeframes_list(ticker)

Get timeframes list for ticker - must be implemented by subclasses.

Return type:

List[str]

get_ticker_years_list(ticker, timeframe='tick')

Return type:

List[int]

create_tickers_years_dict()

Create a dictionary containing ticker years data, structured as: {ticker: {timeframe: [year1, year2, …]}}

If no data files exist yet, returns an empty dictionary.

Return type:

Dict[str, Dict[str, List[int]]]

save_tickers_years_info(ticker_years_dict)

Save ticker years list to a JSON file.

Return type:

None

Parameters

ticker_years_dictDict[str, Dict[str, List[int]]]

Dictionary containing ticker years data, structured as: {ticker: {timeframe: [year1, year2, …]}}

filenamestr, optional

Name of the JSON file to save the data, by default ‘tickers_years.json’

Raises

TypeError

If ticker_years_dict is not a dictionary

IOError

If there’s an error writing the file

add_tickers_years_info_to_file(ticker, timeframe, year)

In local info filepath, update just the years list of the given ticker and timeframe by adding the year(s) specified if not already present

Return type:

None

Parameters

tickerstr

The ticker symbol to update

timeframestr

The timeframe for the ticker data

yearUnion[int, List[int]]

The year or list of years to add to the years list

Raises

TypeError

If year is not an integer or list of integers

clear_tickers_years_info(filter=None)

Clear the tickers years info file. If filter is specified, it has to be a ticker value and so only the tickers years info related to the filter are cleared. If filter is not specified, the entire file is cleared. Parameters ———- filter : Optional[str], optional

Filter to apply to the tickers years info file, by default None Filter has to be a ticker value

Return type:

None

clear_database(filter=None)

Clear database files If filter is provided and is a ticker present in database (files present) delete only files related to that ticker

Return type:

None

load_tickers_years_info()

Load ticker years list from a JSON file.

Return type:

Dict[str, Dict[str, List[int]]]

Returns

Dict[str, Dict[str, List[int]]]

Dictionary containing ticker years data, structured as: {ticker: {timeframe: [year1, year2, …]}}

Raises

FileNotFoundError

If the JSON file doesn’t exist

IOError

If there’s an error reading the file

class forex_data.data_management.database.LocalDBConnector(**kwargs)

Bases: DatabaseConnector

__init__(**kwargs)

write_data(target_table, dataframe, clean=False)

Write data to database - must be implemented by subclasses.

Return type:

None

read_data(market, ticker, timeframe, start, end, comparison_column_name=None, check_level=None, comparison_operator=None, comparison_aggregation_mode=None)

Read data from database - must be implemented by subclasses.

Return type:

LazyFrame

read_data_year(market, ticker, timeframe, years)

Read data for specific year(s) using SQL YEAR() filter.

Return type:

LazyFrame

read_data_window(market, ticker, timeframe, date, periods, direction, comparison_column_name=None, check_level=None, comparison_operator=None, comparison_aggregation_mode=None)

Read window of data specified by input requirements: the data window has timespan in order to return a dataframe with rows size equal to periods. Query the local db to calculate the start date of the window if direction is forward, or end date if backward.

Return type:

LazyFrame

read_last_timestamp(market, ticker, timeframe=None)

Read last timestamp from database. If timeframe is not set (None), retrieve the smallest timeframe available in local database

Parameters:

• market (str) – Market name

• ticker (str) – Ticker symbol

• timeframe (str) – Timeframe of the data

Returns:

Last timestamp in the local database for the

specified market, ticker and timeframe (or smallest available timeframe if timeframe is not set)

Return type:

datetime

class forex_data.data_management.database.LocalDBYearConnector(**kwargs)

Bases: DatabaseConnector

__init__(**kwargs)

write_data(target_table, dataframe, clean=False)

Write data to database. Since LocalDBYearConnector deals with a single year, it’s only possible to write a single year dataframe. Thus the target_table must be composed by 4 items (market, ticker, timeframe and year). In this object performance is prioritized, the method writes a single year data but sanity check that it is a year must be done by the caller. This to avoid other calls especially to polars collect() calls.

Return type:

None

Parameters

target_tablestr

Target table name

dataframeUnion[PolarsDataFrame, PolarsLazyFrame]

Data to write

cleanbool, optional

Clean data before writing, by default False

read_data(market, ticker, timeframe, start, end, comparison_column_name=None, check_level=None, comparison_operator=None, comparison_aggregation_mode=None)

Read data from database - must be implemented by subclasses.

Return type:

LazyFrame

read_data_year(market, ticker, timeframe, years)

Read data for specific year(s) using SQL YEAR() filter.

Return type:

LazyFrame

read_data_window(market, ticker, timeframe, date, periods, direction, comparison_column_name=None, check_level=None, comparison_operator=None, comparison_aggregation_mode=None)

Read window of data specified by input requirements: the data window has timespan in order to return a dataframe with rows size equal to periods. Query the local db to calculate the start date of the window if direction is forward, or end date if backward.

Parameters:

• market (str) – Market name (e.g., ‘forex’).

• ticker (str) – Trading pair (e.g., ‘XAUUSD’).

• timeframe (str) – Timeframe (e.g., ‘TICK’).

• date (datetime | str | Timestamp | Datetime) – Start or end date for the window.

• periods (int) – Number of timeframe units to look back or forward.

• direction (Literal['backward', 'forward']) – Direction to look back (‘backward’ or ‘forward’).

• comparison_column_name (Union[List[str], str, None]) – List of column names to compare. If None, no comparison is performed.

• check_level (Union[List[int | float], int, float, None]) – List of values to compare against. If None, no comparison is performed.

• | (comparison_operator (List[SUPPORTED_SQL_COMPARISON_OPERATORS]) – SUPPORTED_SQL_COMPARISON_OPERATORS | None): List of comparison operators to use for comparison. If None, no comparison is performed.

• (SUPPORTED_SQL_CONDITION_AGGREGATION_MODES (comparison_aggregation_mode) –

  None): Aggregation mode to use for comparison.

  If None, no comparison is performed.

Returns:

DataFrame with data for the window.

Return type:

LazyFrame

read_last_timestamp(market, ticker, timeframe=None)

Read last timestamp from database. If timeframe is not set (None), retrieve the smallest timeframe available in local database

Parameters:

• market (str) – Market name

• ticker (str) – Ticker symbol

• timeframe (str) – Timeframe of the data

Returns:

Last timestamp in the local database for the

specified market, ticker and timeframe (or smallest available timeframe if timeframe is not set)

Return type:

datetime

forex_data.data_management.historicaldata module

class forex_data.data_management.historicaldata.HistoricalManagerDB(**kwargs)

Bases: object

config: str

data_type: str

engine: str

data_path: str | Path

db_files_year_partitioning: bool

ssl_verify: bool

connector_id: str

max_discrepancy_with_now: str

__init__(**kwargs)

get_source_connectors()

Return type:

List[RemoteConnector]

clear_database(filter=None)

Return type:

None

add_timeframe(timeframe)

Add and cache a new timeframe to the database.

Creates aggregated data for the specified timeframe from tick data and caches it in the database for faster future access. The timeframe is added to the internal list of available timeframes.

Parameters:

timeframe (Union[str, List[str]]) – Timeframe(s) to add. Can be a single string or list of strings. Supported values: ‘1m’, ‘5m’, ‘15m’, ‘30m’, ‘1h’, ‘4h’, ‘1D’, ‘1W’, ‘1M’

Return type:

None

Returns:

None

Raises:

TypeError – If timeframe is not a string or list of strings

Example

>>> manager = HistoricalManagerDB(config='data_config.yaml')
>>> manager.add_timeframe('1W')  # Add weekly timeframe
>>> manager.add_timeframe(['4h', '1D'])  # Add multiple timeframes

Note

• Only new timeframes (not already in the list) will be processed

• Aggregation can take time for large datasets

• Once added, the timeframe is permanently cached in the database

get_data(ticker, timeframe, start, end, comparison_column_name=None, check_level=None, comparison_operator=None, aggregation_mode=None)

Retrieve OHLC historical data for the specified ticker and timeframe.

Fetches historical forex data from the database, automatically downloading and aggregating data if not already available. Supports multiple timeframes and date ranges.

Parameters:

• ticker (str) – Currency pair symbol (e.g., ‘EURUSD’, ‘GBPUSD’, ‘NZDUSD’). Case-insensitive.

• timeframe (str) – Candle timeframe for data aggregation. Supported frames: 1s (1 second) 1m (1 minute) 1h (1 hour) 1d (1 calendar day) 1w (1 calendar week) 1mo (1 calendar month) 1q (1 calendar quarter) 1y (1 calendar year)

• integer (and any multiple of these values by a positive) – ‘2m’, ‘3m’, ‘2h’, ‘3h’, etc.

• e.g. – ‘2m’, ‘3m’, ‘2h’, ‘3h’, etc.

• start (str | datetime) – Start date for data retrieval. Accepts: - ISO format: ‘YYYY-MM-DD’ or ‘YYYY-MM-DD HH:MM:SS’ - datetime object

• end (str | datetime) – End date for data retrieval. Same format as start. Must be after start date.

• comparison_column_name (Union[List[str], str, None]) – Column names to retrieve. Default is None.

• check_level (Union[List[int | float], int, float, None]) – Check level for conditions. Default is None.

• comparison_operator (Union[List[Literal['>', '<', '>=', '<=', '==', '!=']], Literal['>', '<', '>=', '<=', '==', '!='], None]) – Condition for data retrieval. Default is None.

• aggregation_mode (Optional[Literal['AND', 'OR']]) – Aggregation mode for data retrieval. Default is None.

Returns:

DataFrame containing OHLC data with columns:

• timestamp: datetime column with candle timestamps

• open: Opening price (float32)

• high: Highest price (float32)

• low: Lowest price (float32)

• close: Closing price (float32)

Return type:

Union[DataFrame, LazyFrame]

Raises:

• TickerNotFoundError – If the ticker is not available in the historical database

• ValueError – If timeframe is invalid or end date is before start date

Example

>>> manager = HistoricalManagerDB(config='data_config.yaml')
>>> data = manager.get_data(
...     ticker='EURUSD',
...     timeframe='1h',
...     start='2020-01-01',
...     end='2020-01-31'
... )
>>> print(f"Retrieved {len(data)} hourly candles")
Retrieved 744 hourly candles

Note

• Data is automatically downloaded from histdata.com if not cached locally

• First call for a new timeframe may take longer as it builds the aggregation

• Downloaded data is cached for faster subsequent access

• Ticker names are case-insensitive and automatically normalized

get_data_window(ticker, date, timeframe, periods, direction, comparison_column_name=None, check_level=None, comparison_operator=None, comparison_aggregation_mode=None)

Retrieve OHLC historical window data for the specified ticker. The unit resoluton of the window is set equal to the timeframe. Unit resolution is the timespan between two candles (rows) in normal conditions: during weekends the rule does not apply. The window total number of candles (rows) is specified by timeframe * periods.

Fetches historical forex data from the database, automatically downloading and aggregating data if not already available. Supports multiple timeframes

Parameters:

• ticker (str) – Currency pair symbol (e.g., ‘EURUSD’, ‘GBPUSD’, ‘NZDUSD’). Case-insensitive.

• date (date) – date for data retrieval. Accepts: - ISO format: ‘YYYY-MM-DD’ or ‘YYYY-MM-DD HH:MM:SS’ - datetime object

• timeframe (str) – Candle timeframe for data aggregation. Supported frames: 1s (1 second) 1m (1 minute) 1h (1 hour) 1d (1 calendar day) 1w (1 calendar week) 1mo (1 calendar month) 1q (1 calendar quarter) 1y (1 calendar year) periods (int): Number of timeframe units to look back or forward.

• direction (Literal['backward', 'forward']) – Direction to look back (‘backward’ or ‘forward’).

• comparison_column_name (Union[List[str], str, None]) – List of column names to compare. If None, no comparison is performed.

• check_level (Union[List[int | float], int, float, None]) – List of values to compare against. If None, no comparison is performed.

• | (comparison_operator (List[SUPPORTED_SQL_COMPARISON_OPERATORS]) – SUPPORTED_SQL_COMPARISON_OPERATORS | None): List of comparison operators to use for comparison. If None, no comparison is performed.

• (SUPPORTED_SQL_CONDITION_AGGREGATION_MODES (comparison_aggregation_mode) –

  None): Aggregation mode to use for comparison.

  If None, no comparison is performed.

Returns:

DataFrame with the historical

data.

Return type:

Union[DataFrame, LazyFrame]

Raises:

• TickerNotFoundError – If the ticker is not found.

• TickerDataNotFoundError – If the ticker data is not found.

• TickerDataBadTypeException – If the ticker data is not of the expected type.

• TickerDataInvalidException – If the ticker data is invalid.

Examples

>>> get_data_window(
...     ticker='EURUSD',
...     date='2022-01-01',
...     timeframe='1m',
...     window=10,
...     direction='backward'
... )

plot(ticker, timeframe, start_date, end_date)

Plot candlestick chart for the specified ticker and date range.

Generates an interactive candlestick chart using mplfinance, displaying OHLC (Open, High, Low, Close) data for the specified time period.

Parameters:

• ticker (str) – Currency pair symbol (e.g., ‘EURUSD’, ‘GBPUSD’)

• timeframe (str) – Candle timeframe (e.g., ‘1m’, ‘5m’, ‘1h’, ‘1D’, ‘1W’)

• start_date (str) – Start date in ISO format ‘YYYY-MM-DD’ or ‘YYYY-MM-DD HH:MM:SS’

• end_date (str) – End date in ISO format ‘YYYY-MM-DD’ or ‘YYYY-MM-DD HH:MM:SS’

Returns:

Displays the chart using matplotlib

Return type:

None

Example

>>> manager = HistoricalManagerDB(config='data_config.yaml')
>>> manager.plot(
...     ticker='EURUSD',
...     timeframe='1D',
...     start_date='2020-01-01',
...     end_date='2020-12-31'
... )

Note

The chart will be displayed in a matplotlib window. The data is automatically fetched using get_data() and converted to the appropriate format for plotting.

close()

forex_data.data_management.realtimedata module

Module contents

Created on Sat Jul 16 01:31:35 2022

@author: fiora

class forex_data.data_management.HistoricalManagerDB(**kwargs)

Bases: object

config: str

data_type: str

engine: str

data_path: str | Path

db_files_year_partitioning: bool

ssl_verify: bool

connector_id: str

max_discrepancy_with_now: str

__init__(**kwargs)

get_source_connectors()

Return type:

List[RemoteConnector]

clear_database(filter=None)

Return type:

None

add_timeframe(timeframe)

Add and cache a new timeframe to the database.

Creates aggregated data for the specified timeframe from tick data and caches it in the database for faster future access. The timeframe is added to the internal list of available timeframes.

Parameters:

timeframe (Union[str, List[str]]) – Timeframe(s) to add. Can be a single string or list of strings. Supported values: ‘1m’, ‘5m’, ‘15m’, ‘30m’, ‘1h’, ‘4h’, ‘1D’, ‘1W’, ‘1M’

Return type:

None

Returns:

None

Raises:

TypeError – If timeframe is not a string or list of strings

Example

>>> manager = HistoricalManagerDB(config='data_config.yaml')
>>> manager.add_timeframe('1W')  # Add weekly timeframe
>>> manager.add_timeframe(['4h', '1D'])  # Add multiple timeframes

Note

• Only new timeframes (not already in the list) will be processed

• Aggregation can take time for large datasets

• Once added, the timeframe is permanently cached in the database

get_data(ticker, timeframe, start, end, comparison_column_name=None, check_level=None, comparison_operator=None, aggregation_mode=None)

Retrieve OHLC historical data for the specified ticker and timeframe.

Fetches historical forex data from the database, automatically downloading and aggregating data if not already available. Supports multiple timeframes and date ranges.

Parameters:

• ticker (str) – Currency pair symbol (e.g., ‘EURUSD’, ‘GBPUSD’, ‘NZDUSD’). Case-insensitive.

• timeframe (str) – Candle timeframe for data aggregation. Supported frames: 1s (1 second) 1m (1 minute) 1h (1 hour) 1d (1 calendar day) 1w (1 calendar week) 1mo (1 calendar month) 1q (1 calendar quarter) 1y (1 calendar year)

• integer (and any multiple of these values by a positive) – ‘2m’, ‘3m’, ‘2h’, ‘3h’, etc.

• e.g. – ‘2m’, ‘3m’, ‘2h’, ‘3h’, etc.

• start (str | datetime) – Start date for data retrieval. Accepts: - ISO format: ‘YYYY-MM-DD’ or ‘YYYY-MM-DD HH:MM:SS’ - datetime object

• end (str | datetime) – End date for data retrieval. Same format as start. Must be after start date.

• comparison_column_name (Union[List[str], str, None]) – Column names to retrieve. Default is None.

• check_level (Union[List[int | float], int, float, None]) – Check level for conditions. Default is None.

• comparison_operator (Union[List[Literal['>', '<', '>=', '<=', '==', '!=']], Literal['>', '<', '>=', '<=', '==', '!='], None]) – Condition for data retrieval. Default is None.

• aggregation_mode (Optional[Literal['AND', 'OR']]) – Aggregation mode for data retrieval. Default is None.

Returns:

DataFrame containing OHLC data with columns:

• timestamp: datetime column with candle timestamps

• open: Opening price (float32)

• high: Highest price (float32)

• low: Lowest price (float32)

• close: Closing price (float32)

Return type:

Union[DataFrame, LazyFrame]

Raises:

• TickerNotFoundError – If the ticker is not available in the historical database

• ValueError – If timeframe is invalid or end date is before start date

Example

>>> manager = HistoricalManagerDB(config='data_config.yaml')
>>> data = manager.get_data(
...     ticker='EURUSD',
...     timeframe='1h',
...     start='2020-01-01',
...     end='2020-01-31'
... )
>>> print(f"Retrieved {len(data)} hourly candles")
Retrieved 744 hourly candles

Note

• Data is automatically downloaded from histdata.com if not cached locally

• First call for a new timeframe may take longer as it builds the aggregation

• Downloaded data is cached for faster subsequent access

• Ticker names are case-insensitive and automatically normalized

get_data_window(ticker, date, timeframe, periods, direction, comparison_column_name=None, check_level=None, comparison_operator=None, comparison_aggregation_mode=None)

Retrieve OHLC historical window data for the specified ticker. The unit resoluton of the window is set equal to the timeframe. Unit resolution is the timespan between two candles (rows) in normal conditions: during weekends the rule does not apply. The window total number of candles (rows) is specified by timeframe * periods.

Fetches historical forex data from the database, automatically downloading and aggregating data if not already available. Supports multiple timeframes

Parameters:

• ticker (str) – Currency pair symbol (e.g., ‘EURUSD’, ‘GBPUSD’, ‘NZDUSD’). Case-insensitive.

• date (date) – date for data retrieval. Accepts: - ISO format: ‘YYYY-MM-DD’ or ‘YYYY-MM-DD HH:MM:SS’ - datetime object

• timeframe (str) – Candle timeframe for data aggregation. Supported frames: 1s (1 second) 1m (1 minute) 1h (1 hour) 1d (1 calendar day) 1w (1 calendar week) 1mo (1 calendar month) 1q (1 calendar quarter) 1y (1 calendar year) periods (int): Number of timeframe units to look back or forward.

• direction (Literal['backward', 'forward']) – Direction to look back (‘backward’ or ‘forward’).

• comparison_column_name (Union[List[str], str, None]) – List of column names to compare. If None, no comparison is performed.

• check_level (Union[List[int | float], int, float, None]) – List of values to compare against. If None, no comparison is performed.

• | (comparison_operator (List[SUPPORTED_SQL_COMPARISON_OPERATORS]) – SUPPORTED_SQL_COMPARISON_OPERATORS | None): List of comparison operators to use for comparison. If None, no comparison is performed.

• (SUPPORTED_SQL_CONDITION_AGGREGATION_MODES (comparison_aggregation_mode) –

  None): Aggregation mode to use for comparison.

  If None, no comparison is performed.

Returns:

DataFrame with the historical

data.

Return type:

Union[DataFrame, LazyFrame]

Raises:

• TickerNotFoundError – If the ticker is not found.

• TickerDataNotFoundError – If the ticker data is not found.

• TickerDataBadTypeException – If the ticker data is not of the expected type.

• TickerDataInvalidException – If the ticker data is invalid.

Examples

>>> get_data_window(
...     ticker='EURUSD',
...     date='2022-01-01',
...     timeframe='1m',
...     window=10,
...     direction='backward'
... )

plot(ticker, timeframe, start_date, end_date)

Plot candlestick chart for the specified ticker and date range.

Generates an interactive candlestick chart using mplfinance, displaying OHLC (Open, High, Low, Close) data for the specified time period.

Parameters:

• ticker (str) – Currency pair symbol (e.g., ‘EURUSD’, ‘GBPUSD’)

• timeframe (str) – Candle timeframe (e.g., ‘1m’, ‘5m’, ‘1h’, ‘1D’, ‘1W’)

• start_date (str) – Start date in ISO format ‘YYYY-MM-DD’ or ‘YYYY-MM-DD HH:MM:SS’

• end_date (str) – End date in ISO format ‘YYYY-MM-DD’ or ‘YYYY-MM-DD HH:MM:SS’

Returns:

Displays the chart using matplotlib

Return type:

None

Example

>>> manager = HistoricalManagerDB(config='data_config.yaml')
>>> manager.plot(
...     ticker='EURUSD',
...     timeframe='1D',
...     start_date='2020-01-01',
...     end_date='2020-12-31'
... )

Note

The chart will be displayed in a matplotlib window. The data is automatically fetched using get_data() and converted to the appropriate format for plotting.

close()

class forex_data.data_management.BASE_DATA_COLUMN_NAME

Bases: object

TIMESTAMP = 'timestamp'

OPEN = 'open'

HIGH = 'high'

LOW = 'low'

CLOSE = 'close'

ASK = 'ask'

BID = 'bid'

VOL = 'vol'

P_VALUE = 'p'

TRANSACTIONS = 'transactions'

VWAP = 'vwap'

OTC = 'otc'

class forex_data.data_management.DATA_FILE_COLUMN_INDEX

Bases: object

TIMESTAMP = 0

class forex_data.data_management.DEFAULT_PATHS

Bases: object

BASE_PATH = '/home/runner/.database'

HIST_DATA_FOLDER = 'HistoricalData'

REALTIME_DATA_FOLDER = 'RealtimeData'

class forex_data.data_management.SQL_COMPARISON_OPERATORS

Bases: object

GREATER_THAN = '>'

LESS_THAN = '<'

GREATER_THAN_OR_EQUAL = '>='

LESS_THAN_OR_EQUAL = '<='

EQUAL = '=='

NOT_EQUAL = '!='

class forex_data.data_management.SQL_CONDITION_AGGREGATION_MODES

Bases: object

AND = 'AND'

OR = 'OR'

forex_data.data_management.empty_dataframe(engine)

forex_data.data_management.is_empty_dataframe(dataframe)

forex_data.data_management.shape_dataframe(dataframe)

forex_data.data_management.get_dataframe_column(dataframe, column)

forex_data.data_management.get_dataframe_row(dataframe, row)

forex_data.data_management.get_dataframe_element(dataframe, column, row)

forex_data.data_management.get_attrs_names(instance_object, **kwargs)

forex_data.data_management.any_date_to_datetime64(any_date, date_format='ISO8601', unit=None, to_pydatetime=False)

forex_data.data_management.get_db_key_elements(key)

forex_data.data_management.check_timeframe_str(tf, engine='pandas')

class forex_data.data_management.DatabaseConnector(**kwargs)

Bases: object

data_path: str | Path

data_type: str

engine: str

__init__(**kwargs)

connect()

Connect to database - must be implemented by subclasses.

Return type:

Any

check_connection()

Check database connection - must be implemented by subclasses.

Return type:

bool

write_data(target_table, dataframe, clean=False)

Write data to database - must be implemented by subclasses.

Return type:

None

read_data(market, ticker, timeframe, start, end)

Read data from database - must be implemented by subclasses.

Return type:

LazyFrame

read_data_year(market, ticker, timeframe, years)

Read data for specific year(s) - must be implemented by subclasses.

Return type:

LazyFrame

read_data_window(market, ticker, timeframe, date, periods, direction, comparison_column_name=None, check_level=None, comparison_operator=None, comparison_aggregation_mode=None)

Read window of data - must be implemented by subclasses.

Return type:

LazyFrame

read_last_timestamp(market, ticker, timeframe=None)

Read last timestamp from database - must be implemented by subclasses.

Return type:

datetime

get_tickers_list()

Return type:

List[str]

get_ticker_keys(ticker, timeframe=None)

Return type:

List[str]

get_ticker_timeframes_list(ticker)

Get timeframes list for ticker - must be implemented by subclasses.

Return type:

List[str]

get_ticker_years_list(ticker, timeframe='tick')

Return type:

List[int]

create_tickers_years_dict()

Create a dictionary containing ticker years data, structured as: {ticker: {timeframe: [year1, year2, …]}}

If no data files exist yet, returns an empty dictionary.

Return type:

Dict[str, Dict[str, List[int]]]

save_tickers_years_info(ticker_years_dict)

Save ticker years list to a JSON file.

Return type:

None

Parameters

ticker_years_dictDict[str, Dict[str, List[int]]]

Dictionary containing ticker years data, structured as: {ticker: {timeframe: [year1, year2, …]}}

filenamestr, optional

Name of the JSON file to save the data, by default ‘tickers_years.json’

Raises

TypeError

If ticker_years_dict is not a dictionary

IOError

If there’s an error writing the file

add_tickers_years_info_to_file(ticker, timeframe, year)

In local info filepath, update just the years list of the given ticker and timeframe by adding the year(s) specified if not already present

Return type:

None

Parameters

tickerstr

The ticker symbol to update

timeframestr

The timeframe for the ticker data

yearUnion[int, List[int]]

The year or list of years to add to the years list

Raises

TypeError

If year is not an integer or list of integers

clear_tickers_years_info(filter=None)

Clear the tickers years info file. If filter is specified, it has to be a ticker value and so only the tickers years info related to the filter are cleared. If filter is not specified, the entire file is cleared. Parameters ———- filter : Optional[str], optional

Filter to apply to the tickers years info file, by default None Filter has to be a ticker value

Return type:

None

clear_database(filter=None)

Clear database files If filter is provided and is a ticker present in database (files present) delete only files related to that ticker

Return type:

None

load_tickers_years_info()

Load ticker years list from a JSON file.

Return type:

Dict[str, Dict[str, List[int]]]

Returns

Dict[str, Dict[str, List[int]]]

Dictionary containing ticker years data, structured as: {ticker: {timeframe: [year1, year2, …]}}

Raises

FileNotFoundError

If the JSON file doesn’t exist

IOError

If there’s an error reading the file

class forex_data.data_management.LocalDBConnector(**kwargs)

Bases: DatabaseConnector

__init__(**kwargs)

write_data(target_table, dataframe, clean=False)

Write data to database - must be implemented by subclasses.

Return type:

None

read_data(market, ticker, timeframe, start, end, comparison_column_name=None, check_level=None, comparison_operator=None, comparison_aggregation_mode=None)

Read data from database - must be implemented by subclasses.

Return type:

LazyFrame

read_data_year(market, ticker, timeframe, years)

Read data for specific year(s) using SQL YEAR() filter.

Return type:

LazyFrame

read_data_window(market, ticker, timeframe, date, periods, direction, comparison_column_name=None, check_level=None, comparison_operator=None, comparison_aggregation_mode=None)

Read window of data specified by input requirements: the data window has timespan in order to return a dataframe with rows size equal to periods. Query the local db to calculate the start date of the window if direction is forward, or end date if backward.

Return type:

LazyFrame

read_last_timestamp(market, ticker, timeframe=None)

Read last timestamp from database. If timeframe is not set (None), retrieve the smallest timeframe available in local database

Parameters:

• market (str) – Market name

• ticker (str) – Ticker symbol

• timeframe (str) – Timeframe of the data

Returns:

Last timestamp in the local database for the

specified market, ticker and timeframe (or smallest available timeframe if timeframe is not set)

Return type:

datetime

forex_data.data_management.concat_data(data_list=_CountingAttr(counter=27, _default=NOTHING, repr=True, eq=True, order=True, hash=None, init=True, on_setattr=None, alias=None, metadata={}))

forex_data.data_management.reframe_data(dataframe, tf)

Parameters

dataTYPE

DESCRIPTION.

tfTYPE

DESCRIPTION.

Raises

ValueError

DESCRIPTION.

Returns

Dataframe

DESCRIPTION.

forex_data.data_management.validator_dir_path(create_if_missing=False)

exception forex_data.data_management.TickerNotFoundError

Bases: Exception

exception forex_data.data_management.TickerDataNotFoundError

Bases: Exception

exception forex_data.data_management.TickerDataBadTypeException

Bases: Exception

exception forex_data.data_management.TickerDataInvalidException

Bases: Exception

forex_data.data_management.get_histdata_tickers(verify=True)

Get all available tickers from HistData.com.

Return type:

List[str]

Parameters

verifybool, optional

Whether to verify SSL certificates. Default is True.

Returns

List[str]

List of all available tickers (e.g., [‘EURUSD’, ‘GBPUSD’, …]).

class forex_data.data_management.POLARS_DTYPE_DICT

Bases: object

TICK_DTYPE = {'ask': Float32, 'bid': Float32, 'p': Float32, 'vol': Float32}

TF_DTYPE = {'close': Float32, 'high': Float32, 'low': Float32, 'open': Float32}

TIME_TICK_DTYPE = {'ask': Float32, 'bid': Float32, 'p': Float32, 'timestamp': Datetime(time_unit='ms', time_zone=None), 'vol': Float32}

TIME_TF_DTYPE = {'close': Float32, 'high': Float32, 'low': Float32, 'open': Float32, 'timestamp': Datetime(time_unit='ms', time_zone=None)}

forex_data.data_management.business_days_data(dataframe)

Remove non-business days data from the input dataframe. Filter out weekends data: saturday and sunday. Use holidays to get list of country holidays. Consider dataframe always have a column named ‘timestamp’ of type datetime.

Return type:

DataFrame | LazyFrame

forex_data.data_management.get_class_attr_keys(var)

forex_data.data_management.get_class_attr_values(var)

forex_data.data_management.get_class_attr_dict(var)

forex_data.data_management.random_date_between(start_date, end_date)

Get a random datetime between two datetime objects.

Parameters:

• start_date (datetime) – The start date.

• end_date (datetime) – The end date.

Returns:

A random datetime between start_date and end_date.

Return type:

datetime

class forex_data.data_management.RemoteConnector(**kwargs)

Bases: object

data_path: str | Path

data_type: str

engine: str

__init__(**kwargs)

connect()

Connect to database - must be implemented by subclasses.

Return type:

Any

check_connection()

Check database connection - must be implemented by subclasses.

Return type:

bool

clear_temporary_folder()

Return type:

None

get_available_tickers()

Get available tickers - must be implemented by subclasses.

Return type:

List[str]

get_data(symbol, timeframe, start_date, end_date)

Get data - must be implemented by subclasses.

Return type:

LazyFrame

get_recent_data(symbol, timeframe, interval_window)

Get recent data - must be implemented by subclasses.

Return type:

LazyFrame

download_month_raw(ticker, year, month_num, engine='polars_lazy')

Download a single month of tick data from histdata.com and parse it into a DataFrame.

Scrapes the download token from the histdata page, POSTs to the download endpoint to retrieve the ZIP archive, extracts the CSV content, and converts it to a DataFrame using the specified engine.

Return type:

Union[DataFrame, LazyFrame]

Parameters

tickerstr

The ticker symbol for the currency pair (e.g. ‘EURUSD’).

yearint

The year of the data to download (e.g. 2023).

month_numint

The month number (1-12) of the data to download.

enginestr, optional

The DataFrame engine to use: ‘pandas’ for pandas.DataFrame or ‘polars’ for PolarsDataFrame. Defaults to ‘polars’.

Returns

Union[PolarsDataFrame, PolarsLazyFrame]

The tick data loaded into a DataFrame of the specified engine.

class forex_data.data_management.RealTimeDBConnectorTwelveData(**kwargs)

Bases: RemoteConnector

Class to read real-time data from the database using TwelveData API.

api_key: str

plan: str

property tier: str

self.tier.

Type:

Alias for plan to avoid AttributeError

__init__(**kwargs)

property chunk_size: int

Max number of data points per request.

property max_requests_per_minute: int

Max number of requests per minute.

get_realtime_price(symbol)

Fetches the instantaneous real-time price and outputs as a 1-row LazyFrame.

Return type:

LazyFrame

get_data(symbol, timeframe, start_date, end_date)

Fetches historical data for a specific date range. Automatically checks boundaries for maximum output limits per call.

Return type:

LazyFrame

get_recent_data(symbol, timeframe, interval_window)

Fetches recent data relative to the current time minus the interval_window. Example: Pass timedelta(days=90) to get the most recent rolling 3 months.

Return type:

LazyFrame

class forex_data.data_management.HistDataConnector(**kwargs)

Bases: RemoteConnector

Connector class that encapsulates all HTTP interactions with histdata.com.

Wraps connectivity checks, ticker list scraping, download token extraction, and monthly tick data ZIP downloads behind a single remote connector interface.

ssl_verify: bool

__init__(**kwargs)

connect()

Configure the requests session with SSL settings.

Return type:

None

check_connection()

Test connectivity to histdata.com.

Return type:

bool

get_available_tickers()

Scrape available tickers from histdata.com.

Results are cached after the first successful call on this instance.

Return type:

List[str]

Returns

List[str]

Sorted, deduplicated list of ticker symbols (e.g. [‘EURUSD’, ‘GBPUSD’, …]).

download_month_raw(ticker, year, month_num, engine='polars_lazy')

Download a single month of tick data from histdata.com and parse it into a DataFrame.

Scrapes the download token from the histdata page, POSTs to the download endpoint to retrieve the ZIP archive, extracts the CSV content, and converts it to a DataFrame using the specified engine.

Return type:

Union[DataFrame, LazyFrame]

Parameters

tickerstr

Forex pair symbol (e.g. ‘eurusd’).

yearint

Data year.

month_numint

Month number (1-12).

enginestr

DataFrame engine to use for parsing. One of ‘pandas’, ‘pyarrow’, ‘polars’, ‘polars_lazy’.

Returns

Union[PolarsDataFrame, PolarsLazyFrame]

Parsed tick data DataFrame with columns: timestamp, ask, bid, vol, p.

Raises

TickerNotFoundError

If the download token cannot be scraped (ticker not supported).

TickerDataBadTypeException

If the downloaded content is not a valid ZIP file.

TickerDataNotFoundError

If the ZIP archive contents cannot be extracted.

TickerDataInvalidException

If the extracted file type is unexpected.

class forex_data.data_management.DukascopyConnector(**kwargs)

Bases: RemoteConnector

Connector class that encapsulates all HTTP interactions with Dukascopy’s historical datafeed.

Wraps connectivity checks, ticker registry, and tick data downloading via tick_vault library behind a single RemoteConnector-derived interface.

ssl_verify: bool

__init__(**kwargs)

connect()

Configure session and tick_vault base directory.

Return type:

None

check_connection()

Test connectivity to dukascopy.com.

Return type:

bool

get_available_tickers()

Get list of available tickers from tick_vault’s registry and Dukascopy’s tools page.

Return type:

List[str]

Returns

List[str]

Sorted, deduplicated list of ticker symbols (e.g. [‘BTCUSD’, ‘EURUSD’, …]).

download_month_raw(ticker, year, month_num, temp_filepath='', engine='polars_lazy')

Downloads tick data for a specific year and month from Dukascopy using tick_vault.

Return type:

Union[DataFrame, LazyFrame]

Parameters

ticker: str

The currency pair (e.g., ‘EURUSD’).

year: int

Year of the data to download.

month_num: int

Month of the data (1-12).

engine: str

Either ‘polars’ or ‘polars_lazy’.

Returns

Union[PolarsDataFrame, PolarsLazyFrame]

Polars DataFrame or LazyFrame with column names matching HistDataConnector.

get_recent_data(symbol, timeframe, interval_window, engine='polars_lazy')

Fetches recent data relative to the current time minus the interval_window.

Return type:

Union[DataFrame, LazyFrame]

Parameters

symbol: str

The currency pair (e.g. ‘EURUSD’).

timeframe: str

The target timeframe (e.g. ‘TICK’, ‘1m’, ‘5m’).

interval_window: timedelta

The duration of data to fetch (e.g., timedelta(days=90)).

engine: str

Either ‘polars’ or ‘polars_lazy’.

Returns

Union[PolarsDataFrame, PolarsLazyFrame]

Polars DataFrame or LazyFrame containing recent data.