pandas_market_calendars package

Submodules

pandas_market_calendars.calendar_registry module

pandas_market_calendars.calendar_registry.get_calendar(name, open_time=None, close_time=None) → MarketCalendar

Retrieves an instance of an MarketCalendar whose name is given.

Parameters:

name – The name of the MarketCalendar to be retrieved.
open_time – Market open time override as datetime.time object. If None then default is used.
close_time – Market close time override as datetime.time object. If None then default is used.

Returns:

MarketCalendar of the desired calendar.

pandas_market_calendars.calendar_registry.get_calendar_names(): All Market Calendar names and aliases that can be used in “factory” :return: list(str)

pandas_market_calendars.calendar_utils module

Utilities to use with market_calendars

pandas_market_calendars.calendar_utils.convert_freq(index, frequency)

Converts a DateTimeIndex to a new lower frequency

Parameters:

index – DateTimeIndex
frequency – frequency string

Returns:

DateTimeIndex

pandas_market_calendars.calendar_utils.merge_schedules(schedules, how='outer')

Given a list of schedules will return a merged schedule. The merge method (how) will either return the superset of any datetime when any schedule is open (outer) or only the datetime where all markets are open (inner)

CAVEATS:

This does not work for schedules with breaks, the break information will be lost.
Only “market_open” and “market_close” are considered, other market times are not yet supported.

Parameters:

schedules – list of schedules
how – outer or inner

Returns:

schedule DataFrame

pandas_market_calendars.class_registry module

class pandas_market_calendars.class_registry.ProtectedDict(*args, **kwargs)

Bases: dict

copy() → a shallow copy of D

class pandas_market_calendars.class_registry.RegisteryMeta(name, bases, attr)

Bases: type

Metaclass used to register all classes inheriting from RegisteryMeta

pandas_market_calendars.exchange_calendar_asx module

pandas_market_calendars.exchange_calendar_bmf module

pandas_market_calendars.exchange_calendar_cfe module

pandas_market_calendars.exchange_calendar_cme module

pandas_market_calendars.exchange_calendar_eurex module

pandas_market_calendars.exchange_calendar_hkex module

pandas_market_calendars.exchange_calendar_ice module

pandas_market_calendars.exchange_calendar_jpx module

pandas_market_calendars.exchange_calendar_lse module

pandas_market_calendars.exchange_calendar_nyse module

pandas_market_calendars.exchange_calendar_ose module

pandas_market_calendars.exchange_calendar_six module

pandas_market_calendars.exchange_calendar_sse module

pandas_market_calendars.exchange_calendar_tase module

pandas_market_calendars.exchange_calendar_tsx module

pandas_market_calendars.exchange_calendar_xbom module

pandas_market_calendars.holidays_cn module

pandas_market_calendars.holidays_jp module

pandas_market_calendars.holidays_oz module

pandas_market_calendars.holidays_uk module

pandas_market_calendars.holidays_us module

pandas_market_calendars.jpx_equinox module

pandas_market_calendars.market_calendar module

class pandas_market_calendars.market_calendar.DEFAULT: Bases: object

class pandas_market_calendars.market_calendar.MarketCalendar(open_time=None, close_time=None)

Bases: object

An MarketCalendar represents the timing information of a single market or exchange. Unless otherwise noted all times are in UTC and use Pandas data structures.

Parameters:

open_time – Market open time override as datetime.time object. If None then default is used.
close_time – Market close time override as datetime.time object. If None then default is used.

add_time(market_time, times, opens=<class 'pandas_market_calendars.market_calendar.DEFAULT'>)

Adds the specified market time to regular_market_times and makes the necessary adjustments.

Parameters:

market_time – the market_time to add
times – the time information
opens – see .change_time docstring

Returns:

None

property adhoc_holidays

Returns:: list of ad-hoc holidays

property break_end

Break time end. If None then there is no break

Returns:: time or None

break_end_on(date)

property break_start

Break time start. If None then there is no break

Returns:: time or None

break_start_on(date)

classmethod calendar_names(): All Market Calendar names and aliases that can be used in “factory” :return: list(str)

