Exchange calendars and trading hours for the world's markets, from the
Diurn API, with an
exchange_calendars-style
interface.
pip install diurn # the client and diurn.py: standard library only
pip install 'diurn[pd]' # the Pandas flavor, also diurn.get_calendar
pip install 'diurn[sf]' # the StaticFrame flavor
Nothing imports Pandas, StaticFrame, or NumPy until its flavor is used.
An API key is free at https://diurn.io/signin/; set DIURN_API_KEY.
import diurn
xnys = diurn.get_calendar('XNYS')
xnys.is_session('2026-11-26') # False: Thanksgiving
xnys.next_session('2026-11-25') # Timestamp('2026-11-27 00:00:00')
xnys.sessions_in_range('2026-11-01', '2026-11-30') # DatetimeIndex
xnys.is_open_at_time('2026-11-27T18:30:00Z') # False: an early close at 13:00
xnys.next_close('2026-11-27T15:00:00Z') # Timestamp('2026-11-27 13:00:00-0500', tz='America/New_York')
xnys.schedule('2026-11-01', '2026-11-30') # open, break_start, break_end, close, kind, verification, reason
Three flavors, one calendar
The same calendar, with the same methods, in three sets of types:
|
session |
range of sessions |
schedule |
instants |
diurn / diurn.pd (diurn[pd]) |
pd.Timestamp |
pd.DatetimeIndex |
pd.DataFrame |
aware pd.Timestamp, venue's zone |
diurn.sf (diurn[sf]) |
np.datetime64[D] |
sf.IndexDate |
sf.Frame |
np.datetime64[s], UTC |
diurn.py |
datetime.date |
list[date] |
list[ScheduleRow] |
aware datetime, venue's zone |
import diurn.sf as dsf
dsf.get_calendar('XTKS').schedule('2026-11-02', '2026-11-06') # sf.Frame
import diurn.py as dpy
dpy.get_calendar('XHKG').next_session('2026-12-24') # datetime.date(2026, 12, 28)
Every method accepts dates as datetime.date, ISO strings, pandas Timestamps
or NumPy datetime64, and instants as aware datetimes, aware Timestamps, or
ISO strings with an offset. A naive datetime is refused: it is not an instant.
The interface
is_session, sessions_in_range, next_session, previous_session,
date_to_session(direction=), sessions_window, sessions_distance,
next_open, next_close, is_open_at_time, session_open,
session_close, session_break_start, session_break_end and schedule,
as in exchange_calendars, with these differences:
- A session is a day the venue trades, as the API's
/v1/trading-days
counts one: open, early_close, open_for_some, and a holiday that
carries a session, such as NSE's Muhurat.
unknown is neither open nor closed. Past what Diurn can answer, a
method that depends on such a day raises diurn.Indeterminate. Pass
on_unknown="missing" to get None (or NaT) instead; ranges then leave
the day out.
- Instants keep the venue's zone, in the Pandas and plain flavors. They
compare equal to UTC ones.
schedule(start, end) is a method over a range, since the calendar is
answered by an API rather than precomputed. It adds kind, verification
and reason; all_days=True keeps holidays and unknown days as rows.
next_session and previous_session take any date, not only a session.
- A session's times are
None (or NaT) where Diurn holds no hours for
it, a day known to trade whose hours are not published; a date that is
not a session is a ValueError, as in exchange_calendars.
sessions_distance over a range with an unknown day raises, or with
on_unknown="missing" is None: a count that skipped the day would be
wrong.
- Product schedules. Where a venue keeps several (
calendar.products),
get_calendar(mic, product=...) picks one; by default the whole venue's
sessions are used. A product with no hours of its own has none: it is never
given another product's.
name is the MIC, as exchange_calendars names a calendar by its code;
the registry's name is market_name. tz is the IANA name, a string,
where exchange_calendars has a ZoneInfo.
The API
diurn.Client has one method per API operation and returns typed models:
venue search, multi-venue status, exceptions, trading-day arithmetic, usage.
client = diurn.Client() # DIURN_API_KEY, DIURN_API_URL
client.statuses(['XNYS', 'XLON', 'XTKS']) # whether each is trading now
client.usage() # your plan's meters
Retries are off by default. Client(retries=3) retries what waiting can
fix: a rate limit, after the server's Retry-After; a 503 or a dropped
connection, backing off from half a second. A plan's refusal (a MIC cap, a
date outside the window) is never retried, and a wait longer than max_wait
seconds (60) is raised rather than slept. A calendar retries as its client
does: diurn.get_calendar('XNYS', client=diurn.Client(retries=3)).
diurn.AsyncClient has the same methods as coroutines, for an event loop.
It needs nothing beyond the standard library: each call runs the client in a
worker thread, so calls made together run together.
client = diurn.AsyncClient()
statuses = await asyncio.gather(*(client.status(mic) for mic in ('XNYS', 'XLON')))
Errors
Typed, never prose: AuthError (no or inactive key), UnknownVenue,
OutOfWindow (with allowed_from and allowed_to), NotInPlan,
MicCapExceeded (with mics_in_use and resets_at), RateLimited (with
retry_after), Indeterminate and TransportError, all under
diurn.DiurnError. Every plan refusal is an OverLimit with limit and
resets_at. Indeterminate is raised the same whether the calendar met an
unknown day or the API did (its 422, as IndeterminateResponse, also an
ApiError); a stepping method that finds no session within 800 days raises
it too.
Caching
Responses are cached on disk by MIC, range and the dataset the server serves.
The dataset is checked against the free /health endpoint every few minutes,
so a cached answer is reused exactly as long as it is still the answer, and a
repeat query makes no metered request. The directory is DIURN_CACHE_DIR, or
the platform's own cache directory: ~/Library/Caches/diurn on macOS,
%LOCALAPPDATA%\diurn\Cache on Windows, and $XDG_CACHE_HOME/diurn or
~/.cache/diurn elsewhere (XDG_CACHE_HOME is honoured on any platform where
it is set). get_calendar(..., cache=False) turns it off.
License
MIT or Apache-2.0, at your option.