nepkit 0.1.0__py3-none-any.whl

nepkit/__init__.py

@@ -0,0 +1,32 @@
+"""nepkit — typed Bikram Sambat ↔ Gregorian date conversion.
+
+Everything a caller needs is re-exported here, so the module layout underneath
+stays free to change without breaking imports.
+"""
+
+from nepkit.calendar_data import BS_MONTH_NAMES, MAX_BS_YEAR, MIN_BS_YEAR, days_in_month
+from nepkit.convert import MAX_AD_DATE, MIN_AD_DATE, BSDate, ad_to_bs, bs_to_ad
+from nepkit.exceptions import (
+    CalendarDataError,
+    DateError,
+    DateOutOfRangeError,
+    InvalidDateError,
+    NepkitError,
+)
+
+__all__ = [
+    "BS_MONTH_NAMES",
+    "MAX_AD_DATE",
+    "MAX_BS_YEAR",
+    "MIN_AD_DATE",
+    "MIN_BS_YEAR",
+    "BSDate",
+    "CalendarDataError",
+    "DateError",
+    "DateOutOfRangeError",
+    "InvalidDateError",
+    "NepkitError",
+    "ad_to_bs",
+    "bs_to_ad",
+    "days_in_month",
+]

nepkit/calendar_data.py

@@ -0,0 +1,202 @@
+"""Bundled Bikram Sambat calendar table: validation, loading, and lookups.
+
+See src/nepkit/data/DATA.md for where the underlying numbers came from.
+"""
+
+import json
+from bisect import bisect_right
+from collections.abc import Mapping
+from dataclasses import dataclass
+from datetime import date
+from importlib import resources
+from itertools import pairwise
+from typing import Final
+
+from nepkit.exceptions import CalendarDataError, DateOutOfRangeError, InvalidDateError
+
+_MONTHS_PER_YEAR: Final[int] = 12
+
+# Romanisation varies (Ashoj/Ashwin, Poush/Push, Mangsir/Marga). This set is
+# pinned by a test so it stays stable once anything downstream prints it.
+BS_MONTH_NAMES: Final[tuple[str, ...]] = (
+    "Baisakh",
+    "Jestha",
+    "Ashadh",
+    "Shrawan",
+    "Bhadra",
+    "Ashoj",
+    "Kartik",
+    "Mangsir",
+    "Poush",
+    "Magh",
+    "Falgun",
+    "Chaitra",
+)
+_MIN_DAYS_IN_MONTH: Final[int] = 29
+_MAX_DAYS_IN_MONTH: Final[int] = 32
+_MIN_DAYS_IN_YEAR: Final[int] = 365
+_MAX_DAYS_IN_YEAR: Final[int] = 366
+
+
+@dataclass(frozen=True, slots=True)
+class BSYearData:
+    """One BS year's month lengths, validated on construction."""
+
+    year: int
+    months: tuple[int, ...]
+
+    def __post_init__(self) -> None:
+        if len(self.months) != _MONTHS_PER_YEAR:
+            raise CalendarDataError(
+                f"BS {self.year}: expected {_MONTHS_PER_YEAR} months, got {len(self.months)}"
+            )
+        for month, days in enumerate(self.months, start=1):
+            if not (_MIN_DAYS_IN_MONTH <= days <= _MAX_DAYS_IN_MONTH):
+                raise CalendarDataError(
+                    f"BS {self.year} month {month}: {days} days is outside "
+                    f"[{_MIN_DAYS_IN_MONTH}, {_MAX_DAYS_IN_MONTH}]"
+                )
+        total = sum(self.months)
+        if not (_MIN_DAYS_IN_YEAR <= total <= _MAX_DAYS_IN_YEAR):
+            raise CalendarDataError(
+                f"BS {self.year}: year totals {total} days, outside "
+                f"[{_MIN_DAYS_IN_YEAR}, {_MAX_DAYS_IN_YEAR}]"
+            )
+
+
+def _load_years() -> tuple[BSYearData, ...]:
+    raw = resources.files("nepkit.data").joinpath("calendar.json").read_text(encoding="utf-8")
+    try:
+        rows: object = json.loads(raw)
+    except json.JSONDecodeError as exc:
+        raise CalendarDataError(f"calendar.json is not valid JSON: {exc}") from exc
+
+    if not isinstance(rows, list) or not rows:
+        raise CalendarDataError("calendar.json must contain a non-empty list of year rows")
+
+    years: list[BSYearData] = []
+    for row in rows:
+        if not isinstance(row, dict) or "year" not in row or "months" not in row:
+            raise CalendarDataError(f"calendar.json row is malformed: {row!r}")
+        year, months = row["year"], row["months"]
+        if (
+            not isinstance(year, int)
+            or not isinstance(months, list)
+            or not all(isinstance(m, int) for m in months)
+        ):
+            raise CalendarDataError(f"calendar.json row is malformed: {row!r}")
+        years.append(BSYearData(year=year, months=tuple(months)))
+
+    years.sort(key=lambda y: y.year)
+    return tuple(years)
+
+
+def _check_contiguous(years: tuple[BSYearData, ...]) -> None:
+    for previous, current in pairwise(years):
+        if current.year == previous.year:
+            raise CalendarDataError(f"calendar.json has a duplicate row for BS {current.year}")
+        if current.year != previous.year + 1:
+            raise CalendarDataError(
+                f"calendar.json has a gap: BS {previous.year} is followed by BS {current.year}"
+            )
+
+
+def _build_cumulative_offsets(years: tuple[BSYearData, ...]) -> Mapping[int, int]:
+    """Days from the anchor to the start of each BS year, so bs_to_ad never sums a range."""
+    offsets: dict[int, int] = {}
+    running = 0
+    for year_data in years:
+        offsets[year_data.year] = running
+        running += sum(year_data.months)
+    return offsets
+
+
+_YEARS: Final[tuple[BSYearData, ...]] = _load_years()
+_check_contiguous(_YEARS)
+_BY_YEAR: Final[Mapping[int, BSYearData]] = {y.year: y for y in _YEARS}
+_CUMULATIVE_OFFSET: Final[Mapping[int, int]] = _build_cumulative_offsets(_YEARS)
+# The same offsets as a sorted sequence. _CUMULATIVE_OFFSET answers "which offset
+# does this year start at?"; this answers the inverse, "which year contains this
+# offset?", which is a bisect over boundaries and not a dict lookup at all.
+_YEAR_START_OFFSETS: Final[tuple[int, ...]] = tuple(_CUMULATIVE_OFFSET[y.year] for y in _YEARS)
+
+MIN_BS_YEAR: Final[int] = _YEARS[0].year
+MAX_BS_YEAR: Final[int] = _YEARS[-1].year
+
+# Derived from the table, never written down: the number of days the bundled
+# range covers. Every other bound (the last BS date, the AD window in convert)
+# is computed from this, so extending calendar.json moves them all at once.
+TOTAL_DAYS: Final[int] = sum(sum(y.months) for y in _YEARS)
+
+
+@dataclass(frozen=True, slots=True)
+class Anchor:
+    """The one verified BS↔AD correspondence the whole module hangs on."""
+
+    bs_year: int
+    bs_month: int
+    bs_day: int
+    ad_date: date
+
+
+def _check_anchor_is_first_day_of_min_year(anchor: Anchor, min_year: int) -> None:
+    """The cumulative offset table starts at min_year, so the anchor must be its 1/1."""
+    if (anchor.bs_year, anchor.bs_month, anchor.bs_day) != (min_year, 1, 1):
+        raise CalendarDataError(
+            f"ANCHOR {anchor.bs_year}-{anchor.bs_month:02d}-{anchor.bs_day:02d} is not "
+            f"the first day of calendar.json's first year (BS {min_year}) — the "
+            "cumulative offset table is built starting from that first year, so the "
+            "anchor must be its first day or every offset is silently wrong"
+        )
+
+
+# ANCHOR pins one verified BS<->AD correspondence (see data/DATA.md) as a single
+# fact, rather than two literals that could drift apart, because the AD side
+# cannot be derived from calendar.json's month lengths alone.
+ANCHOR: Final[Anchor] = Anchor(bs_year=2000, bs_month=1, bs_day=1, ad_date=date(1943, 4, 14))
+
+_check_anchor_is_first_day_of_min_year(ANCHOR, MIN_BS_YEAR)
+
+
+def days_in_month(year: int, month: int) -> int:
+    """Number of days in the given BS month. Raises on an out-of-range year or bad month."""
+    if not (MIN_BS_YEAR <= year <= MAX_BS_YEAR):
+        raise DateOutOfRangeError(
+            f"BS year {year} is outside the bundled range [{MIN_BS_YEAR}, {MAX_BS_YEAR}]"
+        )
+    if not (1 <= month <= _MONTHS_PER_YEAR):
+        raise InvalidDateError(f"BS month {month} is outside [1, {_MONTHS_PER_YEAR}]")
+    return _BY_YEAR[year].months[month - 1]
+
+
+def check_bs_date(year: int, month: int, day: int) -> None:
+    """Raise unless (year, month, day) is a real BS date inside the bundled range."""
+    max_day = days_in_month(year, month)  # validates year and month
+    if not (1 <= day <= max_day):
+        raise InvalidDateError(f"BS {year}-{month:02d}: day {day} is outside [1, {max_day}]")
+
+
+def days_from_anchor(year: int, month: int, day: int) -> int:
+    """Days from ANCHOR to the given BS date. The one primitive bs_to_ad needs."""
+    check_bs_date(year, month, day)
+    days_before_month = sum(_BY_YEAR[year].months[: month - 1])
+    return _CUMULATIVE_OFFSET[year] + days_before_month + (day - 1)
+
+
+def bs_from_days(days: int) -> tuple[int, int, int]:
+    """Inverse of days_from_anchor: the BS date that many days after ANCHOR."""
+    if not (0 <= days < TOTAL_DAYS):
+        raise DateOutOfRangeError(
+            f"{days} days from the anchor is outside [0, {TOTAL_DAYS}) — the bundled "
+            f"table covers BS {MIN_BS_YEAR} through {MAX_BS_YEAR}"
+        )
+    index = bisect_right(_YEAR_START_OFFSETS, days) - 1
+    year_data = _YEARS[index]
+    remainder = days - _YEAR_START_OFFSETS[index]
+    for month, length in enumerate(year_data.months, start=1):
+        if remainder < length:
+            return (year_data.year, month, remainder + 1)
+        remainder -= length
+    # Unreachable: the bounds check above puts `days` inside the span, and bisect
+    # picks the year containing it, so `remainder` is always < that year's total.
+    raise AssertionError(f"bs_from_days({days}) escaped BS {year_data.year}'s months")

