Panchanga

A basic Hindu calendar and daily Panchanga web app.

Current v1 scope

The current branch provides a daily Panchanga view for a selected date and location, including:

• Tithi and Paksha
• Vara
• Nakshatra
• Yoga
• Karana
• Lunar Masa, including Adhika Masa
• Vikram and Shaka Samvat years
• Sunrise and sunset
• Amanta and Purnimanta calendar conventions
• Browser timezone detection with an Amsterdam fallback
• Previous day, Today, and Next day navigation
• A curated bilingual Hindu festival list (Live/Explore/Tithi same-day badge, plus a browsable Festivals tab with per-year resolved dates)
• Installable/offline-capable PWA assets

Panchanga shows the daily Tithi, Vara, Nakshatra, Yoga, and Karana, along with the lunar month, Samvat years, sunrise, and sunset. Results depend on the selected date, location, timezone, and calendar convention.

Run locally

Install the Pixi environment and start the development server. The task builds public/ from the package and then serves that deployable artifact:

pixi install
pixi run dev-server

Open http://127.0.0.1:8080/. Do not open index.html with file://; the service worker and offline assets require HTTP or HTTPS.

To serve the deployable PWA artifact instead:

pixi run production-server

Install and use the package

Install the CPython package from PyPI once a release is published:

pip install pancanga
pancanga --date 2026-07-15
pancanga --place "New Delhi" --date 2026-07-15
pancanga --json --date 2026-07-15

The same CLI is available as python -m pancanga. The default output is human-readable; --json emits the stable machine-readable result contract.

For MicroPython targets, use the generated package.json mip manifest hosted with the release artifacts or repository:

import mip
mip.install("https://<pages-host>/<project>/package.json")

Use the URL of the deployed public/package.json; its relative module URLs expect the accompanying pancanga/ directory from the same deployment.

The core engine can then be imported without the CLI, web UI, or location data:

from pancanga import compute_panchanga

PyScript's MicroPython runtime loads the package through its virtual filesystem. The web build generates pyscript.json with the module map and the service worker caches the same module graph for offline use:

<script type="mpy" src="app.py" config="pyscript.json"></script>

The canonical package source lives under src/pancanga; browser assets and the PyScript adapter live under src/pancanga_web.

Verify

Run the complete Python, browser-contract, generated-asset, and reference test suite:

pixi run test-suite

Check generated browser manifests and deployed assets:

pixi run generate-check
# or
python tools/build_manifests.py --check

The Python, browser-contract, generated-asset, MicroPython, Lightpanda, and Firefox offline PWA checks are covered by the Pixi tasks. Full offline browser verification can be run with:

pixi run pwa-e2e-firefox

CI and GitLab Pages

The GitLab pipeline runs the test/compile/generated-manifest checks and a real Firefox offline PWA test. On master, the Pages job runs pixi run build-web, validates the generated public/ artifact, and publishes it to GitLab Pages. The deployed URL is available under Deploy → Pages.

The Pages artifact contains the web app, pyscript.json, package.json, and the cached pancanga/ module tree. The package.json can therefore be used as the mip manifest for MicroPython deployments.

PyPI publication is a separate manual, tag-triggered CI job. It uses uv build and uv publish with the masked UV_PUBLISH_TOKEN variable; it does not run as part of the Pages deployment.

Calculation notes

The browser loads the portable calculation engine as ordinary Python modules through PyScript's files configuration. The service worker caches the module graph for offline use. Daily values are evaluated at local sunrise for the selected coordinates. The app currently uses the Lahiri ayanamsa and supports the generated timezone data documented in docs/pwa-deployment.md.

Calendar results can vary by location, timezone, and calendar convention. This is a basic calendar release, not a complete regional festival or Muhurta calendar.

v1 release boundary

Included in the basic release:

• Daily Panchanga calculation and display
• Date and location selection
• Local sunrise and sunset
• Amanta/Purnimanta selection
• Karana display
• Curated bilingual festival list (same-day badge and a per-year Festivals tab)
• PWA/offline packaging

Deferred to a later release:

• Monthly calendar grid/navigation
• Ekadashi as a recurring rule, deferred-month lookup for Adhika-suppressed festivals, and expanding the curated festival list beyond its current 9-entry seed set
• Muhurta, Choghadiya, and Rahu Kalam
• Additional regional calendar conventions
• Notifications, accounts, and native mobile apps

See docs/release-notes.md for the current branch release summary and remaining release-readiness work.