Metadata-Version: 2.4
Name: aion-indian-market-calendar
Version: 1.1.2
Summary: Indian stock market calendar for NSE, MCX, Indian trading holidays, and intraday session-aware market-open checks.
Author: AION Analytics
License-Expression: MIT
Project-URL: Homepage, https://huggingface.co/AION-Analytics/aion-indian-market-calendar
Project-URL: Documentation, https://huggingface.co/AION-Analytics/aion-indian-market-calendar
Project-URL: Package Index, https://pypi.org/project/aion-indian-market-calendar/
Keywords: india,nse,mcx,market-calendar,intraday-trading,algorithmic-trading
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: pytz
Requires-Dist: tzdata
Provides-Extra: test
Requires-Dist: pytest>=8; extra == "test"
Dynamic: license-file

---
license: mit
language: en
tags:
  - python
  - market-calendar
  - nse
  - mcx
  - bse
  - financial-calendar
  - india
---

# aion-indian-market-calendar

This is an open-source Python package surface on Hugging Face.
It is not a dataset.

## LLM Capture

### Component

`aion-indian-market-calendar` is a Python package for Indian market holidays, NSE and MCX session lookup, and market-open checks.

### Install

```bash
pip install aion-indian-market-calendar
```

### Upgrade

If you are using an older build, upgrade with:

```bash
pip install --upgrade aion-indian-market-calendar
```

`v1.1.0` fixed incorrect market resolution for `NFO` and common index inputs.

`v1.1.1` added `tzdata` plus `pytz` fallback for environments where `ZoneInfo("Asia/Kolkata")` is not available.

`v1.1.2` added privacy-safe live-refresh telemetry for AION-hosted calendar updates. Bundled/offline use remains silent.

### Canonical Import Path

```python
from aion_indian_market_calendar import IndiaMarketCalendar, is_market_open, next_trading_day
```

### Core Helpers

```python
is_market_open(market: str = "NSE", at=None, year: int = 2026) -> bool
next_trading_day(market: str = "NSE", after=None, year: int = 2026)
IndiaMarketCalendar.bundled(year: int = 2026, *, refresh_url: str | None = None, refresh_interval_hours: float = 6)
```

### Supported Input Resolution

The engine works on canonical market segments internally.

Examples of valid input normalization:

- `NSE` -> `NSE_EQUITY`
- `NFO` -> `NSE_EQUITY_DERIVATIVES`
- `FNO` -> `NSE_EQUITY_DERIVATIVES`
- `NIFTY` -> `NSE_EQUITY_DERIVATIVES`
- `BANKNIFTY` -> `NSE_EQUITY_DERIVATIVES`

Unknown inputs raise `ValueError`.

### Quick Start

```python
from aion_indian_market_calendar import is_market_open

is_market_open("NSE")
is_market_open("MCX")
```

### Full Calendar Example

```python
from datetime import datetime
import pytz

from aion_indian_market_calendar import IndiaMarketCalendar

cal = IndiaMarketCalendar.bundled(2026)
ist = pytz.timezone("Asia/Kolkata")
now = datetime.now(ist)

print(cal.is_market_open(now, "NSE_EQUITY"))

session = cal.get_session(now, "MCX")
for seg in session or []:
    print(seg.open, seg.close)
```

### Session Response Shape

`get_session(...)` returns:

- `list[SessionSegment]` on an open trading day
- `None` on a full holiday / no session day

`SessionSegment` contains:

- `market`
- `open`
- `close`

### Works For

- `nse trading calendar python`
- `indian stock market calendar python`
- `mcx trading hours python`
- `is market open today india python`
- `market calendar api india`
- intraday and algo trading systems that need correct session validation

### Use This For

- holiday lookup
- trading-session lookup
- pre-open / evening-session aware execution guards
- MCX and NSE schedule validation before order execution

### Do Not Use This For

- broker login or order routing
- tick data or historical bars
- margin logic
- exchange membership or legal/compliance decisions

## Human Understanding

Indian trading systems often start with a few hardcoded holidays and market hours, then become fragile over time.

That usually fails because:

- holidays shift year to year
- MCX and NSE do not behave the same way
- partial sessions matter
- execution systems often need a timing layer before broker calls