nepkit/cli.py

@@ -0,0 +1,384 @@
+"""Command-line entry point for nepkit.
+
+Deliberately thin. Everything about *what* to print lives in nepkit.render and
+nepkit.convert; this module decides only where output goes and what exit code
+to leave behind.
+
+Exit codes:
+
+    0  success
+    2  usage error -- bad flag or unknown command (Typer's own)
+    3  InvalidDateError     -- not a real date
+    4  DateOutOfRangeError  -- a real date, but outside the bundled table
+
+3 and 4 are separate on purpose. The exception hierarchy exists so a caller can
+distinguish "you typed something that is not a date" from "that date is real
+but I have no data for it"; collapsing both into 1 would throw that away at the
+one boundary where it is most useful.
+"""
+
+import json
+import shlex
+import sys
+from collections.abc import Generator
+from contextlib import contextmanager
+from datetime import date
+from enum import StrEnum
+from importlib.metadata import version
+from typing import Annotated, Final
+
+import typer
+from rich.console import Console
+from rich.panel import Panel
+from typer.main import get_command
+
+from nepkit.calendar_data import MAX_BS_YEAR, MIN_BS_YEAR
+from nepkit.convert import MAX_AD_DATE, MIN_AD_DATE, BSDate, ad_to_bs, bs_to_ad
+from nepkit.exceptions import DateOutOfRangeError, InvalidDateError
+from nepkit.render import (
+    MonthGrid,
+    ad_month_grid,
+    block_width,
+    bs_month_grid,
+    render_body_markup,
+    render_plain,
+)
+
+EXIT_INVALID_DATE: Final[int] = 3
+EXIT_OUT_OF_RANGE: Final[int] = 4
+
+_DATE_PARTS: Final[int] = 3
+
+app = typer.Typer(
+    name="nepkit",
+    help="Bikram Sambat (BS) <-> Gregorian (AD) date conversion.",
+)
+
+# figlet "standard", composed glyph by glyph so the columns actually line up.
+_ASCII_TITLE: Final[str] = r"""
+                      _     _  _
+ _ __    ___   _ __  | | __(_)| |_
+| '_ \  / _ \ | '_ \ | |/ /| || __|
+| | | ||  __/ | |_) ||   < | || |_
+|_| |_| \___| | .__/ |_|\_\|_| \__|
+              |_|"""
+
+_PROMPT: Final[str] = "nepkit> "
+_QUIT_WORDS: Final[frozenset[str]] = frozenset({"quit", "exit", "q"})
+# Prompt-only words. They are not subcommands because they mean nothing outside
+# a session -- `nepkit clear` should stay a usage error, not clear your screen.
+_CLEAR_WORDS: Final[frozenset[str]] = frozenset({"clear", "cls"})
+_HISTORY_LENGTH: Final[int] = 1000
+
+
+class ColorMode(StrEnum):
+    """When to dress up calendar output. Grids only; conversions are never coloured."""
+
+    auto = "auto"
+    always = "always"
+    never = "never"
+
+
+def _today() -> date:
+    """Seam for tests. Patch this rather than the clock itself."""
+    return date.today()
+
+
+def _stdin_is_interactive() -> bool:
+    """Seam for tests, and the guard that keeps `nepkit` usable in a pipeline."""
+    return sys.stdin.isatty()
+
+
+def _enable_line_editing() -> bool:
+    """Give input() cursor keys and history by importing readline.
+
+    The import *is* the mechanism: readline hooks itself into input(), so
+    Up/Down recall and Ctrl-A/Ctrl-E editing arrive without another line of
+    code. It only engages on a real terminal, which is why no test can observe
+    the recall itself.
+
+    Absent on Windows, where the prompt keeps working without editing.
+    """
+    try:
+        import readline
+    except ImportError:
+        return False
+    readline.set_history_length(_HISTORY_LENGTH)
+    return True
+
+
+def _dispatch(line: str) -> None:
+    """Run one REPL line through the same command table the shell uses.
+
+    standalone_mode=False makes Typer return the exit code instead of calling
+    sys.exit, so a failing command ends the line rather than the session.
+    """
+    try:
+        get_command(app).main(shlex.split(line), prog_name="nepkit", standalone_mode=False)
+    except Exception as exc:
+        # Deliberately broad. A typo must not throw the user out of the session,
+        # and Typer's usage errors live in typer._click.exceptions -- a private
+        # module this should not be importing to name them precisely.
+        typer.echo(f"error: {exc}", err=True)
+
+
+def _today_line() -> str:
+    """Today in both calendars, or a note that it is off the end of the table.
+
+    Decorating the banner must never stop the session from opening, which it
+    would once the clock passes MAX_AD_DATE in 2034.
+    """
+    ad = _today()
+    if not (MIN_AD_DATE <= ad <= MAX_AD_DATE):
+        return f"[dim]Today [/dim] AD {ad.isoformat()}  [dim](outside the supported range)[/dim]"
+    return f"[dim]Today [/dim] BS [bold]{_format_bs(ad_to_bs(ad))}[/bold]   AD {ad.isoformat()}"
+
+
+def _print_banner(*, editing: bool) -> None:
+    # A plain Console, not force_terminal: the REPL needs stdin to be a tty but
+    # stdout can still be redirected, and then this should come out unstyled.
+    console = Console()
+    console.print(_ASCII_TITLE, style="bold cyan", markup=False, highlight=False)
+    # Flush left, so the info block lines up with the wordmark's left edge.
+    console.print(
+        f"[bold]nepkit[/bold] [dim]v{version('nepkit')}[/dim] "
+        f"[dim]-[/dim] Bikram Sambat (BS) <-> Gregorian (AD) date conversion",
+        soft_wrap=True,
+        highlight=False,
+    )
+    console.print(_today_line(), soft_wrap=True, highlight=False)
+    hint = "  Up/Down recalls history." if editing else ""
+    console.print(
+        f"\n[dim]Type a command, 'help', 'clear', or 'quit'.{hint}[/dim]",
+        soft_wrap=True,
+        highlight=False,
+    )
+    console.print()
+
+
+def _clear_screen() -> None:
+    """Wipe the terminal.
+
+    A no-op when stdout is redirected, so a session whose output is being
+    captured never has escape sequences written into the capture.
+    """
+    Console().clear()
+
+
+def _run_repl() -> None:
+    editing = _enable_line_editing()
+    _clear_screen()
+    _print_banner(editing=editing)
+    while True:
+        try:
+            line = input(_PROMPT).strip()
+        except EOFError:  # Ctrl-D
+            typer.echo("")
+            return
+        except KeyboardInterrupt:  # Ctrl-C abandons the line, not the session
+            typer.echo("")
+            continue
+        if not line:
+            continue
+        word = line.lower()
+        if word in _QUIT_WORDS:
+            return
+        if word in _CLEAR_WORDS:
+            _clear_screen()
+            _print_banner(editing=editing)
+            continue
+        _dispatch("--help" if word == "help" else line)
+
+
+@app.callback(invoke_without_command=True)
+def main(ctx: typer.Context) -> None:
+    """Bikram Sambat <-> Gregorian date conversion."""
+    if ctx.invoked_subcommand is not None:
+        return
+    if not _stdin_is_interactive():
+        # No terminal means no prompt: printing help and exiting 2 keeps the
+        # old behaviour for scripts, which would otherwise block on stdin.
+        typer.echo(ctx.get_help())
+        raise typer.Exit(2)
+    _run_repl()
+
+
+@contextmanager
+def _reported_as_exit_code() -> Generator[None, None, None]:
+    """Turn nepkit's date errors into stderr messages and distinct exit codes."""
+    try:
+        yield
+    except InvalidDateError as exc:
+        typer.echo(str(exc), err=True)
+        raise typer.Exit(EXIT_INVALID_DATE) from exc
+    except DateOutOfRangeError as exc:
+        typer.echo(str(exc), err=True)
+        raise typer.Exit(EXIT_OUT_OF_RANGE) from exc
+
+
+def _parse_ymd(text: str) -> tuple[int, int, int]:
+    """Parse YYYY-MM-DD without regard to which calendar it belongs to.
+
+    Both directions go through this so that identical garbage produces an
+    identical exit code either way.
+    """
+    parts = text.split("-")
+    if len(parts) != _DATE_PARTS or not all(part.isdigit() for part in parts):
+        raise InvalidDateError(f"{text!r} is not a date in YYYY-MM-DD form")
+    year, month, day = (int(part) for part in parts)
+    return year, month, day
+
+
+def _parse_bs(text: str) -> BSDate:
+    year, month, day = _parse_ymd(text)
+    return BSDate(year=year, month=month, day=day)  # validates against the table
+
+
+def _parse_ad(text: str) -> date:
+    year, month, day = _parse_ymd(text)
+    try:
+        return date(year, month, day)
+    except ValueError as exc:
+        raise InvalidDateError(f"AD {text} is not a real Gregorian date") from exc
+
+
+def _format_bs(bs: BSDate) -> str:
+    return f"{bs.year:04d}-{bs.month:02d}-{bs.day:02d}"
+
+
+def _emit_grid(grid: MonthGrid, kind: str, *, as_json: bool, color: ColorMode) -> None:
+    if as_json:
+        typer.echo(
+            json.dumps(
+                {
+                    "calendar": kind,
+                    "title": grid.title,
+                    "subtitle": grid.subtitle,
+                    "today": grid.today,
+                    "weeks": [list(week) for week in grid.weeks],
+                }
+            )
+        )
+        return
+
+    coloured = color is ColorMode.always or (color is ColorMode.auto and Console().is_terminal)
+    if not coloured:
+        # render_plain, never render_body_markup: piped output stays inert, so a
+        # grid does not change shape on the one day a month today falls in it.
+        typer.echo(render_plain(grid))
+        return
+
+    # The subtitle goes inside the panel, not in its border: panel furniture is
+    # clipped to the body width, and a span like "Ashadh 17 - Shrawan 16, 2081"
+    # is wider than the 27-column grid, so the border ate the year.
+    body = f"[dim]{grid.subtitle.center(block_width(grid))}[/dim]\n{render_body_markup(grid)}"
+    Console(force_terminal=True).print(
+        Panel.fit(body, title=f"[bold]{grid.title}[/bold]", border_style="cyan")
+    )
+
+
+JsonOption = Annotated[bool, typer.Option("--json", help="Emit machine-readable JSON.")]
+ColorOption = Annotated[ColorMode, typer.Option("--color", help="When to colourise the grid.")]
+YearArg = Annotated[int | None, typer.Argument(help="Year. Defaults to the current one.")]
+MonthArg = Annotated[int | None, typer.Argument(help="Month, 1-12. Defaults to the current one.")]
+
+
+@app.command("bs2ad")
+def bs_to_ad_command(
+    bs_date: Annotated[str, typer.Argument(metavar="BS_DATE", help="Bikram Sambat YYYY-MM-DD.")],
+    as_json: JsonOption = False,
+) -> None:
+    """Convert a Bikram Sambat date to Gregorian."""
+    with _reported_as_exit_code():
+        bs = _parse_bs(bs_date)
+        ad = bs_to_ad(bs)
+    if as_json:
+        typer.echo(json.dumps({"bs": _format_bs(bs), "ad": ad.isoformat()}))
+    else:
+        typer.echo(ad.isoformat())
+
+
+@app.command("ad2bs")
+def ad_to_bs_command(
+    ad_date: Annotated[str, typer.Argument(metavar="AD_DATE", help="Gregorian YYYY-MM-DD.")],
+    as_json: JsonOption = False,
+) -> None:
+    """Convert a Gregorian date to Bikram Sambat."""
+    with _reported_as_exit_code():
+        ad = _parse_ad(ad_date)
+        bs = ad_to_bs(ad)
+    if as_json:
+        typer.echo(json.dumps({"bs": _format_bs(bs), "ad": ad.isoformat()}))
+    else:
+        typer.echo(_format_bs(bs))
+
+
+@app.command("today")
+def today_command(as_json: JsonOption = False) -> None:
+    """Print today's date in both calendars."""
+    ad = _today()
+    with _reported_as_exit_code():
+        bs = ad_to_bs(ad)
+    if as_json:
+        typer.echo(json.dumps({"bs": _format_bs(bs), "ad": ad.isoformat()}))
+        return
+    # Two labelled lines, the same shape `range` prints, so the two commands
+    # that report a position in both calendars read alike.
+    typer.echo(f"BS {_format_bs(bs)}")
+    typer.echo(f"AD {ad.isoformat()}")
+
+
+@app.command("range")
+def range_command(as_json: JsonOption = False) -> None:
+    """Print the date range nepkit has data for."""
+    bs_min, bs_max = f"{MIN_BS_YEAR:04d}-01-01", _format_bs(ad_to_bs(MAX_AD_DATE))
+    if as_json:
+        typer.echo(
+            json.dumps(
+                {
+                    "bs": {"min": bs_min, "max": bs_max},
+                    "ad": {
+                        "min": MIN_AD_DATE.isoformat(),
+                        "max": MAX_AD_DATE.isoformat(),
+                    },
+                }
+            )
+        )
+        return
+    typer.echo(f"BS {bs_min} .. {bs_max}  (years {MIN_BS_YEAR}-{MAX_BS_YEAR})")
+    typer.echo(f"AD {MIN_AD_DATE.isoformat()} .. {MAX_AD_DATE.isoformat()}")
+
+
+@app.command("calbs")
+def calbs_command(
+    year: YearArg = None,
+    month: MonthArg = None,
+    as_json: JsonOption = False,
+    color: ColorOption = ColorMode.auto,
+) -> None:
+    """Display a Bikram Sambat month."""
+    with _reported_as_exit_code():
+        current = ad_to_bs(_today()) if MIN_AD_DATE <= _today() <= MAX_AD_DATE else None
+        if year is None or month is None:
+            if current is None:
+                raise DateOutOfRangeError(
+                    f"today ({_today().isoformat()}) is outside the convertible window, "
+                    "so there is no current BS month to default to"
+                )
+            year, month = year or current.year, month or current.month
+        grid = bs_month_grid(year, month, today=current)
+    _emit_grid(grid, "bs", as_json=as_json, color=color)
+
+
+@app.command("calad")
+def calad_command(
+    year: YearArg = None,
+    month: MonthArg = None,
+    as_json: JsonOption = False,
+    color: ColorOption = ColorMode.auto,
+) -> None:
+    """Display a Gregorian month."""
+    with _reported_as_exit_code():
+        today = _today()
+        grid = ad_month_grid(year or today.year, month or today.month, today=today)
+    _emit_grid(grid, "ad", as_json=as_json, color=color)

