quando

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

quando is a lightweight library for business day arithmetic and market calendar utilities. It auto-detects any date input, resolves holidays via exchange-calendars, and provides 52 methods covering everything from date conversion to settlement dates and rebalancing triggers.

Features

• 52 methods — conversion, timezone, validation, day checks, navigation, ranges, period boundaries, settlement, and expiry
• Auto-detecting inputs — string (ISO, compact, US, slash), datetime, date, int/float (Unix epoch or Excel West serial)
• Exchange calendars — NYSE, EUREX, LSE, TSX, ASX, HKEX, JPX, CME via exchange-calendars; any exchange code works
• Custom holidays — add, remove, and persist overrides to JSON; merged transparently at query time
• Period boundaries — month, quarter, year, and ISO week; always snaps to the nearest business day
• Rebalancing triggers — is_month_end(), is_quarter_end(), is_year_end() for signal and rebalance logic
• Settlement & expiry — T+N conventions, COB roll-back, and monthly/quarterly/weekly expiry dates
• Pluggable calendars — load a custom JSON calendar file and set it as the active default with one call

Installation

pip install quando

Or with uv:

uv add quando

For development:

git clone https://github.com/aexsalomao/quando
cd quando
uv sync --extra dev

Quick Start

import quando as q

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

# Parse anything
q.to_datetime("20240115")             # datetime(2024, 1, 15, tzinfo=UTC)
q.to_datetime(45306)                  # Excel West serial → 2024-01-15
q.to_datetime(1705276800.0)           # Unix epoch

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

# Navigation
q.next_business_day("2024-12-24")     # Dec 26 (Christmas skip)
q.add_business_days("2024-01-10", 5)  # Jan 17
q.snap("2024-01-13", "forward")       # Jan 15... wait, holiday → Jan 16

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

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

# Date ranges & counting
q.date_range("2024-01-01", "2024-01-31")   # list of 21 trading days
q.trading_days_in_year(2024)               # 252
q.business_days_between("2024-01-01", "2024-01-31")  # 21

# Settlement & expiry
q.to_settlement_date("2024-06-10", "T+2")  # Jun 12
q.next_expiry("2024-01-01", "monthly")     # Jan 19 (third Friday)
q.days_to_expiry("2024-01-10", "2024-01-19")  # 6 business days

API

Setup

Conversions

Timezone

Validation & Comparison

Day Checks

Holiday Management

Date Navigation

Date Ranges & Counting

Period Boundaries

All period functions return a UTC-aware datetime that lands on a business day.

Period Boundary Checks

Useful as rebalancing triggers in a backtest loop.

Settlement & Expiry

Reference & I/O

Supported Calendars

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

Custom Calendars

import quando as q

# Add a one-off closure
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")  # also calls q.use() with the saved calendar name

JSON schema:

{
  "name": "NYSE",
  "holidays": [
    {"date": "2024-07-05", "name": "Independence Day (observed)"}
  ]
}

Running Tests

pytest
pytest --cov=quando   # with coverage

License

MIT © Antônio Salomão