change_time(market_time, times, opens=<class 'pandas_market_calendars.market_calendar.DEFAULT'>)

Changes the specified market time in regular_market_times and makes the necessary adjustments.

Parameters:

market_time – the market_time to change
times – new time information
opens –
whether the market_time is a time that closes or opens the market this is only needed if the market_time should be respected by .open_at_time True: opens False: closes None: consider it neither opening nor closing, don’t add to open_close_map (ignore in .open_at_time) DEFAULT: same as None, unless the market_time is in self.__class__.open_close_map. Then it will take

the default value as defined by the class.

Returns:

None

clean_dates(start_date, end_date)

Strips the inputs of time and time zone information

Parameters:

start_date – start date
end_date – end date

Returns:

(start_date, end_date) with just date, no time and no time zone

property close_offset

Returns:: close offset

property close_time

Default close time for the market

Returns:: time

close_time_on(date)

days_at_time(days, market_time, day_offset=0)

Create an index of days at time t, interpreted in timezone tz. The returned index is localized to UTC.

In the example below, the times switch from 13:45 to 12:45 UTC because March 13th is the daylight savings transition for US/Eastern. All the times are still 8:45 when interpreted in US/Eastern.

>>> import pandas as pd; import datetime; import pprint
>>> dts = pd.date_range('2016-03-12', '2016-03-14')
>>> dts_at_845 = days_at_time(dts, datetime.time(8, 45), 'US/Eastern')
>>> pprint.pprint([str(dt) for dt in dts_at_845])
['2016-03-12 13:45:00+00:00',
 '2016-03-13 12:45:00+00:00',
 '2016-03-14 12:45:00+00:00']

Parameters:

days – DatetimeIndex An index of dates (represented as midnight).
market_time – datetime.time The time to apply as an offset to each day in days.
day_offset – int The number of days we want to offset @days by

Returns:

pd.Series of date with the time requested.

early_closes(schedule)

Get a DataFrame of the dates that are an early close.

Parameters:: schedule – schedule DataFrame
Returns:: schedule DataFrame with rows that are early closes

classmethod factory(name, *args, **kwargs)

Parameters:

cls(RegisteryMeta) – registration meta class
name(str) – name of class that needs to be instantiated
args(Optional(tuple)) – instance positional arguments
kwargs(Optional(dict)) – instance named arguments

Returns:

class instance

get_offset(market_time)

get_special_times(market_time)

get_special_times_adhoc(market_time)

get_time(market_time, all_times=False)

get_time_on(market_time, date)

property has_custom

property has_discontinued

holidays()

Returns the complete CustomBusinessDay object of holidays that can be used in any Pandas function that take that input.

Returns:: CustomBusinessDay object of holidays

property interruptions

This needs to be a list with a tuple for each date that had an interruption. The tuple should have this layout:

(date, start_time, end_time[, start_time2, end_time2, …])

E.g.: [

(“2002-02-03”, (time(11), -1), time(11, 2)), (“2010-01-11”, time(11), (time(11, 1), 1)), (“2010-01-13”, time(9, 59), time(10), time(10, 29), time(10, 30)), (“2011-01-10”, time(11), time(11, 1))

]

The date needs to be a string in this format: ‘yyyy-mm-dd’. Times need to be two datetime.time objects for each interruption, indicating start and end.

Optionally these can be wrapped in a tuple, where the second element needs to be an integer indicating an offset.

On “2010-01-13” in the example, it is shown that there can be multiple interruptions in a day.

property interruptions_df: Will return a pd.DataFrame only containing interruptions.

is_custom(market_time)

is_different(col, diff=None)

is_discontinued(market_time)

is_open_now(schedule, include_close=False, only_rth=False)

To determine if the current local system time (converted to UTC) is an open time for the market

Parameters:

schedule – schedule DataFrame
include_close – if False then the function will return False if the current local system time is equal to the closing timestamp. If True then it will return True if the current local system time is equal to the closing timestamp. Use True if using bars and would like to include the last bar as a valid open date and time.
only_rth – whether to consider columns that are before market_open or after market_close

Returns:

True if the current local system time is a valid open date and time, False if not

late_opens(schedule)

Get a DataFrame of the dates that are an late opens.

Parameters:: schedule – schedule DataFrame
Returns:: schedule DataFrame with rows that are late opens

property market_times

abstract property name

Name of the market

Returns:: string name

open_at_time(schedule, timestamp, include_close=False, only_rth=False)

Determine if a given timestamp is during an open time for the market. If the timestamp is before the first open time or after the last close time of schedule, a ValueError will be raised.

Parameters:

schedule – schedule DataFrame
timestamp – the timestamp to check for. Assumed to be UTC, if it doesn’t include tz information.
include_close – if False then the timestamp that equals the closing timestamp will return False and not be considered a valid open date and time. If True then it will be considered valid and return True. Use True if using bars and would like to include the last bar as a valid open date and time. The close refers to the latest market_time available, which could be after market_close (e.g. ‘post’).
only_rth – whether to ignore columns that are before market_open or after market_close. If true, include_close will be referring to market_close.

Returns:

True if the timestamp is a valid open date and time, False if not

open_close_map = {'break_end': True, 'break_start': False, 'market_close': False, 'market_open': True, 'post': False, 'pre': True}

property open_offset

Returns:: open offset

property open_time

Default open time for the market

Returns:: time

open_time_on(date)

property regular_holidays

Returns:: pd.AbstractHolidayCalendar: a calendar containing the regular holidays for this calendar

regular_market_times = {'market_close': ((None, datetime.time(23, 0)),), 'market_open': ((None, datetime.time(0, 0)),)}

remove_time(market_time)

Removes the specified market time from regular_market_times and makes the necessary adjustments.

Parameters:: market_time – the market_time to remove
Returns:: None

schedule(start_date, end_date, tz='UTC', start='market_open', end='market_close', force_special_times=True, market_times=None, interruptions=False)