nepkit/convert.py

@@ -0,0 +1,52 @@
+"""Conversion between Bikram Sambat and Gregorian dates.
+
+Both directions collapse to a day count from calendar_data.ANCHOR and expand
+out the other side; the AD-side expander is datetime.date arithmetic.
+"""
+
+from dataclasses import dataclass
+from datetime import date, timedelta
+from typing import Final
+
+from nepkit.calendar_data import (
+    ANCHOR,
+    TOTAL_DAYS,
+    bs_from_days,
+    check_bs_date,
+    days_from_anchor,
+)
+from nepkit.exceptions import DateOutOfRangeError
+
+# Computed from ANCHOR plus the table's length, never written down as literals.
+# ANCHOR.ad_date is the only AD fact in the package that cannot be derived (see
+# data/DATA.md); a second AD literal here would be free to drift away from it.
+MIN_AD_DATE: Final[date] = ANCHOR.ad_date
+MAX_AD_DATE: Final[date] = ANCHOR.ad_date + timedelta(days=TOTAL_DAYS - 1)
+
+
+@dataclass(frozen=True, slots=True)
+class BSDate:
+    """A Bikram Sambat date, validated on construction against the bundled table."""
+
+    year: int
+    month: int
+    day: int
+
+    def __post_init__(self) -> None:
+        check_bs_date(self.year, self.month, self.day)
+
+
+def bs_to_ad(bs: BSDate) -> date:
+    """Convert a Bikram Sambat date to its Gregorian equivalent."""
+    return ANCHOR.ad_date + timedelta(days=days_from_anchor(bs.year, bs.month, bs.day))
+
+
+def ad_to_bs(ad: date) -> BSDate:
+    """Convert a Gregorian date to its Bikram Sambat equivalent."""
+    if not (MIN_AD_DATE <= ad <= MAX_AD_DATE):
+        raise DateOutOfRangeError(
+            f"AD {ad.isoformat()} is outside the convertible window "
+            f"{MIN_AD_DATE.isoformat()} through {MAX_AD_DATE.isoformat()}"
+        )
+    year, month, day = bs_from_days((ad - ANCHOR.ad_date).days)
+    return BSDate(year=year, month=month, day=day)