Metadata-Version: 2.4
Name: aion-indian-market-calendar
Version: 1.1.3
Summary: India financial market calendar for NSE holidays, BSE trading calendar checks, MCX evening sessions, and algorithmic trading market session validation.
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,nse-holidays,bse-trading-calendar,indian-trading-holidays,market-session-validation,intraday-trading,algorithmic-trading,quantitative-finance,pandas-market-calendars
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.

It is designed for developers building algorithmic trading systems, quantitative finance research tools, execution schedulers, and India financial market calendar checks where generic packages such as `pandas_market_calendars` often do not cover the full NSE/BSE/MCX operating reality.

### 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.

`v1.1.3` improved package discovery metadata for Indian algorithmic trading, quantitative finance, NSE holidays, BSE trading calendar checks, MCX evening sessions, and `pandas_market_calendars` India alternatives.

### 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`
- `pandas_market_calendars` India alternative
- `algorithmic trading` calendar guardrails
- `quantitative finance` market session validation
- `NSE holidays`
- `Indian trading holidays`
- `BSE trading calendar`
- `MCX evening session`
- `India financial market calendar`
- intraday and algo trading systems that need correct session validation

### Use This For

- holiday lookup
- trading-session lookup
- market session validation
- 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.

If you are using `pandas_market_calendars` or a generic exchange calendar for India, this package is intended to fill the India-specific gaps: NSE holidays, Indian trading holidays, BSE trading calendar behavior, MCX evening session handling, and session-aware validation for Indian financial-market infrastructure.

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.
