Skip to main content

Aion

Aion is a small Python package for trading-calendar date logic. Version 1 focuses on US equities through the XNYS calendar from exchange_calendars.

Installation

pip install aion-market-calendar        # or: uv add aion-market-calendar

The distribution is named aion-market-calendar on PyPI, but the package is imported as aion:

import aion

Aion supports Python 3.10+ and depends only on exchange_calendars. Unlike pandas-based market-calendar libraries, every entry point returns plain Python datetime.date objects (never pandas Timestamps), so you can use it without pulling pandas into your own call sites.

Worked example: quarterly expiration

A common pattern is trading around an event that recurs on a fixed weekday of a quarter-end month — for example the quarterly equity-option expiration on the third Friday of March, June, September, and December — and lining up an entry a set number of trading days earlier.

from aion import Aion, Weekday

# Event: 3rd Friday of Q1's expiration month (March), snapped to a trading day.
event = Aion("2026-01-01").nth_weekday_of_month(Weekday.FRIDAY, 3, month=3).tday()

# Entry: 5 trading days before the event (holidays skipped by the XNYS calendar).
entry = event.tday(-5)

event.date(), entry.date()
# (datetime.date(2026, 3, 20), datetime.date(2026, 3, 13))

The trailing .tday() on the event matters: nth_weekday_of_month is pure calendar math and does not know about holidays, and the third Friday of March can land on Good Friday — a market closure (it did in 2008). tday() rolls a non-trading anchor back to the prior session (use roll="next" to roll forward) before any offset is applied.

Low-level calendar API

The low-level calendar API uses plain Python dates:

from aion import get_calendar

cal = get_calendar()

cal.is_trading_day()
# True if today is a trading day in the XNYS calendar

cal.is_trading_day("2026-01-02")
# True

cal.current_trading_day("2026-01-18")
# datetime.date(2026, 1, 16)

cal.previous_trading_day("2026-01-05")
# datetime.date(2026, 1, 2)

cal.next_trading_day("2026-01-17")
# datetime.date(2026, 1, 20)

cal.offset_trading_days("2026-01-16", 1)
# datetime.date(2026, 1, 20)

Every entry point defaults to today (resolved in the calendar's timezone) when no date is given — cal.is_trading_day(), Aion(), and the convenience functions below.

For one-off lookups that return a plain datetime.date, import the module-level helpers instead of constructing a calendar:

from aion import current_trading_day, previous_trading_day, next_trading_day

current_trading_day()
# today's session, or the most recent one if today does not trade

current_trading_day("2026-01-18")
# datetime.date(2026, 1, 16)

previous_trading_day("2026-01-05")
# datetime.date(2026, 1, 2)   (exclusive)

next_trading_day("2026-01-02")
# datetime.date(2026, 1, 5)   (exclusive)

previous_trading_day("2026-01-05", inclusive=True)
# datetime.date(2026, 1, 5)

Each accepts a calendar="XNYS" keyword to target another exchange.

The Aion class provides an immutable fluent API for composing date transforms:

from aion import Aion, Weekday

Aion("2026-05-15").qe().months(-1).me().tday().date()
# datetime.date(2026, 5, 29)

Aion("2026-05-15").quarter_end().months(-1).month_end().trading_day().date()
# datetime.date(2026, 5, 29)

Aion("2026-02-28").months(1, preserve_eom=True).date()
# datetime.date(2026, 3, 31)

Aion("2026-05-15").week_start(Weekday.MONDAY).date()
# datetime.date(2026, 5, 11)

Aion("2026-05-15").last_weekday_of_month(Weekday.FRIDAY).tday().date()
# datetime.date(2026, 5, 29)

Aion()
# today, resolved in the calendar's timezone

Aion mirrors the trading-day navigation as chainable transforms. tday() snaps to a trading day (and optionally offsets by sessions), while previous_trading_day() / next_trading_day() step strictly off the anchor:

Aion("2026-01-03").tday().date()
# datetime.date(2026, 1, 2)   (Saturday rolls back to Friday)

Aion("2026-01-03").tday(1, roll="next").date()
# datetime.date(2026, 1, 6)   (roll forward to Monday, then +1 session)

Aion("2026-01-05").previous_trading_day().date()
# datetime.date(2026, 1, 2)   (exclusive)

Aion("2026-01-05").previous_trading_day(inclusive=True).date()
# datetime.date(2026, 1, 5)

The short aliases map to descriptive methods:

  • qe() is quarter_end()
  • qs() is quarter_start()
  • me() is month_end()
  • ms() is month_start()
  • tday() is trading_day()
  • ye() is year_end()
  • ys() is year_start()

Period-end methods accept offsets. For example, quarter_end(1) moves to the next quarter's end after the containing quarter.

Range queries are half-open by default: start is included and end is excluded.

cal.trading_days_between("2026-01-02", "2026-01-05")
# 1

cal.trading_days("2026-01-02", "2026-01-05")
# (datetime.date(2026, 1, 2),)

cal.trading_days("2026-01-02", "2026-01-05", inclusive="both")
# (datetime.date(2026, 1, 2), datetime.date(2026, 1, 5))

For non-trading anchors, offset operations roll to the previous trading day by default:

cal.offset_trading_days("2026-01-03", 0)
# datetime.date(2026, 1, 2)

cal.offset_trading_days("2026-01-03", 0, roll="next")
# datetime.date(2026, 1, 5)

Development

uv run pytest
uv run ruff check .
uv run mypy src
uv build

Metadata

Release files for aion-market-calendar 0.1.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for aion-market-calendar 0.1.0
File Size Uploaded Provenance Actions
aion_market_calendar-0.1.0.tar.gz 9.4 kB With provenance Details for aion_market_calendar-0.1.0.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for aion-market-calendar 0.1.0
File Interpreter ABI Platform Actions
aion_market_calendar-0.1.0-py3-none-any.whl Python 3 none any Details for aion_market_calendar-0.1.0-py3-none-any.whl

Total release size: 20.9 kB

Release files / aion_market_calendar-0.1.0.tar.gz

Download URL aion_market_calendar-0.1.0.tar.gz
Size 9.4 kB
Tags Source
SHA-256 checksum
How to use checksums
ba91fa7991810192295bfc6fd38ad8dbaba2ec89e53630ef3ec950bee81816ba
BLAKE2b-256 checksum
How to use checksums
f1b77a0f6568c07a2e581c4bdfc9b9c858939ab6c5922943049b4f9b0aa0dd68
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/6.1.0 CPython/3.13.14

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Jul 28, 2026.

Transparency log

Release files / aion_market_calendar-0.1.0-py3-none-any.whl

Download URL aion_market_calendar-0.1.0-py3-none-any.whl
Size 11.5 kB
Tags Python 3
SHA-256 checksum
How to use checksums
42367bd2fbf6fb0d589398d26de46f8ec0d2a7fe0de59c6358f25d71d7e24708
BLAKE2b-256 checksum
How to use checksums
66c6db8edb52b2c3208ae9e5a6e4b7fddf2227be6e47104e326329adee5cacd2
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/6.1.0 CPython/3.13.14

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Jul 28, 2026.

Transparency log

Security for aion-market-calendar 0.1.0

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

Full provenance

Both files in this release have been uploaded with provenance metadata.

Select from 2 files

Attestation for aion_market_calendar-0.1.0.tar.gz

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Jul 28, 2026.

Transparency log

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Release history Release notifications | RSS feed

This release

0.1.0 This release

2 release files Full provenance

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page