🕉️ Kalagana

An offline, dependency-free Hindu (Drik) Panchang & festival calculator in pure Python.

Tithi, Vara, Nakshatra, Yoga, Karana, sunrise/sunset, ayanamsa, muhurta and festival dates — computed from first principles, with no network, no database and no downloaded ephemeris files.

What is Kalagana?

Kalagana computes a complete Drik Panchang — the five traditional limbs of the Hindu calendar — together with the dates of Hindu, Islamic, national and observances festivals, 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.

✨ 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: 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.

📄 License

Released under the MIT License — see the LICENSE file.

Copyright (c) 2026 Amit K. Jangir.