exchange_calendars is a Python library with securities exchange calendars
Project description
exchange_calendars
A Python library for defining and querying calendars for security exchanges.
Calendars for more than 50 exchanges available out-the-box! If you still can't find the calendar you're looking for, create a new one!
What's new in 3.4? (October 2021)
Quite a bit! (Please offer any feedback at the 3.4 discussion)
- Tutorials. Five of them!
- New calendar methods #71 (see calendar_methods.ipynb for usage), including:
- trading_index (tutorial trading_index.ipynb)
- is_trading_minute
- is_break_minute
- minute_offset
- session_offset
- minute_offset_by_sessions
- Calendar's now have a
sideparameter to determine which of the open, close, break-start and break-end minutes are treated as trading minutes #71. - 24 hour calendars are now truly 24 hours (open/close times are no longer one minute later/earlier than the actual open/close) #71.
- Some calendar methods have been renamed to improve consistency (table of changes here) #85. The previous names will continue to be available until version 4.0. NOTE: Some newly named methods have also made changes to parameter names, for example from
session_labeltosessionand fromstart_session_labeltostart. - Under-the-bonnet work has sped up many methods.
- A test suite overhaul (#71, #92, #96) has made it simpler to define and test calendars.
Installation
$ pip install exchange_calendars
Quick Start
import exchange_calendars as xcals
Get a list of available calendars:
>>> xcals.get_calendar_names(include_aliases=False)[5:10]
['CMES', 'IEPA', 'XAMS', 'XASX', 'XBKK']
Get a calendar:
>>> xnys = xcals.get_calendar("XNYS") # New York Stock Exchange
>>> xhkg = xcals.get_calendar(
"XHKG",
start="2018-01",
end="2021-12-31",
side="left"
) # Hong Kong Stock Exchange
Query the schedule:
>>> xhkg.schedule.loc["2020-12-29":"2021-01-05"]
| market_open | break_start | break_end | market_close | |
|---|---|---|---|---|
| 2020-12-29 00:00:00+00:00 | 2020-12-29 01:30:00 | 2020-12-29 04:00:00 | 2020-12-29 05:00:00 | 2020-12-29 08:00:00 |
| 2020-12-30 00:00:00+00:00 | 2020-12-30 01:30:00 | 2020-12-30 04:00:00 | 2020-12-30 05:00:00 | 2020-12-30 08:00:00 |
| 2020-12-31 00:00:00+00:00 | 2020-12-31 01:30:00 | NaT | NaT | 2020-12-31 04:00:00 |
| 2021-01-04 00:00:00+00:00 | 2021-01-04 01:30:00 | 2021-01-04 04:00:00 | 2021-01-04 05:00:00 | 2021-01-04 08:00:00 |
| 2021-01-05 00:00:00+00:00 | 2021-01-05 01:30:00 | 2021-01-05 04:00:00 | 2021-01-05 05:00:00 | 2021-01-05 08:00:00 |
Working with sessions
>>> xnys.is_session("2020-01-01")
False
>>> xnys.sessions_in_range("2021-01-01", "2021-01-11")
DatetimeIndex(['2021-01-04 00:00:00+00:00', '2021-01-05 00:00:00+00:00',
'2021-01-06 00:00:00+00:00', '2021-01-07 00:00:00+00:00',
'2021-01-08 00:00:00+00:00', '2021-01-11 00:00:00+00:00'],
dtype='datetime64[ns, UTC]', freq='C')
>>> xnys.sessions_window("2021-01-04", 7)
DatetimeIndex(['2021-01-04 00:00:00+00:00', '2021-01-05 00:00:00+00:00',
'2021-01-06 00:00:00+00:00', '2021-01-07 00:00:00+00:00',
'2021-01-08 00:00:00+00:00', '2021-01-11 00:00:00+00:00',
'2021-01-12 00:00:00+00:00', '2021-01-13 00:00:00+00:00'],
dtype='datetime64[ns, UTC]', freq='C')
>>> xnys.date_to_session_("2021-01-01", direction="next")
Timestamp('2021-01-04 00:00:00+0000', tz='UTC', freq='C')
>>> xnys.previous_session("2021-01-11")
Timestamp('2021-01-08 00:00:00+0000', tz='UTC', freq='C')
>>> xhkg.trading_index(
... "2020-12-30",
... "2020-12-31",
... period="90T",
... force_close=True,
... force_break_close=True
... )
IntervalIndex([[2020-12-30 01:30:00, 2020-12-30 03:00:00), [2020-12-30 03:00:00, 2020-12-30 04:00:00), [2020-12-30 05:00:00, 2020-12-30 06:30:00), [2020-12-30 06:30:00, 2020-12-30 08:00:00), [2020-12-31 01:30:00, 2020-12-31 03:00:00), [2020-12-31 03:00:00, 2020-12-31 04:00:00)],
closed='left',
dtype='interval[datetime64[ns, UTC]]')
See the sessions tutorial for a deeper dive into sessions.
Working with minutes
>>> xhkg.session_minutes("2021-01-04")
DatetimeIndex(['2021-01-04 01:30:00+00:00', '2021-01-04 01:31:00+00:00',
'2021-01-04 01:32:00+00:00', '2021-01-04 01:33:00+00:00',
'2021-01-04 01:34:00+00:00', '2021-01-04 01:35:00+00:00',
'2021-01-04 01:36:00+00:00', '2021-01-04 01:37:00+00:00',
'2021-01-04 01:38:00+00:00', '2021-01-04 01:39:00+00:00',
...
'2021-01-04 07:50:00+00:00', '2021-01-04 07:51:00+00:00',
'2021-01-04 07:52:00+00:00', '2021-01-04 07:53:00+00:00',
'2021-01-04 07:54:00+00:00', '2021-01-04 07:55:00+00:00',
'2021-01-04 07:56:00+00:00', '2021-01-04 07:57:00+00:00',
'2021-01-04 07:58:00+00:00', '2021-01-04 07:59:00+00:00'],
dtype='datetime64[ns, UTC]', length=330, freq=None)
>>> mins = [ "2021-01-04 " + tm for tm in ["01:29", "01:30", "04:20", "07:59", "08:00"] ]
>>> [ xhkg.is_trading_minute(minute) for minute in mins ]
[False, True, False, True, False]
>>> xhkg.is_break_minute("2021-01-04 04:20")
True
>>> xhkg.previous_close("2021-01-04 21:10")
Timestamp('2021-01-04 08:00:00+0000', tz='UTC')
>>> xhkg.previous_minute("2021-01-04 21:10")
Timestamp('2021-01-04 07:59:00+0000', tz='UTC')
Check out the minutes tutorial for a deeper dive that includes an explanation of the concept of 'minutes' and how the "side" option determines which minutes are treated as trading minutes.
Tutorials
sessions.ipynb - all things sessions.
minutes.ipynb - all things minutes. Don't miss this one!
calendar_properties.ipynb - a walk through the schedule and all other calendar properties.
calendar_methods.ipynb - a walk through all the methods available to interrogate a calendar.
trading_index.ipynb - a method that warrants a tutorial all of its own.
Hopefully you'll find that exchange_calendars has the method you need to get the information you want. If it doesn't, either PR it or raise an issue and let us know!
Command Line Usage
Print a unix-cal like calendar straight from the command line (holidays are indicated by brackets)...
ecal XNYS 2020
2020
January February March
Su Mo Tu We Th Fr Sa Su Mo Tu We Th Fr Sa Su Mo Tu We Th Fr Sa
[ 1] 2 3 [ 4] [ 1]
[ 5] 6 7 8 9 10 [11] [ 2] 3 4 5 6 7 [ 8] [ 1] 2 3 4 5 6 [ 7]
[12] 13 14 15 16 17 [18] [ 9] 10 11 12 13 14 [15] [ 8] 9 10 11 12 13 [14]
[19][20] 21 22 23 24 [25] [16][17] 18 19 20 21 [22] [15] 16 17 18 19 20 [21]
[26] 27 28 29 30 31 [23] 24 25 26 27 28 [29] [22] 23 24 25 26 27 [28]
[29] 30 31
April May June
Su Mo Tu We Th Fr Sa Su Mo Tu We Th Fr Sa Su Mo Tu We Th Fr Sa
1 2 3 [ 4] 1 [ 2] 1 2 3 4 5 [ 6]
[ 5] 6 7 8 9 [10][11] [ 3] 4 5 6 7 8 [ 9] [ 7] 8 9 10 11 12 [13]
[12] 13 14 15 16 17 [18] [10] 11 12 13 14 15 [16] [14] 15 16 17 18 19 [20]
[19] 20 21 22 23 24 [25] [17] 18 19 20 21 22 [23] [21] 22 23 24 25 26 [27]
[26] 27 28 29 30 [24][25] 26 27 28 29 [30] [28] 29 30
[31]
July August September
Su Mo Tu We Th Fr Sa Su Mo Tu We Th Fr Sa Su Mo Tu We Th Fr Sa
1 2 [ 3][ 4] [ 1] 1 2 3 4 [ 5]
[ 5] 6 7 8 9 10 [11] [ 2] 3 4 5 6 7 [ 8] [ 6][ 7] 8 9 10 11 [12]
[12] 13 14 15 16 17 [18] [ 9] 10 11 12 13 14 [15] [13] 14 15 16 17 18 [19]
[19] 20 21 22 23 24 [25] [16] 17 18 19 20 21 [22] [20] 21 22 23 24 25 [26]
[26] 27 28 29 30 31 [23] 24 25 26 27 28 [29] [27] 28 29 30
[30] 31
October November December
Su Mo Tu We Th Fr Sa Su Mo Tu We Th Fr Sa Su Mo Tu We Th Fr Sa
1 2 [ 3] 1 2 3 4 [ 5]
[ 4] 5 6 7 8 9 [10] [ 1] 2 3 4 5 6 [ 7] [ 6] 7 8 9 10 11 [12]
[11] 12 13 14 15 16 [17] [ 8] 9 10 11 12 13 [14] [13] 14 15 16 17 18 [19]
[18] 19 20 21 22 23 [24] [15] 16 17 18 19 20 [21] [20] 21 22 23 24 [25][26]
[25] 26 27 28 29 30 [31] [22] 23 24 25 [26] 27 [28] [27] 28 29 30 31
[29] 30
ecal XNYS 1 2020
January 2020
Su Mo Tu We Th Fr Sa
[ 1] 2 3 [ 4]
[ 5] 6 7 8 9 10 [11]
[12] 13 14 15 16 17 [18]
[19][20] 21 22 23 24 [25]
[26] 27 28 29 30 31
Methods renamed in version 3.4
| Previous Name | New Name |
|---|---|
| previous_session_label | previous_session |
| next_session_label | next_session |
| date_to_session_label | date_to_session |
| minute_to_session_label | minute_to_session |
| open_and_close_for_session | session_open_close |
| break_start_and_end_for_session | session_break_start_end |
| minutes_for_session | session_minutes |
| minute_index_to_session_labels | minutes_to_sessions |
| all_sessions | sessions |
| all_minutes | minutes |
| all_minutes_nanos | minutes_nanos |
| first_trading_minute | first_minute |
| last_trading_minute | last_minute |
| first_trading_session | first_session |
| last_trading_session | last_session |
| has_breaks | sessions_has_break |
| market_opens_nanos | opens_nanos |
| market_closes_nanos | closes_nanos |
| market_break_starts_nanos | break_starts_nanos |
| market_break_ends_nanos | break_ends_nanos |
What to expect in 4.0? (February/March 2022)
Major anticipated changes in 4.0 include the following (see the path to 4.0 for a fuller list):
- Changes to the timezone of returned sessions and times (these changes are not yet set in stone - please have your say here).
- Schedule times to change from tz-naive to "UTC".
- Sessions to change from "UTC" to tz-naive.
- Renaming of some methods and method parameters to provide consistency across the package.
- Minimum supported Python version to advance from 3.7 to 3.8.
- For those methods renamed in 3.4, the previous method names will be removed.
Frequently Asked Questions
How can I create a new calendar?
First off, make sure the calendar you're after hasn't already been defined; exchange calendars comes with over 50 pre-defined calendars, including major security exchanges.
If you can't find what you're after, a custom calendar can be created as a subclass of ExchangeCalendar. This workflow describes the process to add a new calendar to exchange_calendars. Just follow the relevant parts.
To access the new calendar via get_calendar call either xcals.register_calendar or xcals.register_calendar_type to register, respectively, a specific calendar instance or a calendar factory (i.e. the subclass).
Can I contribute a new calendar to exchange calendars?
Yes please! The workflow can be found here.
<calendar> is missing a holiday, has a wrong time, should have a break etc...
All of the exchange calendars are maintained by user contributions. If a calendar you care about needs revising, please open a PR - that's how this thing works!
You'll find the workflow to modify an existing calendar here.
What times are considered open and closed?
exchange_calendars attempts to be broadly useful by considering an exchange to be open only during periods of regular trading. During any pre-trading, post-trading or auction period the exchange is treated as closed. An exchange is also treated as closed during any observed lunch break.
See the minutes tutorial for a detailed explanation of which minutes an exchange is considered open over. If you previously used trading_calendars, or exchange_calendars prior to release 3.4, then this is the place to look for answers to questions of how the definition of trading minutes has changed over time (and is now stable and flexible!).
Calendars
| Exchange | ISO Code | Country | Version Added | Exchange Website (English) |
|---|---|---|---|---|
| New York Stock Exchange | XNYS | USA | 1.0 | https://www.nyse.com/index |
| CBOE Futures | XCBF | USA | 1.0 | https://markets.cboe.com/us/futures/overview/ |
| Chicago Mercantile Exchange | CMES | USA | 1.0 | https://www.cmegroup.com/ |
| ICE US | IEPA | USA | 1.0 | https://www.theice.com/index |
| Toronto Stock Exchange | XTSE | Canada | 1.0 | https://www.tsx.com/ |
| BMF Bovespa | BVMF | Brazil | 1.0 | http://www.b3.com.br/en_us/ |
| London Stock Exchange | XLON | England | 1.0 | https://www.londonstockexchange.com/ |
| Euronext Amsterdam | XAMS | Netherlands | 1.2 | https://www.euronext.com/en/regulation/amsterdam |
| Euronext Brussels | XBRU | Belgium | 1.2 | https://www.euronext.com/en/regulation/brussels |
| Euronext Lisbon | XLIS | Portugal | 1.2 | https://www.euronext.com/en/regulation/lisbon |
| Euronext Paris | XPAR | France | 1.2 | https://www.euronext.com/en/regulation/paris |
| Frankfurt Stock Exchange | XFRA | Germany | 1.2 | http://en.boerse-frankfurt.de/ |
| SIX Swiss Exchange | XSWX | Switzerland | 1.2 | https://www.six-group.com/en/home.html |
| Tokyo Stock Exchange | XTKS | Japan | 1.2 | https://www.jpx.co.jp/english/ |
| Austrialian Securities Exchange | XASX | Australia | 1.3 | https://www.asx.com.au/ |
| Bolsa de Madrid | XMAD | Spain | 1.3 | https://www.bolsamadrid.es |
| Borsa Italiana | XMIL | Italy | 1.3 | https://www.borsaitaliana.it |
| New Zealand Exchange | XNZE | New Zealand | 1.3 | https://www.nzx.com/ |
| Wiener Borse | XWBO | Austria | 1.3 | https://www.wienerborse.at/en/ |
| Hong Kong Stock Exchange | XHKG | Hong Kong | 1.3 | https://www.hkex.com.hk/?sc_lang=en |
| Copenhagen Stock Exchange | XCSE | Denmark | 1.4 | http://www.nasdaqomxnordic.com/ |
| Helsinki Stock Exchange | XHEL | Finland | 1.4 | http://www.nasdaqomxnordic.com/ |
| Stockholm Stock Exchange | XSTO | Sweden | 1.4 | http://www.nasdaqomxnordic.com/ |
| Oslo Stock Exchange | XOSL | Norway | 1.4 | https://www.oslobors.no/ob_eng/ |
| Irish Stock Exchange | XDUB | Ireland | 1.4 | http://www.ise.ie/ |
| Bombay Stock Exchange | XBOM | India | 1.5 | https://www.bseindia.com |
| Singapore Exchange | XSES | Singapore | 1.5 | https://www.sgx.com |
| Shanghai Stock Exchange | XSHG | China | 1.5 | http://english.sse.com.cn |
| Korea Exchange | XKRX | South Korea | 1.6 | http://global.krx.co.kr |
| Iceland Stock Exchange | XICE | Iceland | 1.7 | http://www.nasdaqomxnordic.com/ |
| Poland Stock Exchange | XWAR | Poland | 1.9 | http://www.gpw.pl |
| Santiago Stock Exchange | XSGO | Chile | 1.9 | https://www.bolsadesantiago.com/ |
| Colombia Securities Exchange | XBOG | Colombia | 1.9 | https://www.bvc.com.co/nueva/https://www.bvc.com.co/nueva/ |
| Mexican Stock Exchange | XMEX | Mexico | 1.9 | https://www.bmv.com.mx |
| Lima Stock Exchange | XLIM | Peru | 1.9 | https://www.bvl.com.pe |
| Prague Stock Exchange | XPRA | Czech Republic | 1.9 | https://www.pse.cz/en/ |
| Budapest Stock Exchange | XBUD | Hungary | 1.10 | https://bse.hu/ |
| Athens Stock Exchange | ASEX | Greece | 1.10 | http://www.helex.gr/ |
| Istanbul Stock Exchange | XIST | Turkey | 1.10 | https://www.borsaistanbul.com/en/ |
| Johannesburg Stock Exchange | XJSE | South Africa | 1.10 | https://www.jse.co.za/z |
| Malaysia Stock Exchange | XKLS | Malaysia | 1.11 | http://www.bursamalaysia.com/market/ |
| Moscow Exchange | XMOS | Russia | 1.11 | https://www.moex.com/en/ |
| Philippine Stock Exchange | XPHS | Philippines | 1.11 | https://www.pse.com.ph/ |
| Stock Exchange of Thailand | XBKK | Thailand | 1.11 | https://www.set.or.th/set/mainpage.do?language=en&country=US |
| Indonesia Stock Exchange | XIDX | Indonesia | 1.11 | https://www.idx.co.id/ |
| Taiwan Stock Exchange Corp. | XTAI | Taiwan | 1.11 | https://www.twse.com.tw/en/ |
| Buenos Aires Stock Exchange | XBUE | Argentina | 1.11 | https://www.bcba.sba.com.ar/ |
| Pakistan Stock Exchange | XKAR | Pakistan | 1.11 | https://www.psx.com.pk/ |
| Xetra | XETR | Germany | 2.1 | https://www.xetra.com/ |
| Tel Aviv Stock Exchange | XTAE | Israel | 2.1 | https://www.tase.co.il/ |
| Astana International Exchange | AIXK | Kazakhstan | 3.2 | https://www.aix.kz/ |
| Bucharest Stock Exchange | XBSE | Romania | 3.2 | https://www.bvb.ro/ |
Note that exchange calendars are defined by their ISO-10383 market identifier code.
Release history Release notifications | RSS feed
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
