django-bikram 0.1.0__tar.gz

django_bikram-0.1.0/.gitignore

@@ -0,0 +1,33 @@
+# Byte-compiled / optimized
+__pycache__/
+*.py[cod]
+*$py.class
+
+# Distribution / packaging
+build/
+dist/
+*.egg-info/
+.eggs/
+wheels/
+
+# Test / type / lint caches
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+.coverage
+.coverage.*
+htmlcov/
+.tox/
+.nox/
+
+# Virtual environments
+.venv/
+venv/
+env/
+ENV/
+
+# Editor / OS
+.idea/
+.vscode/
+*.swp
+.DS_Store

django_bikram-0.1.0/CHANGELOG.md

@@ -0,0 +1,55 @@
+# Changelog
+
+All notable changes to this project are documented here.
+
+The format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+## [0.1.0] - 2026-07-18
+
+Initial release.
+
+### Added
+
+- `BSDate`: an immutable, hashable, totally ordered Bikram Sambat date with a
+  `datetime.date`-shaped API — `weekday()`, `isoformat()`, `replace()`,
+  `timedelta` arithmetic, and `BSDate - BSDate -> timedelta`.
+- AD ↔ BS conversion (`django_bikram.convert`) via day-offset arithmetic from a
+  single anchor. `O(log years)` per conversion; never walks day by day.
+- Verified calendar data for **1975–2083 BS** (1918-04-13 – 2027-04-13 AD),
+  cross-checked between two independent MIT-licensed sources. Dates outside the
+  range raise `DateOutOfRange` rather than being extrapolated.
+- Two-tier calendar data: `VERIFIED_BS_MONTH_DAYS` (two-source attested) versus
+  an opt-in `PROVISIONAL_BS_MONTH_DAYS` (computed). `is_verified_year()` and
+  `BSDate.is_verified` report which tier a date belongs to.
+- `django_bikram.predict`: a Surya-Siddhanta month-length predictor for years
+  past the verified range. `validate()` backtests it against the 109 verified
+  years (~87% of months exact, remainder ±1 day, 58/109 years fully correct);
+  `build_provisional_table()` returns the predicted table. Enable predicted
+  years with the `DJANGO_BIKRAM_PROVISIONAL_THROUGH_YEAR` environment variable
+  or `install_provisional()`; using one raises `ProvisionalDateWarning`.
+  Predictions are never presented as verified.
+- `django_bikram.formatting`: strftime-style formatting and parsing with
+  independent language (English/Nepali) and numeral (ASCII/Devanagari) switches.
+  Directives: `%Y %y %m %-m %d %-d %B %b %A %a %j %%`.
+- `django_bikram.django.fields.BSDateField`: a `models.DateField` subclass that
+  stores a native Gregorian `date` and exposes a `BSDate`, preserving indexes,
+  range queries, ordering, aggregation and DB-side date functions.
+- `django_bikram.django.forms`: `BSDateField` form field and `BSDateInput` widget.
+- `django_bikram.django.drf`: DRF serializer field, import-guarded as an optional
+  extra, plus `register_serializer_field()` for `ModelSerializer`.
+- `django_bikram.django.lookups`: `bs_year_q` / `bs_month_q` / `bs_year_bounds` /
+  `bs_month_bounds` — index-friendly half-open range helpers.
+- Migration serializer for `BSDate`, so `default=BSDate(...)` works.
+- `py.typed`: the package ships inline type information and passes `mypy --strict`.
+- Bilingual documentation: English and Nepali README plus a Nepali quickstart.
+
+### Deliberately not included
+
+- `__bs_year` / `__bs_month` query transforms. See the README section
+  "Why there is no `__bs_year` lookup" — the range helpers are exact and use
+  the index; a transform would not.
+- Bikram Sambat time/datetime types. The calendar defines days, not clocks;
+  use an ordinary `DateTimeField` for instants.

django_bikram-0.1.0/CONTRIBUTING.md

@@ -0,0 +1,55 @@
+# Contributing to django-bikram
+
+Thanks for helping. The bar here is high on purpose: this is a calendar library,
+and a wrong month length is a silent, hard-to-notice bug.
+
+## Development setup
+
+```bash
+git clone https://github.com/anishbhimgc/django-bikram
+cd django-bikram
+python -m venv .venv && source .venv/bin/activate
+pip install -e ".[dev]"
+```
+
+## The checks CI runs (run them before you push)
+
+```bash
+pytest                    # the full suite
+ruff check django_bikram/ # style + lint
+mypy django_bikram/       # strict typing
+```
+
+CI additionally runs the test suite across Python 3.10–3.13 and Django 4.2 / 5.1
+/ 5.2, verifies the docstring examples, and validates the built package metadata.
+
+## Touching the calendar data
+
+`django_bikram/calendar_data.py` is the correctness core.
+
+- **Verified years** (`VERIFIED_BS_MONTH_DAYS`) may only be added when a year is
+  corroborated by **at least two independent published sources**, and must pass
+  the invariants in `tests/test_calendar_data.py` (twelve months, 365/366 days,
+  no filler tail).
+- **Do not** promote predicted (provisional) data into the verified table. The
+  predictor in `django_bikram/predict.py` is ~87% accurate per month (see its
+  `validate()`); that is a planning aid, never a source of verified dates.
+
+## Releasing (maintainers)
+
+Publishing uses **PyPI Trusted Publishing** — no tokens are stored.
+
+One-time PyPI setup:
+
+1. On https://pypi.org, register a *pending publisher* under the project
+   (or the account): PyPI → *Your projects* → *Publishing* → add a GitHub
+   publisher with owner `anishbhimgc`, repo `django-bikram`, workflow
+   `publish.yml`, environment `pypi`.
+
+Each release:
+
+1. Bump `version` in `pyproject.toml` and move the `CHANGELOG.md` entries from
+   *Unreleased* into a dated version section.
+2. Commit, tag (`git tag v0.1.0 && git push --tags`).
+3. Create a GitHub Release for that tag. The `publish.yml` workflow builds,
+   checks, and uploads to PyPI automatically.

django_bikram-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 django-bikram contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.