Generates the schedule DataFrame. The resulting DataFrame will have all the valid business days as the index and columns for the requested market times. The columns can be determined either by setting a range (inclusive on both sides), using start and end, or by passing a list to `market_times’. A range of market_times is derived from a list of market_times that are available to the instance, which are sorted based on the current regular time. See examples/usage.ipynb for demonstrations.

All time zones are set to UTC by default. Setting the tz parameter will convert the columns to the desired timezone, such as ‘America/New_York’.

Parameters:

start_date – first date of the schedule
end_date – last date of the schedule
tz – timezone that the columns of the returned schedule are in, default: “UTC”
start – the first market_time to include as a column, default: “market_open”
end – the last market_time to include as a column, default: “market_close”
force_special_times –
how to handle special times. True: overwrite regular times of the column itself, conform other columns to special times of

market_open/market_close if those are requested.

False: only overwrite regular times of the column itself, leave others alone None: completely ignore special times
market_times – alternative to start/end, list of market_times that are in self.regular_market_times
interruptions – bool, whether to add interruptions to the schedule, default: False These will be added as columns to the right of the DataFrame. Any interruption on a day between start_date and end_date will be included, regardless of the market_times requested. Also, force_special_times does not take these into consideration.

Returns:

schedule DataFrame

property special_closes

A list of special close times and corresponding HolidayCalendars.

Returns:: List of (time, AbstractHolidayCalendar) tuples

property special_closes_adhoc

Returns:: List of (time, DatetimeIndex) tuples that represent special closes that cannot be codified into rules.

special_dates(market_time, start_date, end_date, filter_holidays=True)

Calculate a datetimeindex that only contains the specail times of the requested market time.

Parameters:

market_time – market_time reference
start_date – first possible date of the index
end_date – last possible date of the index
filter_holidays – will filter days by self.valid_days, which can be useful when debugging

Returns:

schedule DatetimeIndex

property special_market_close

A list of special close times and corresponding HolidayCalendars.

Returns:: List of (time, AbstractHolidayCalendar) tuples

property special_market_close_adhoc

Returns:: List of (time, DatetimeIndex) tuples that represent special closes that cannot be codified into rules.

property special_market_open

A list of special open times and corresponding AbstractHolidayCalendar.

Returns:: List of (time, AbstractHolidayCalendar) tuples

property special_market_open_adhoc

Returns:: List of (time, DatetimeIndex) tuples that represent special opens that cannot be codified into rules.

property special_opens

A list of special open times and corresponding AbstractHolidayCalendar.

Returns:: List of (time, AbstractHolidayCalendar) tuples

property special_opens_adhoc

Returns:: List of (time, DatetimeIndex) tuples that represent special opens that cannot be codified into rules.

abstract property tz

Time zone for the market.

Returns:: timezone

valid_days(start_date, end_date, tz='UTC')

Get a DatetimeIndex of valid open business days.

Parameters:

start_date – start date
end_date – end date
tz – time zone in either string or pytz.timezone

Returns:

DatetimeIndex of valid business days

property weekmask

class pandas_market_calendars.market_calendar.MarketCalendarMeta(name, bases, namespace, /, **kwargs): Bases: ABCMeta, RegisteryMeta

pandas_market_calendars.trading_calendars_mirror module

Module contents

class pandas_market_calendars.MarketCalendar(open_time=None, close_time=None)

Bases: object

An MarketCalendar represents the timing information of a single market or exchange. Unless otherwise noted all times are in UTC and use Pandas data structures.

Parameters:

open_time – Market open time override as datetime.time object. If None then default is used.
close_time – Market close time override as datetime.time object. If None then default is used.

add_time(market_time, times, opens=<class 'pandas_market_calendars.market_calendar.DEFAULT'>)

Adds the specified market time to regular_market_times and makes the necessary adjustments.

Parameters:

market_time – the market_time to add
times – the time information
opens – see .change_time docstring

Returns:

None

property adhoc_holidays

Returns:: list of ad-hoc holidays

property break_end

Break time end. If None then there is no break

Returns:: time or None

break_end_on(date)

property break_start

Break time start. If None then there is no break

Returns:: time or None

break_start_on(date)

classmethod calendar_names(): All Market Calendar names and aliases that can be used in “factory” :return: list(str)

change_time(market_time, times, opens=<class 'pandas_market_calendars.market_calendar.DEFAULT'>)

Changes the specified market time in regular_market_times and makes the necessary adjustments.

Parameters:

market_time – the market_time to change
times – new time information
opens –
whether the market_time is a time that closes or opens the market this is only needed if the market_time should be respected by .open_at_time True: opens False: closes None: consider it neither opening nor closing, don’t add to open_close_map (ignore in .open_at_time) DEFAULT: same as None, unless the market_time is in self.__class__.open_close_map. Then it will take

the default value as defined by the class.

Returns:

None

clean_dates(start_date, end_date)

Strips the inputs of time and time zone information

Parameters:

start_date – start date
end_date – end date

Returns:

(start_date, end_date) with just date, no time and no time zone

property close_offset

Returns:: close offset

property close_time

Default close time for the market

Returns:: time

close_time_on(date)

days_at_time(days, market_time, day_offset=0)

Create an index of days at time t, interpreted in timezone tz. The returned index is localized to UTC.

In the example below, the times switch from 13:45 to 12:45 UTC because March 13th is the daylight savings transition for US/Eastern. All the times are still 8:45 when interpreted in US/Eastern.

>>> import pandas as pd; import datetime; import pprint
>>> dts = pd.date_range('2016-03-12', '2016-03-14')
>>> dts_at_845 = days_at_time(dts, datetime.time(8, 45), 'US/Eastern')
>>> pprint.pprint([str(dt) for dt in dts_at_845])
['2016-03-12 13:45:00+00:00',
 '2016-03-13 12:45:00+00:00',
 '2016-03-14 12:45:00+00:00']

Parameters:

days – DatetimeIndex An index of dates (represented as midnight).
market_time – datetime.time The time to apply as an offset to each day in days.
day_offset – int The number of days we want to offset @days by

Returns:

pd.Series of date with the time requested.

early_closes(schedule)

Get a DataFrame of the dates that are an early close.

Parameters:: schedule – schedule DataFrame
Returns:: schedule DataFrame with rows that are early closes

classmethod factory(name, *args, **kwargs)

Parameters:

cls(RegisteryMeta) – registration meta class
name(str) – name of class that needs to be instantiated
args(Optional(tuple)) – instance positional arguments
kwargs(Optional(dict)) – instance named arguments

Returns:

class instance

get_offset(market_time)

get_special_times(market_time)

get_special_times_adhoc(market_time)

get_time(market_time, all_times=False)

get_time_on(market_time, date)

property has_custom

property has_discontinued

holidays()

Returns the complete CustomBusinessDay object of holidays that can be used in any Pandas function that take that input.

Returns:: CustomBusinessDay object of holidays

property interruptions

This needs to be a list with a tuple for each date that had an interruption. The tuple should have this layout:

(date, start_time, end_time[, start_time2, end_time2, …])

E.g.: [

(“2002-02-03”, (time(11), -1), time(11, 2)), (“2010-01-11”, time(11), (time(11, 1), 1)), (“2010-01-13”, time(9, 59), time(10), time(10, 29), time(10, 30)), (“2011-01-10”, time(11), time(11, 1))

]

The date needs to be a string in this format: ‘yyyy-mm-dd’. Times need to be two datetime.time objects for each interruption, indicating start and end.

Optionally these can be wrapped in a tuple, where the second element needs to be an integer indicating an offset.

On “2010-01-13” in the example, it is shown that there can be multiple interruptions in a day.

property interruptions_df: Will return a pd.DataFrame only containing interruptions.

is_custom(market_time)

is_different(col, diff=None)

is_discontinued(market_time)

is_open_now(schedule, include_close=False, only_rth=False)

To determine if the current local system time (converted to UTC) is an open time for the market

Parameters:

schedule – schedule DataFrame
include_close – if False then the function will return False if the current local system time is equal to the closing timestamp. If True then it will return True if the current local system time is equal to the closing timestamp. Use True if using bars and would like to include the last bar as a valid open date and time.
only_rth – whether to consider columns that are before market_open or after market_close

Returns:

True if the current local system time is a valid open date and time, False if not

late_opens(schedule)

Get a DataFrame of the dates that are an late opens.

Parameters:: schedule – schedule DataFrame
Returns:: schedule DataFrame with rows that are late opens

property market_times

abstract property name

Name of the market

Returns:: string name

open_at_time(schedule, timestamp, include_close=False, only_rth=False)

Determine if a given timestamp is during an open time for the market. If the timestamp is before the first open time or after the last close time of schedule, a ValueError will be raised.

Parameters:

schedule – schedule DataFrame
timestamp – the timestamp to check for. Assumed to be UTC, if it doesn’t include tz information.
include_close – if False then the timestamp that equals the closing timestamp will return False and not be considered a valid open date and time. If True then it will be considered valid and return True. Use True if using bars and would like to include the last bar as a valid open date and time. The close refers to the latest market_time available, which could be after market_close (e.g. ‘post’).
only_rth – whether to ignore columns that are before market_open or after market_close. If true, include_close will be referring to market_close.

Returns:

True if the timestamp is a valid open date and time, False if not

open_close_map = {'break_end': True, 'break_start': False, 'market_close': False, 'market_open': True, 'post': False, 'pre': True}

property open_offset

Returns:: open offset

property open_time

Default open time for the market

Returns:: time

open_time_on(date)

property regular_holidays

Returns:: pd.AbstractHolidayCalendar: a calendar containing the regular holidays for this calendar

regular_market_times = {'market_close': ((None, datetime.time(23, 0)),), 'market_open': ((None, datetime.time(0, 0)),)}

remove_time(market_time)

Removes the specified market time from regular_market_times and makes the necessary adjustments.

Parameters:: market_time – the market_time to remove
Returns:: None

schedule(start_date, end_date, tz='UTC', start='market_open', end='market_close', force_special_times=True, market_times=None, interruptions=False)

Generates the schedule DataFrame. The resulting DataFrame will have all the valid business days as the index and columns for the requested market times. The columns can be determined either by setting a range (inclusive on both sides), using start and end, or by passing a list to `market_times’. A range of market_times is derived from a list of market_times that are available to the instance, which are sorted based on the current regular time. See examples/usage.ipynb for demonstrations.

