Metadata-Version: 2.4
Name: pancanga
Version: 0.1.0
Summary: Panchanga (pañcāṅga) engine: Hindu calendar calculations with zero dependencies, for CPython, MicroPython, and the browser
Keywords: astronomy,hindu-calendar,lunisolar,micropython,nakshatra,pancanga,panchang,panchanga,pyscript,tithi
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: Implementation :: CPython
Classifier: Programming Language :: Python :: Implementation :: MicroPython
Classifier: Topic :: Religion
Classifier: Topic :: Scientific/Engineering :: Astronomy
Requires-Python: >=3.12
Provides-Extra: dev
Requires-Dist: playwright<2,>=1.63; extra == 'dev'
Description-Content-Type: text/markdown

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

```bash
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:

```bash
pixi run production-server
```

## Install and use the package

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

```bash
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:

```python
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:

```python
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:

```html
<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:

```bash
pixi run test-suite
```

Check generated browser manifests and deployed assets:

```bash
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:

```bash
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.
