Metadata-Version: 2.4
Name: aion-market-calendar
Version: 0.1.0
Summary: Trading calendar and date utilities
Keywords: trading,calendar,exchange-calendars,finance,dates,nyse,xnys
Author: aklingler
Author-email: aklingler <andrew.j.klingler@gmail.com>
License-Expression: MIT
License-File: LICENSE
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Financial and Insurance Industry
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Office/Business :: Financial
Classifier: Typing :: Typed
Requires-Dist: exchange-calendars>=4.13.2
Requires-Python: >=3.10
Project-URL: Homepage, https://github.com/delian-research/aion
Project-URL: Repository, https://github.com/delian-research/aion
Project-URL: Issues, https://github.com/delian-research/aion/issues
Project-URL: Changelog, https://github.com/delian-research/aion/blob/main/CHANGELOG.md
Description-Content-Type: text/markdown

# 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

```bash
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`:

```python
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 `Timestamp`s), 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.

```python
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:

```python
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:

```python
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:

```python
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:

```python
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.

```python
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:

```python
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

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