Time Helpers¶

Time helper functions.

Kline boundary functions delegated to kline-timestamp library. Generic datetime/string/ms conversions kept here.

Functions:

`parse_timestamp`(timestamp_str[, timezone])	Parses a timestamp string in multiple formats and returns a timezone-aware datetime.
`convert_ms_column_to_datetime_with_zone`(df, col)	Replace a column from milliseconds to datetime with time zone.
`convert_datetime_to_string`(dt)	Converts a datetime to a string.
`convert_datetime_to_milliseconds`(dt[, timezoned])	Converts a datetime to milliseconds.
`convert_string_to_milliseconds`(ts[, timezoned])	Converts a string to milliseconds.
`convert_milliseconds_to_utc_string`(ms)	Converts a timestamp in milliseconds to a UTC string.
`convert_milliseconds_to_time_zone_datetime`(ms)	Converts a timestamp in milliseconds to a timezone-aware datetime.
`convert_milliseconds_to_str`(ms, timezoned)	Converts a timestamp in milliseconds to a timezone-aware string.
`convert_string_to_datetime`(ts[, timezoned])	Converts a string to datetime.
`check_tick_interval`(tick_interval)	Checks if argument is a Binance valid tick interval for candles.
`open_from_milliseconds`(ms, tick_interval)	Returns the open timestamp in milliseconds for a tick interval.
`next_open_by_milliseconds`(ms, tick_interval)	Calculates the next open timestamp in milliseconds for a tick interval.
`infer_frequency_and_set_index`(data[, ...])	Infers the frequency of the DataFrame based on the 'Open timestamp' column and sets it as the DataFrame index.
`get_dataframe_time_index_ranges`(data[, interval])	Divides a DataFrame into time ranges of a specified interval.
`remove_initial_included_ranges`(time_ranges, ...)	Remove the time ranges that are completely included in the initial period.

parse_timestamp(timestamp_str: str, timezone: str | BaseTzInfo | None = 'Europe/Madrid') → datetime[source]¶

Parses a timestamp string in multiple formats and returns a timezone-aware datetime.

If the timestamp string doesn’t include time zone information, it is assumed to be in UTC. If timezone parameter is specified, the datetime is converted to that timezone.

Parameters:

timestamp_str (str) – Timestamp string. Accepts ISO 8601 and common date/time formats.
timezone – Time zone in IANA format (e.g., “Europe/Madrid”) or pytz timezone object.

Return datetime:

Timezone-aware datetime object.

convert_ms_column_to_datetime_with_zone(df: DataFrame, col: str, time_zone='Europe/Madrid', ambiguous='infer') → Series[source]¶

Replace a column from milliseconds to datetime with time zone.

Parameters:

df – A pandas dataframe.
col – Name of the column to replace.
time_zone – A time zone like ‘Europe/Madrid’
ambiguous – A string or list to resolve ambiguous times during DST transitions. Default is ‘infer’.

Returns:

Modified dataframe.

convert_datetime_to_string(dt) → str[source]¶

Converts a datetime to a string.

Parameters:: dt – A datetime object.
Returns:: A string with a date and time. Example: ‘2021-01-01 00:00:00’

convert_datetime_to_milliseconds(dt: datetime, timezoned: str = None) → float[source]¶

Converts a datetime to milliseconds. If timezoned, assumes the datetime is in that timezone.

Parameters:

dt – A datetime object.
timezoned – A timezone like ‘Europe/Madrid’

Returns:

A Unix timestamp in milliseconds.

convert_string_to_milliseconds(ts: str, timezoned: str = None) → int[source]¶

Converts a string to milliseconds.

Parameters:

ts – A string with a date and time. Example: ‘2021-01-01 00:00:00’
timezoned – A timezone like ‘Europe/Madrid’

Returns:

Returns a timestamp in milliseconds.

convert_milliseconds_to_utc_string(ms: int) → str[source]¶

Converts a timestamp in milliseconds to a UTC string.

Parameters:: ms – A timestamp in milliseconds.
Returns:: A string with a date and time.

convert_milliseconds_to_time_zone_datetime(ms: int, timezoned: str = None) → datetime[source]¶

Converts a timestamp in milliseconds to a timezone-aware datetime.

Parameters:

ms – A timestamp in milliseconds.
timezoned – A timezone like ‘Europe/Madrid’

Returns:

A datetime object.

convert_milliseconds_to_str(ms: int, timezoned: str) → str[source]¶

Converts a timestamp in milliseconds to a timezone-aware string.

Parameters:

ms – A timestamp in milliseconds.
timezoned – A timezone like ‘Europe/Madrid’

Returns:

A string with a date and time.

convert_string_to_datetime(ts: str, timezoned: str = None) → datetime[source]¶

Converts a string to datetime. If timezoned, localizes the result.

Parameters:

ts – A string with a date and time. Example: ‘2021-01-01 00:00:00’
timezoned – A timezone like ‘Europe/Madrid’

Returns:

Returns a datetime object.

check_tick_interval(tick_interval: str) → str[source]¶

Checks if argument is a Binance valid tick interval for candles.

Parameters:: tick_interval (str) – A string, maybe, binance tick interval well formatted.
Returns:: A string with the tick interval.

open_from_milliseconds(ms: int, tick_interval: str) → int[source]¶

Returns the open timestamp in milliseconds for a tick interval.

Parameters:

ms – A timestamp in milliseconds.
tick_interval – A tick interval like ‘1m’, ‘1h’, etc.

Returns:

Open timestamp in milliseconds.

next_open_by_milliseconds(ms: int, tick_interval: str) → int[source]¶

Calculates the next open timestamp in milliseconds for a tick interval.

Parameters:

ms – A timestamp in milliseconds.
tick_interval – A tick interval like ‘1m’, ‘1h’, etc.

Returns:

Next open timestamp in milliseconds.

infer_frequency_and_set_index(data: DataFrame, timestamp_column: str = 'Open timestamp', timezone: str = None) → DataFrame[source]¶

Infers the frequency of the DataFrame based on the ‘Open timestamp’ column and sets it as the DataFrame index.

Parameters:

data (pd.DataFrame) – Input DataFrame with a column containing timestamps in milliseconds.
timestamp_column (str) – Name of the column containing timestamps. Default is ‘Open timestamp’.
timezone (str) – The timezone to use. Default is None to infer from the dataframe.

Return pd.DataFrame:

DataFrame with the timestamp column set as the index and the frequency inferred.

get_dataframe_time_index_ranges(data: DataFrame, interval='30T') → list[tuple][source]¶

Divides a DataFrame into time ranges of a specified interval.

Parameters:

data (pd.DataFrame) – A dataframe with a datetime index.
interval – Interval expressed as a Pandas frequency string. Default is ‘30T’.

Return list:

A list of tuples containing the start and end time of each interval.

remove_initial_included_ranges(time_ranges, initial_minutes) → list[tuple][source]¶

Remove the time ranges that are completely included in the initial period.

Parameters:

time_ranges – A list of tuples containing the start and end time of each interval.
initial_minutes – A quantity of minutes that defines the initial period.

Returns:

Filtered list of tuples.