All time zones are set to UTC by default. Setting the tz parameter will convert the columns to the desired timezone, such as ‘America/New_York’.

Parameters:

start_date – first date of the schedule
end_date – last date of the schedule
tz – timezone that the columns of the returned schedule are in, default: “UTC”
start – the first market_time to include as a column, default: “market_open”
end – the last market_time to include as a column, default: “market_close”
force_special_times –
how to handle special times. True: overwrite regular times of the column itself, conform other columns to special times of

market_open/market_close if those are requested.

False: only overwrite regular times of the column itself, leave others alone None: completely ignore special times
market_times – alternative to start/end, list of market_times that are in self.regular_market_times
interruptions – bool, whether to add interruptions to the schedule, default: False These will be added as columns to the right of the DataFrame. Any interruption on a day between start_date and end_date will be included, regardless of the market_times requested. Also, force_special_times does not take these into consideration.

Returns:

schedule DataFrame

property special_closes

A list of special close times and corresponding HolidayCalendars.

Returns:: List of (time, AbstractHolidayCalendar) tuples

property special_closes_adhoc

Returns:: List of (time, DatetimeIndex) tuples that represent special closes that cannot be codified into rules.

special_dates(market_time, start_date, end_date, filter_holidays=True)

Calculate a datetimeindex that only contains the specail times of the requested market time.

