pandas-market-calendars

Warnings

• breaking As of version 5.0.0, the minimum required Python version has been raised to 3.10. Users on Python 3.9 or older must upgrade their Python environment.
  Fix: Upgrade your Python installation to version 3.10 or newer. For example, using `pyenv` or your system's package manager.
• gotcha Calendar accuracy for specific dates and markets can sometimes be an issue. GitHub issues indicate instances where holidays, early closes, or regular market times for certain exchanges (e.g., NYSE, EUREX, CME) might be incorrect or require updates. Users should verify critical dates for their specific use case.
  Fix: Always cross-reference calendar data for critical dates with official exchange sources. Report any discrepancies as issues on the project's GitHub page.
• gotcha There's a distinction between `schedule()` and `date_range()`. `schedule()` returns a DataFrame with `market_open` and `market_close` timestamps for valid trading days. `date_range()` takes this schedule and generates a `pd.DatetimeIndex` of all trading minutes/hours/days within that schedule, based on a specified frequency. Confusing their outputs can lead to incorrect time series generation.
  Fix: Understand that `schedule()` defines the boundaries of trading periods, while `date_range()` populates those periods with specific timestamps at a given frequency. Use `schedule()` to get market open/close per day, and `date_range()` to create a detailed time series of trading moments.
• gotcha An open GitHub issue (#301) suggests that importing `pandas_market_calendars` might subtly alter the behavior of the `pandas` library. While the exact impact isn't fully detailed in public search results, it indicates a potential side effect.
  Fix: Be aware of this potential interaction, especially when using complex pandas operations alongside `pandas-market-calendars`. If unexpected behavior is observed in pandas, try isolating the `pandas-market-calendars` import to confirm if it's the cause.

Install

• pip install pandas-market-calendars pip
• conda install -c conda-forge pandas-market-calendars conda

Imports

• mcal

  import pandas_market_calendars as mcal

  The convention is to import the package and alias it as 'mcal' for brevity and consistency.

Quickstart

This quickstart demonstrates how to list available calendars, get a specific market calendar (NYSE), retrieve its trading schedule for a date range, and then use that schedule to generate a DatetimeIndex of trading days. It also shows how to query specific market open/close times for a given date. Dates and times are timezone-aware.

import pandas_market_calendars as mcal
import pandas as pd

# List all available calendars
print("Available calendars:", mcal.get_calendar_names()[:5], "...")

# Create a NYSE calendar instance
nyse = mcal.get_calendar('NYSE')

# Get the market schedule for a date range
start_date = '2023-12-20'
end_date = '2024-01-10'
schedule = nyse.schedule(start_date=start_date, end_date=end_date)

print(f"\nNYSE Schedule from {start_date} to {end_date}:")
print(schedule.head())

# Get a DatetimeIndex of valid trading times (e.g., daily frequency)
trading_days = mcal.date_range(schedule, frequency='1D')
print(f"\nFirst 5 trading days in the schedule (1D frequency):")
print(trading_days.head())

# Get specific market times for a date
example_date = pd.Timestamp('2023-12-22', tz='America/New_York')
market_open_time = nyse.market_open_time(example_date)
market_close_time = nyse.market_close_time(example_date)
print(f"\nMarket open on {example_date.date()}: {market_open_time.time()}")
print(f"Market close on {example_date.date()}: {market_close_time.time()}")