Skip to content

quando

Navigate trading calendars, business days, and market periods — with zero fuss.

PyPI Python License CI Docs

pip install quando

Features

  • 52 methods, one import

    Conversions, timezone, validation, day checks, navigation, ranges, period boundaries, settlement, and expiry — all under import quando as q.

    API Reference

  • Auto-detecting inputs

    Pass a string, datetime, date, Unix epoch, or Excel West serial — quando figures it out. No manual parsing.

  • 8 exchange calendars

    NYSE, EUREX, LSE, TSX, ASX, HKEX, JPX, CME — or any exchange-calendars code. Switch with a single q.use() call.

  • Custom holidays

    Add or remove holidays, persist overrides to JSON, and load them back in any session. Merged transparently at query time.

  • Rebalancing triggers

    is_month_end(), is_quarter_end(), is_year_end() — drop-in conditions for backtest rebalancing logic.

  • Settlement & expiry

    T+N conventions, COB roll-back, and monthly/quarterly/weekly expiry dates for derivatives workflows.

Quick start

import quando as q

q.use("NYSE")  # set global calendar (default: NYSE)

q.is_business_day("2024-01-15")   # False — MLK Day
q.is_holiday("2024-01-15")        # True
q.is_weekend("2024-01-13")        # True
q.day_of_week("2024-01-15")       # "Monday"

import quando as q

q.next_business_day("2024-12-24")       # Dec 26 (Christmas skip)
q.prev_business_day("2024-01-01")       # Dec 29, 2023
q.add_business_days("2024-01-10", 5)    # Jan 17
q.snap("2024-01-13", "forward")         # Jan 16 (weekend + MLK)

import quando as q

q.start_of_month("2024-09-15")     # Sep 3 (Sep 1 Sunday, Sep 2 Labor Day)
q.end_of_quarter("2024-01-15")     # Mar 28 (Mar 31 Sunday, Mar 29 Good Friday)
q.end_of_year("2024-06-01")        # Dec 31

# Rebalancing trigger
if q.is_month_end("2024-01-31"):
    print("rebalance!")            # prints — Jan 31 is last NYSE trading day

import quando as q

q.to_settlement_date("2024-06-10", "T+2")      # Jun 12
q.to_cob("2024-01-13")                         # Jan 12 (weekend → roll back)
q.next_expiry("2024-01-01", "monthly")          # Jan 19 (third Friday)
q.days_to_expiry("2024-01-10", "2024-01-19")   # 6 business days

import quando as q

q.use("NYSE")
q.add_holiday("2024-07-05", "Independence Day (observed)")

# Persist to JSON
q.save_calendar("my_calendar.json")

# Load it back in another session
q.load_calendar("my_calendar.json")

Supported calendars

Alias Exchange Timezone
NYSE New York Stock Exchange America/New_York
EUREX Eurex Europe/Berlin
LSE London Stock Exchange Europe/London
TSX Toronto Stock Exchange America/Toronto
ASX Australian Securities Exchange Australia/Sydney
HKEX Hong Kong Exchanges Asia/Hong_Kong
JPX Japan Exchange Group Asia/Tokyo
CME Chicago Mercantile Exchange America/Chicago

Any exchange-calendars exchange code (e.g. "XLON", "XEUR") also works directly.