Exchange Calendars

Warnings

• breaking Version 4.0 introduced significant breaking changes related to timezone handling and method naming. Schedule times returned by the calendar are now UTC-localized, while sessions are timezone-naive. Numerous methods were renamed for consistency (e.g., `session_label` parameters became `session`). The old method names were deprecated in earlier versions and removed in 4.0.
  Fix: Review the official migration guide for 4.0. Ensure all references to session labels and timezone-aware datetimes are updated. Adapt to UTC-localized times for market open/close and timezone-naive sessions.
• gotcha Some calendars have defined historical `start` and `end` bounds, outside of which the accuracy of the calendar's schedule is not guaranteed. Querying dates outside these specified bounds may yield incorrect or undefined trading sessions/holidays.
  Fix: Always verify the `calendar.default_start` and `calendar.default_end` properties for any calendar instance if querying historical or distant future dates. Be aware that the accuracy beyond these bounds is not guaranteed and may require manual verification or community contributions.
• breaking The library explicitly requires Python >=3.10 and <4.0. Attempting to install or run `exchange-calendars` on unsupported Python versions (e.g., Python 3.9 or older, or Python 4.x when released) will lead to installation failures or runtime errors.
  Fix: Ensure your Python environment meets the `requires_python` specification (`>=3.10, <4`). Upgrade your Python interpreter if necessary.
• gotcha The definition of 'trading minutes' and the behavior of 24-hour calendars (specifically, their open/close times) changed significantly in version 3.4, and the default `side` parameter for calendars was adjusted in v4. Prior to v3.4, 24-hour calendars might have had open/close times one minute later/earlier than the actual market times.
  Fix: If migrating from `trading_calendars` or `exchange_calendars` versions prior to 3.4, carefully review the 'minutes tutorial' in the documentation to understand the current stable definition of trading minutes. Be aware of the `side` parameter (defaulting to 'left' in v4) and its impact on inclusive/exclusive minute ranges.
• gotcha The library typically defines an exchange as 'open' only during regular trading periods, excluding pre-trading, post-trading, auction periods, or observed lunch breaks. This definition might differ from other sources or user expectations.
  Fix: Consult the 'minutes tutorial' in the official documentation for a detailed explanation of how trading minutes are defined and which periods are considered open or closed by the library to align expectations with its functionality.

Install

• pip install exchange-calendars Install stable version

Imports

• exchange_calendars

  import exchange_calendars as xcals

  The library was forked from `trading_calendars`. The `trading_calendars` package is no longer maintained, and `exchange_calendars` is the actively developed successor.
• get_calendar

  xcals.get_calendar('XNYS')

  Used to retrieve a specific exchange calendar by its ISO-10383 market identifier code (MIC).

Quickstart

This quickstart demonstrates how to import the library, list available calendars, retrieve a specific exchange calendar (NYSE in this case), and query its trading schedule for a given date range.

import exchange_calendars as xcals
import pandas as pd

# Get a list of available calendar names
print("Available calendars (first 5):", xcals.get_calendar_names(include_aliases=False)[:5])

# Get the New York Stock Exchange (XNYS) calendar
xnys = xcals.get_calendar("XNYS")

# Query the schedule for a specific date range
start_date = pd.Timestamp("2023-12-28", tz='UTC')
end_date = pd.Timestamp("2024-01-03", tz='UTC')
schedule = xnys.schedule.loc[start_date:end_date]

print("\nNYSE Schedule (2023-12-28 to 2024-01-03):")
print(schedule)