Parameters:

market_time – market_time reference
start_date – first possible date of the index
end_date – last possible date of the index
filter_holidays – will filter days by self.valid_days, which can be useful when debugging

Returns:

schedule DatetimeIndex

property special_market_close

A list of special close times and corresponding HolidayCalendars.

Returns:: List of (time, AbstractHolidayCalendar) tuples

property special_market_close_adhoc

Returns:: List of (time, DatetimeIndex) tuples that represent special closes that cannot be codified into rules.

property special_market_open

A list of special open times and corresponding AbstractHolidayCalendar.

Returns:: List of (time, AbstractHolidayCalendar) tuples

property special_market_open_adhoc

Returns:: List of (time, DatetimeIndex) tuples that represent special opens that cannot be codified into rules.

property special_opens

A list of special open times and corresponding AbstractHolidayCalendar.

Returns:: List of (time, AbstractHolidayCalendar) tuples

property special_opens_adhoc

Returns:: List of (time, DatetimeIndex) tuples that represent special opens that cannot be codified into rules.

abstract property tz

Time zone for the market.

Returns:: timezone

valid_days(start_date, end_date, tz='UTC')

Get a DatetimeIndex of valid open business days.

Parameters:

start_date – start date
end_date – end date
tz – time zone in either string or pytz.timezone

Returns:

DatetimeIndex of valid business days

property weekmask

pandas_market_calendars.convert_freq(index, frequency)

Converts a DateTimeIndex to a new lower frequency

Parameters:

index – DateTimeIndex
frequency – frequency string

Returns:

DateTimeIndex

pandas_market_calendars.get_calendar(name, open_time=None, close_time=None) → MarketCalendar

Retrieves an instance of an MarketCalendar whose name is given.

Parameters:

name – The name of the MarketCalendar to be retrieved.
open_time – Market open time override as datetime.time object. If None then default is used.
close_time – Market close time override as datetime.time object. If None then default is used.

Returns:

MarketCalendar of the desired calendar.

pandas_market_calendars.get_calendar_names(): All Market Calendar names and aliases that can be used in “factory” :return: list(str)

pandas_market_calendars.merge_schedules(schedules, how='outer')

Given a list of schedules will return a merged schedule. The merge method (how) will either return the superset of any datetime when any schedule is open (outer) or only the datetime where all markets are open (inner)

CAVEATS:

This does not work for schedules with breaks, the break information will be lost.
Only “market_open” and “market_close” are considered, other market times are not yet supported.

Parameters:

schedules – list of schedules
how – outer or inner

Returns:

schedule DataFrame