🕉️ Kalagana — Official Drik Panchang & Panchangam for Python

The official, offline, dependency-free Python library and CLI for the Hindu (Drik) Panchang, Panchangam and the Indian festival calendar.

Compute Tithi, Vara, Nakshatra, Yoga, Karana, sunrise/sunset, ayanamsa, muhurat (muhurta) and the dates of Hindu, Islamic and national festivals — for any city in India or worldwide — from first principles, with no network, no database and no downloaded ephemeris files.

What is Kalagana?

Kalagana computes a complete Drik Panchang (also written panchangam, panjika or Hindu calendar) — the five traditional limbs of the Hindu calendar — together with the dates of Hindu festivals, Islamic (Hijri) festivals and Indian national holidays, for any latitude, longitude and timezone, in both North (purnimanta) and South (amanta) traditions.

Everything is derived from positional astronomy implemented in the code itself, using the algorithms from Jean Meeus' Astronomical Algorithms. There are:

• ❌ no network calls
• ❌ no database
• ❌ no downloaded ephemeris files
• ❌ no third-party packages
• ✅ just the Python standard library

The same inputs always produce the same outputs — the calculation core is pure and deterministic.

What you can compute

Panchang (tithi, nakshatra, yoga, karana, vara), sunrise/sunset and moonrise/moonset, muhurat (Rahu Kalam, Yamaganda, Gulika, Abhijit, Choghadiya, Hora, Brahma Muhurta, Durmuhurta), Vikram Samvat / Shaka eras, ritu and ayana, and a rule-driven calendar of Hindu festivals (Diwali, Holi, Navratri, Dussehra, Ganesh Chaturthi, Krishna Janmashtami, Ekadashi, Karwa Chauth, Chhath Puja, Makar Sankranti, Pongal, Onam …), Islamic festivals (Eid al-Fitr, Eid al-Adha, Muharram, Milad-un-Nabi …) and Indian national holidays — for any date, past or decades ahead.

✨ Highlights

• 🌗 Full five limbs — Tithi (with paksha), Vara, Nakshatra (with pada), Yoga and Karana, each with exact start and end times.
• ☀️ Rise & set — sunrise, sunset, moonrise, moonset and solar noon, with refraction and disc-limb corrections.
• 🌐 Location aware — geodetic latitude/longitude + IANA timezone; ships with a built-in city table (no lookup service).
• 📐 Multiple ayanamsa — Lahiri (default), Raman, KP, Yukteshwar and Fagan–Bradley.
• 🧮 Meeus-grade astronomy — Sun to ~0.01°, Moon to ~10″, including nutation, aberration and ΔT.
• 🎉 Festivals from rules, never stored — Hindu (lunar + solar sankranti), Islamic (Hijri), national holidays and fixed-date observances, plus monthly vrats.
• 🐍 Pure standard library — targets Python 3.10+.

🚀 Installation

pip install kalagana

On Windows, add the optional timezone database for full IANA support (India is exact either way):

pip install "kalagana[tz]"

Verify the install:

python -c "import kalagana; print(kalagana.__version__)"

No dependencies are pulled in — the runtime uses only the Python standard library.

🧑💻 Command line

Installing the package adds a kalagana command (equivalent to python -m kalagana). Every data subcommand takes a location (--city, or --lat/--lon) and --format text|json|csv.

Common options:

--city NAME            # built-in city key (see `kalagana cities`)
--lat D --lon D        # explicit coordinates instead of a city
--tz Asia/Kolkata      # override the timezone
--tradition north      # north | south | tamil | telugu | kannada | malayalam | bengali | odia | gujarati | marathi
--ayanamsa lahiri      # lahiri | raman | kp | yukteshwar | fagan_bradley
--format text|json|csv # output format

Examples:

# JSON output, piped to jq
kalagana day 2026-11-08 --city delhi --format json

# National holidays only (kind filter)
kalagana festivals 2026 --kind national

# Recompute without Islamic festivals
kalagana festivals 2026 --no-islamic

⚡ Quick start (Python)

from datetime import date
from kalagana import daily_panchang, festivals_for_year, city_lookup

loc = city_lookup("Delhi")

# The five limbs for the Hindu day beginning at sunrise
day = daily_panchang(date(2026, 11, 8), loc)
print(day.vara_en, "|", day.masa_purnimanta, day.paksha)
for t in day.tithi:
    print(f"Tithi    : {t.name:<22} {t.start:%H:%M} → {t.end:%H:%M}")

# Festival dates are computed from rules, not stored
for f in festivals_for_year(2026, loc, include_monthly=False, kinds=("national",)):
    print(f.date, f.name, f.kind)

Real output (Delhi, 8 November 2026 — Diwali day):

Sunday | Kartika Krishna
Tithi    : Krishna Chaturdashi    06:39 → 11:30
Tithi    : Amavasya               11:30 → 06:40
2026-01-26 Republic Day national
2026-08-15 Independence Day national
2026-10-02 Gandhi Jayanti national

🎉 Festivals

Festival dates are produced by a generic engine from a table of rules — never stored. Rules come in four groups:

from datetime import date
from kalagana import festivals_for_year, national_holidays, find_next, city_lookup

delhi = city_lookup("Delhi")
national_holidays(2026, delhi)                       # the three gazetted holidays
find_next("Eid al-Fitr", date(2026, 1, 1), delhi)    # 2026-03-20

Every occurrence carries a kind — festival, national or observance. Whole groups can be switched off with include_islamic=False / include_fixed=False (or the KALAGANA_INCLUDE_* environment variables).

Islamic dates use the tabular (arithmetic) Islamic calendar, so they may differ by a day or two from the locally sighted date.

🌐 REST API

Kalagana ships a small offline REST API built on the standard-library http.server (no web framework, no network):

kalagana serve --port 8765      # or: python -m kalagana.server

curl -s "http://127.0.0.1:8765/day?date=2026-11-08&city=delhi"
curl -s "http://127.0.0.1:8765/festivals?year=2026&city=delhi&kind=national"

Full reference: docs/api/README.md.

⚙️ Configuration

Kalagana needs no configuration to run, and defaults to Delhi / Asia/Kolkata (IST). Optional settings are read from the environment and a local .env file (parsed by kalagana/config.py; no python-dotenv dependency):

cp .env.example .env

The full annotated list is in .env.example.

🔬 Accuracy

Limb boundaries are located to one second of time. Eclipses are computed by an approximate detector (correct dates, rough type) — consult an authoritative ephemeris for exact circumstances, and always cross-check important dates against your local panchang.

⚠️ Disclaimer

Panchang calculations encode tradition and convention (ayanamsa choice, masa system, tie-break rules), and Islamic dates use a tabular calendar. Regional and sampradaya differences exist and are treated as first-class options rather than bugs.

Kalagana is an independent, open-source project. Here "official" means only that this is the project's canonical package on PyPI — Kalagana is not affiliated with, endorsed by, or connected to drikpanchang.com, any government body, or any religious institution.

📄 License

Released under the MIT License — see the LICENSE file.

Copyright (c) 2026 Amit K. Jangir.