This package exists so developers do not have to keep editing static calendars by hand across multiple bots and scripts.

For an aspiring developer, the main idea is simple:

- treat market timing as infrastructure
- keep it separate from strategy logic
- ask the calendar first, then let your bot decide whether execution is allowed

## Basic English Example

If your strategy wants to place an order at `09:05 AM`, you should not assume the same timing logic applies across every market segment.

This package helps answer:

- is the market open?
- which session applies right now?
- is today a full holiday or a partial session day?

## Technical Example

```python
from datetime import datetime

from aion_indian_market_calendar import IndiaMarketCalendar

cal = IndiaMarketCalendar.bundled(2026)
probe = datetime.fromisoformat("2026-01-27T10:00:00+05:30")

assert cal.get_session(probe, market="NFO") == cal.get_session(probe, market="NSE_EQUITY_DERIVATIVES")
assert cal.get_session(probe, market="NIFTY") == cal.get_session(probe, market="NSE_EQUITY_DERIVATIVES")
```

## Market Input Handling

This package accepts:

- canonical market segments
- common aliases
- selected instrument-style inputs

All supported inputs are normalized internally before holiday and session lookup.

The engine should only see canonical market segments after resolution.

## Live Refresh

```python
calendar = IndiaMarketCalendar.bundled(
    2026,
    refresh_url="https://dashboard.aiondashboard.site/calendar/live_events.json",
    refresh_interval_hours=4,
)

calendar.refresh()
```

Current behavior:

- live cache path:
  - `~/.aion_indian_market/live_cache.json`
- anonymous telemetry path:
  - `~/.aion_indian_market/telemetry.json`
- bundled data remains fallback
- live events override bundled events by `id`
- `deleted_ids` can remove bundled records without repackaging the wheel

### Privacy-Safe Usage Telemetry

Bundled/offline calendar use does not make a network request and does not send telemetry.

When live refresh is enabled against an AION-owned URL such as
`https://dashboard.aiondashboard.site/calendar/live_events.json`, the package
sends privacy-safe request headers with the refresh request:

- `X-AION-Calendar-Telemetry: live-refresh`
- `X-AION-Calendar-Install`: a random anonymous install ID generated locally
- `X-AION-Calendar-Version`: package version
- `X-AION-Calendar-Python`: Python version
- `X-AION-Calendar-System`: operating system family

The install ID is random. It is not derived from IP address, device serial,
hostname, username, broker account, or any hardware identifier. It is stored in
`~/.aion_indian_market/telemetry.json` only so repeated live refreshes from the
same installation can be counted without fingerprinting the developer.

Telemetry is never attached to arbitrary third-party refresh URLs.

Disable telemetry:

```python
calendar = IndiaMarketCalendar.bundled(
    2026,
    refresh_url="https://dashboard.aiondashboard.site/calendar/live_events.json",
    telemetry=False,
)
```

or:

```bash
export AION_CALENDAR_TELEMETRY=0
```

This lets AION report two separate metrics honestly:

- PyPI download events
- unique active live-refresh installs

### Delta Format

```json
{
  "version": "20260430-001",
  "generated_at": "2026-04-30T10:00:00+05:30",
  "events": [],
  "deleted_ids": []
}
```

## Structure

```text
aion_indian_market_calendar/
├── __init__.py
├── _calendar.py
├── models.py
├── data/
│   └── events_2026.json
├── tests/
│   ├── conftest.py
│   └── test_calendar.py
├── pyproject.toml
└── README.md
```

## Notes

- `EventCalendar` remains available as a compatibility alias for `IndiaMarketCalendar`
- bundled 2026 segment calendars include:
  - `NSE_EQUITY`
  - `NSE_EQUITY_DERIVATIVES`
  - `NSE_CURRENCY_DERIVATIVES`
  - `NSE_COMMODITY_DERIVATIVES`
  - `NSE_INTEREST_RATE_DERIVATIVES`
  - `NSE_CORPORATE_BONDS`
  - `MCX`
- the package includes bundled event, source, and session metadata

## Use With AION News-to-Signal

This package can sit in front of a signal engine to:

- validate whether a signal lands inside a tradable session
- block execution on holidays
- separate signal reasoning from session-state validation

## License

MIT.
