$ show rsheftel/pandas_market_calendars
pandas_market_calendars is a Python library that provides market and exchange trading calendars for over 50 global financial exchanges, including equities, futures, and OTC markets. It generates accurate trading schedules (open/close times, holidays, early closes, late opens, and breaks) as pandas DatetimeIndex objects, enabling developers and quantitative analysts to align time series data, backtest strategies, and check market status. The library is a fork of Quantopian/Zipline's exchange_calendars module, extended with additional calendars, utility functions, and source documentation. Architecturally, the library uses a base MarketCalendar class with a metaclass-based registry pattern that automatically registers all calendar subclasses by name and alias. Individual exchange calendars (e.g., NYSE, CME, LSE, JPX) are implemented as subclasses in the `calendars/` directory, with holiday rules defined in separate `holidays/` modules. Market times are stored in a ProtectedDict (immutable dictionary) to prevent accidental modification. The library also provides a mirror module that wraps calendars from the external `exchange_calendars` package, ensuring backward compatibility. Key entry points include `get_calendar()` to retrieve a calendar instance, `date_range()` to generate intraday timestamps, `merge_schedules()` to combine multiple exchange schedules, and `mark_session()` to classify timestamps into pre-market, regular, and post-market sessions. The library depends on pandas for data structures and timezone handling via zoneinfo, and optionally on exchange-calendars for mirrored calendars. It is designed for production use with extensive test coverage, CI/CD pipelines, and semantic versioning. The library's primary data flow is static: holiday rules and market time definitions are hardcoded in Python code and updated via new releases. There is no runtime data fetching, which ensures reproducibility but requires manual updates when exchanges change their calendars. The changelog shows frequent updates for holiday corrections and new exchange support, indicating active maintenance.
The LLM identified 4 files worth highlighting for reuse:
Contains `ProtectedDict`, an immutable dictionary that enforces modification only through explicit methods (`change_time`, `add_time`, `remove_time`), preventing accidental mutation of market time configurations. Also contains `RegistryMeta`, a metaclass that automatically registers all `MarketCalendar` subclasses by name and alias, providing a `factory()` classmethod for instantiation. Both patterns are reusable in any library requiring immutable configuration or automatic subclass discovery.
Defines the `MarketCalendar` base class with core methods like `schedule()`, `valid_days()`, `days_at_time()`, and `_special_dates()`. Includes a custom `HolidayCalendar` subclass of `AbstractHolidayCalendar` that bounds `start_date` and `end_date` to avoid polluting the global holiday calendar registry—a best practice for library code. The `days_at_time()` method efficiently applies time offsets to date indices, and `_convert()` handles timezone-aware datetime conversion. This module is the foundation for all exchange calendars and demonstrates clean separation of concerns.
Provides standalone utility functions: `date_range()` for generating intraday timestamps with support for multiple session types (RTH, ETH, pre, post, break, closed), `merge_schedules()` for combining schedules from multiple exchanges, `mark_session()` for labeling timestamps by session, and `convert_freq()` for frequency conversion. These functions operate on pandas DataFrames and are reusable for any time series alignment or schedule manipulation task, independent of the specific exchange calendars.
Implements a mirror adapter that wraps calendars from the external `exchange_calendars` package, converting their weekmask format and lazily initializing the underlying calendar. This pattern allows the library to support calendars from a different package without tight coupling, and demonstrates a clean adapter pattern for integrating external dependencies. The `_FINALIZE_TRADING_CALENDAR` class attribute ensures one-time initialization, though this may have edge cases with subclassing.