nepkit 0.2.0__tar.gz → 0.3.0__tar.gz

{nepkit-0.2.0 → nepkit-0.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: nepkit
-Version: 0.2.0
+Version: 0.3.0
 Summary: Typed Bikram Sambat ↔ Gregorian date conversion, as a library and a CLI.
 Keywords: nepal,bikram-sambat,nepali-date,calendar,cli
 Author: Kritagya
@@ -43,8 +43,10 @@ command-line tool.
 [![Python](https://img.shields.io/pypi/pyversions/nepkit)](https://pypi.org/project/nepkit/)
 [![License](https://img.shields.io/pypi/l/nepkit)](https://github.com/akakritagya/nepkit/blob/main/LICENSE)
 
-> **Status:** first release. The library and CLI both work and are tested; the
-> API may still change before 1.0.
+> **Status:** published, pre-1.0. The library and CLI both work and are tested,
+> but the API and the CLI's output shapes may still change — 0.2.0 appended the
+> weekday to `bs2ad`, `ad2bs`, and `today`. Pin a version if you script against
+> stdout, or read the first field: the date still starts the line.
 
 [**DEMO.md**](https://github.com/akakritagya/nepkit/blob/main/DEMO.md) walks
 through every command, option, and failure mode with real captured output.

{nepkit-0.2.0 → nepkit-0.3.0}/README.md

@@ -17,8 +17,10 @@ command-line tool.
 [![Python](https://img.shields.io/pypi/pyversions/nepkit)](https://pypi.org/project/nepkit/)
 [![License](https://img.shields.io/pypi/l/nepkit)](https://github.com/akakritagya/nepkit/blob/main/LICENSE)
 
-> **Status:** first release. The library and CLI both work and are tested; the
-> API may still change before 1.0.
+> **Status:** published, pre-1.0. The library and CLI both work and are tested,
+> but the API and the CLI's output shapes may still change — 0.2.0 appended the
+> weekday to `bs2ad`, `ad2bs`, and `today`. Pin a version if you script against
+> stdout, or read the first field: the date still starts the line.
 
 [**DEMO.md**](https://github.com/akakritagya/nepkit/blob/main/DEMO.md) walks
 through every command, option, and failure mode with real captured output.

{nepkit-0.2.0 → nepkit-0.3.0}/pyproject.toml

@@ -28,7 +28,7 @@ license-files = ["LICENSE"]
 name = "nepkit"
 readme = "README.md"
 requires-python = ">=3.12"
-version = "0.2.0"
+version = "0.3.0"
 
 [[project.authors]]
 name = "Kritagya"
@@ -69,8 +69,15 @@ select = [
     "SIM",
     "ANN",
     "RUF",
+    "D",
 ]
 
+[tool.ruff.lint.pydocstyle]
+convention = "numpy"
+
+[tool.ruff.lint.per-file-ignores]
+"tests/*" = ["D"]
+
 [tool.ruff.format]
 docstring-code-format = true
 line-ending = "lf"

{nepkit-0.2.0 → nepkit-0.3.0}/pyproject.toml.orig

@@ -27,7 +27,7 @@ license-files = ["LICENSE"]
 name = "nepkit"
 readme = "README.md"
 requires-python = ">=3.12"
-version = "0.2.0"
+version = "0.3.0"
 
 [project.urls]
 Homepage = "https://github.com/akakritagya/nepkit"
@@ -56,7 +56,14 @@ line-length = 100
 target-version = "py312"
 
 [tool.ruff.lint]
-select = ["E", "F", "I", "UP", "B", "SIM", "ANN", "RUF"]
+select = ["E", "F", "I", "UP", "B", "SIM", "ANN", "RUF", "D"]
+
+[tool.ruff.lint.pydocstyle]
+convention = "numpy"
+
+[tool.ruff.lint.per-file-ignores]
+# Tests document intent through names and assertions, not docstrings.
+"tests/*" = ["D"]
 
 [tool.ruff.format]
 docstring-code-format = true

{nepkit-0.2.0 → nepkit-0.3.0}/src/nepkit/__init__.py

@@ -4,6 +4,8 @@ Everything a caller needs is re-exported here, so the module layout underneath
 stays free to change without breaking imports.
 """
 
+from importlib.metadata import version
+
 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 (
@@ -14,6 +16,10 @@ from nepkit.exceptions import (
     NepkitError,
 )
 
+# Read from the installed package's metadata rather than duplicated here, so
+# pyproject.toml's `version` stays the one place it can drift out of sync.
+__version__: str = version("nepkit")
+
 __all__ = [
     "BS_MONTH_NAMES",
     "MAX_AD_DATE",
@@ -26,6 +32,7 @@ __all__ = [
     "DateOutOfRangeError",
     "InvalidDateError",
     "NepkitError",
+    "__version__",
     "ad_to_bs",
     "bs_to_ad",
     "days_in_month",

{nepkit-0.2.0 → nepkit-0.3.0}/src/nepkit/calendar_data.py

@@ -40,12 +40,28 @@ _MAX_DAYS_IN_YEAR: Final[int] = 366
 
 @dataclass(frozen=True, slots=True)
 class BSYearData:
-    """One BS year's month lengths, validated on construction."""
+    """One BS year's month lengths, validated on construction.
+
+    Parameters
+    ----------
+    year : int
+        The Bikram Sambat year this row describes.
+    months : tuple of int
+        The number of days in each of the year's 12 months, in order.
+
+    Raises
+    ------
+    CalendarDataError
+        If the row does not have exactly 12 months, if any month's day
+        count is outside `[29, 32]`, or if the months do not sum to a
+        plausible year length.
+    """
 
     year: int
     months: tuple[int, ...]
 
     def __post_init__(self) -> None:
+        """Validate the month count, each month's length, and the year total."""
         if len(self.months) != _MONTHS_PER_YEAR:
             raise CalendarDataError(
                 f"BS {self.year}: expected {_MONTHS_PER_YEAR} months, got {len(self.months)}"
@@ -65,6 +81,19 @@ class BSYearData:
 
 
 def _load_years() -> tuple[BSYearData, ...]:
+    """Load and validate calendar.json into a sorted tuple of year rows.
+
+    Returns
+    -------
+    tuple of BSYearData
+        Every year row in calendar.json, sorted by year.
+
+    Raises
+    ------
+    CalendarDataError
+        If calendar.json is missing, not valid JSON, empty, or contains a
+        malformed row.
+    """
     raw = resources.files("nepkit.data").joinpath("calendar.json").read_text(encoding="utf-8")
     try:
         rows: object = json.loads(raw)
@@ -92,6 +121,18 @@ def _load_years() -> tuple[BSYearData, ...]:
 
 
 def _check_contiguous(years: tuple[BSYearData, ...]) -> None:
+    """Raise unless `years` covers a run of consecutive BS years.
+
+    Parameters
+    ----------
+    years : tuple of BSYearData
+        Year rows, assumed sorted by year.
+
+    Raises
+    ------
+    CalendarDataError
+        If two rows share a year, or a year is skipped between rows.
+    """
     for previous, current in pairwise(years):
         if current.year == previous.year:
             raise CalendarDataError(f"calendar.json has a duplicate row for BS {current.year}")
@@ -102,7 +143,22 @@ def _check_contiguous(years: tuple[BSYearData, ...]) -> None:
 
 
 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."""
+    """Compute the day offset from the anchor to the start of each BS year.
+
+    Days from the anchor to the start of each BS year, so bs_to_ad never
+    sums a range at call time.
+
+    Parameters
+    ----------
+    years : tuple of BSYearData
+        Year rows, assumed sorted by year and contiguous.
+
+    Returns
+    -------
+    Mapping of int to int
+        Each year mapped to the number of days between the first year's
+        start and that year's start.
+    """
     offsets: dict[int, int] = {}
     running = 0
     for year_data in years:
@@ -131,7 +187,19 @@ 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."""
+    """The one verified BS<->AD correspondence the whole module hangs on.
+
+    Parameters
+    ----------
+    bs_year : int
+        The anchor's Bikram Sambat year.
+    bs_month : int
+        The anchor's Bikram Sambat month.
+    bs_day : int
+        The anchor's Bikram Sambat day.
+    ad_date : date
+        The Gregorian date equivalent to `(bs_year, bs_month, bs_day)`.
+    """
 
     bs_year: int
     bs_month: int
@@ -140,7 +208,23 @@ class Anchor:
 
 
 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."""
+    """Raise unless `anchor` is the first day of `min_year`.
+
+    The cumulative offset table starts at min_year, so the anchor must be
+    its 1/1.
+
+    Parameters
+    ----------
+    anchor : Anchor
+        The anchor to check.
+    min_year : int
+        The bundled table's first BS year.
+
+    Raises
+    ------
+    CalendarDataError
+        If `anchor` is not BS `min_year`-01-01.
+    """
     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 "
@@ -159,7 +243,27 @@ _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."""
+    """Look up the number of days in a Bikram Sambat month.
+
+    Parameters
+    ----------
+    year : int
+        The Bikram Sambat year.
+    month : int
+        The Bikram Sambat month, 1-12.
+
+    Returns
+    -------
+    int
+        The number of days in that month.
+
+    Raises
+    ------
+    DateOutOfRangeError
+        If `year` is outside the bundled table's range.
+    InvalidDateError
+        If `month` is outside `[1, 12]`.
+    """
     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}]"
@@ -170,21 +274,78 @@ def days_in_month(year: int, month: int) -> int:
 
 
 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."""
+    """Raise unless `(year, month, day)` is a real BS date inside the bundled range.
+
+    Parameters
+    ----------
+    year : int
+        The Bikram Sambat year.
+    month : int
+        The Bikram Sambat month, 1-12.
+    day : int
+        The day of the month.
+
+    Raises
+    ------
+    DateOutOfRangeError
+        If `year` is outside the bundled table's range.
+    InvalidDateError
+        If `month` or `day` is not a real month or day for that year.
+    """
     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."""
+    """Count the days from ANCHOR to the given BS date.
+
+    The one primitive bs_to_ad needs.
+
+    Parameters
+    ----------
+    year : int
+        The Bikram Sambat year.
+    month : int
+        The Bikram Sambat month, 1-12.
+    day : int
+        The day of the month.
+
+    Returns
+    -------
+    int
+        The number of days between ANCHOR and `(year, month, day)`.
+
+    Raises
+    ------
+    DateOutOfRangeError
+        If `year` is outside the bundled table's range.
+    InvalidDateError
+        If `(year, month, day)` is not a real BS date.
+    """
     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."""
+    """Invert days_from_anchor: find the BS date that many days after ANCHOR.
+
+    Parameters
+    ----------
+    days : int
+        Days since ANCHOR.
+
+    Returns
+    -------
+    tuple of (int, int, int)
+        The `(year, month, day)` that many days after ANCHOR.
+
+    Raises
+    ------
+    DateOutOfRangeError
+        If `days` is outside `[0, TOTAL_DAYS)`.
+    """
     if not (0 <= days < TOTAL_DAYS):
         raise DateOutOfRangeError(
             f"{days} days from the anchor is outside [0, {TOTAL_DAYS}) — the bundled "

{nepkit-0.2.0 → nepkit-0.3.0}/src/nepkit/cli.py

@@ -4,6 +4,8 @@ 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.
 
+Notes
+-----
 Exit codes:
 
     0  success
@@ -74,7 +76,17 @@ _HISTORY_LENGTH: Final[int] = 1000
 
 
 class ColorMode(StrEnum):
-    """When to dress up calendar output. Grids only; conversions are never coloured."""
+    """When to dress up calendar output. Grids only; conversions are never coloured.
+
+    Attributes
+    ----------
+    auto
+        Colour only when stdout is a terminal.
+    always
+        Always colour, even when redirected.
+    never
+        Never colour.
+    """
 
     auto = "auto"
     always = "always"
@@ -82,12 +94,28 @@ class ColorMode(StrEnum):
 
 
 def _today() -> date:
-    """Seam for tests. Patch this rather than the clock itself."""
+    """Return today's date.
+
+    Seam for tests. Patch this rather than the clock itself.
+
+    Returns
+    -------
+    date
+        Today's Gregorian date.
+    """
     return date.today()
 
 
 def _stdin_is_interactive() -> bool:
-    """Seam for tests, and the guard that keeps `nepkit` usable in a pipeline."""
+    """Report whether stdin is a live terminal.
+
+    Seam for tests, and the guard that keeps `nepkit` usable in a pipeline.
+
+    Returns
+    -------
+    bool
+        True if stdin is a tty.
+    """
     return sys.stdin.isatty()
 
 
@@ -104,6 +132,11 @@ def _enable_line_editing() -> bool:
     The except clause still matters: pyreadline3 drives the Win32 console API
     and can fail where Python has no real console, and the prompt has to keep
     working when it does.
+
+    Returns
+    -------
+    bool
+        True if line editing was successfully enabled.
     """
     try:
         import readline
@@ -123,6 +156,12 @@ def _dispatch(line: str) -> None:
 
     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.
+
+    Parameters
+    ----------
+    line : str
+        One line of input, shell-split and dispatched as a `nepkit`
+        invocation.
     """
     try:
         get_command(app).main(shlex.split(line), prog_name="nepkit", standalone_mode=False)
@@ -134,10 +173,15 @@ def _dispatch(line: str) -> None:
 
 
 def _today_line() -> str:
-    """Today in both calendars, or a note that it is off the end of the table.
+    """Format 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.
+
+    Returns
+    -------
+    str
+        A rich-markup line for the REPL banner.
     """
     ad = _today()
     day = weekday_name(ad)
@@ -151,6 +195,14 @@ def _today_line() -> str:
 
 
 def _print_banner(*, editing: bool) -> None:
+    """Print the ASCII wordmark, version, today's date, and usage hint.
+
+    Parameters
+    ----------
+    editing : bool
+        Whether line editing is active, to decide if the Up/Down hint is
+        shown.
+    """
     # 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()
@@ -182,6 +234,7 @@ def _clear_screen() -> None:
 
 
 def _run_repl() -> None:
+    """Run the interactive REPL until the user quits or sends EOF."""
     editing = _enable_line_editing()
     _clear_screen()
     _print_banner(editing=editing)
@@ -206,9 +259,53 @@ def _run_repl() -> None:
         _dispatch("--help" if word == "help" else line)
 
 
+def _version_callback(show_version: bool) -> None:
+    """Print the installed version and exit, if `show_version` is set.
+
+    is_eager on the option that drives this means it fires before Typer
+    parses anything else, so `nepkit --version` works even though no
+    subcommand was given.
+
+    Parameters
+    ----------
+    show_version : bool
+        Whether `--version` was passed.
+
+    Raises
+    ------
+    typer.Exit
+        Always, when `show_version` is True -- printing the version is the
+        entire command.
+    """
+    if show_version:
+        typer.echo(f"nepkit {version('nepkit')}")
+        raise typer.Exit()
+
+
+VersionOption = Annotated[
+    bool,
+    typer.Option(
+        "--version",
+        callback=_version_callback,
+        is_eager=True,
+        help="Show the version and exit.",
+    ),
+]
+
+
 @app.callback(invoke_without_command=True)
-def main(ctx: typer.Context) -> None:
-    """Bikram Sambat <-> Gregorian date conversion."""
+def main(ctx: typer.Context, show_version: VersionOption = False) -> None:
+    """Bikram Sambat <-> Gregorian date conversion.
+
+    Parameters
+    ----------
+    ctx : typer.Context
+        Typer's invocation context, used to detect whether a subcommand was
+        given.
+    show_version : bool, optional
+        Whether `--version` was passed. Handled entirely by
+        `_version_callback`; unused here beyond declaring the option.
+    """
     if ctx.invoked_subcommand is not None:
         return
     if not _stdin_is_interactive():
@@ -221,7 +318,19 @@ def main(ctx: typer.Context) -> None:
 
 @contextmanager
 def _reported_as_exit_code() -> Generator[None, None, None]:
-    """Turn nepkit's date errors into stderr messages and distinct exit codes."""
+    """Turn nepkit's date errors into stderr messages and distinct exit codes.
+
+    Yields
+    ------
+    None
+        Nothing; used only for its exception handling.
+
+    Raises
+    ------
+    typer.Exit
+        With `EXIT_INVALID_DATE` or `EXIT_OUT_OF_RANGE`, after printing the
+        original error to stderr.
+    """
     try:
         yield
     except InvalidDateError as exc:
@@ -237,6 +346,21 @@ def _parse_ymd(text: str) -> tuple[int, int, int]:
 
     Both directions go through this so that identical garbage produces an
     identical exit code either way.
+
+    Parameters
+    ----------
+    text : str
+        The date string to parse.
+
+    Returns
+    -------
+    tuple of (int, int, int)
+        The `(year, month, day)` parsed from `text`.
+
+    Raises
+    ------
+    InvalidDateError
+        If `text` is not in YYYY-MM-DD form.
     """
     parts = text.split("-")
     if len(parts) != _DATE_PARTS or not all(part.isdigit() for part in parts):
@@ -246,11 +370,47 @@ def _parse_ymd(text: str) -> tuple[int, int, int]:
 
 
 def _parse_bs(text: str) -> BSDate:
+    """Parse a Bikram Sambat date string.
+
+    Parameters
+    ----------
+    text : str
+        The date string, YYYY-MM-DD.
+
+    Returns
+    -------
+    BSDate
+        The parsed and validated BS date.
+
+    Raises
+    ------
+    InvalidDateError
+        If `text` is not a real BS date.
+    DateOutOfRangeError
+        If the year is outside the bundled table's range.
+    """
     year, month, day = _parse_ymd(text)
     return BSDate(year=year, month=month, day=day)  # validates against the table
 
 
 def _parse_ad(text: str) -> date:
+    """Parse a Gregorian date string.
+
+    Parameters
+    ----------
+    text : str
+        The date string, YYYY-MM-DD.
+
+    Returns
+    -------
+    date
+        The parsed Gregorian date.
+
+    Raises
+    ------
+    InvalidDateError
+        If `text` is not a real Gregorian date.
+    """
     year, month, day = _parse_ymd(text)
     try:
         return date(year, month, day)
@@ -259,10 +419,35 @@ def _parse_ad(text: str) -> date:
 
 
 def _format_bs(bs: BSDate) -> str:
+    """Format a BSDate as zero-padded YYYY-MM-DD.
+
+    Parameters
+    ----------
+    bs : BSDate
+        The date to format.
+
+    Returns
+    -------
+    str
+        The formatted date.
+    """
     return f"{bs.year:04d}-{bs.month:02d}-{bs.day:02d}"
 
 
 def _emit_grid(grid: MonthGrid, kind: str, *, as_json: bool, color: ColorMode) -> None:
+    """Print a month grid as JSON, plain text, or a coloured panel.
+
+    Parameters
+    ----------
+    grid : MonthGrid
+        The grid to print.
+    kind : str
+        "bs" or "ad", included in the JSON output to identify the calendar.
+    as_json : bool
+        Whether to emit machine-readable JSON instead of a rendered grid.
+    color : ColorMode
+        When to colourise the grid; ignored when `as_json` is True.
+    """
     if as_json:
         typer.echo(
             json.dumps(
@@ -299,12 +484,20 @@ YearArg = Annotated[int | None, typer.Argument(help="Year. Defaults to the curre
 MonthArg = Annotated[int | None, typer.Argument(help="Month, 1-12. Defaults to the current one.")]
 
 
-@app.command("bs2ad")
+@app.command("bs2ad", help="Convert a Bikram Sambat date to Gregorian.")
 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."""
+    """Convert a Bikram Sambat date to Gregorian.
+
+    Parameters
+    ----------
+    bs_date : str
+        The Bikram Sambat date, YYYY-MM-DD.
+    as_json : bool, optional
+        Emit machine-readable JSON instead of plain text. Default is False.
+    """
     with _reported_as_exit_code():
         bs = _parse_bs(bs_date)
         ad = bs_to_ad(bs)
@@ -316,12 +509,20 @@ def bs_to_ad_command(
         typer.echo(f"{ad.isoformat()} {weekday_name(ad)}")
 
 
-@app.command("ad2bs")
+@app.command("ad2bs", help="Convert a Gregorian date to Bikram Sambat.")
 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."""
+    """Convert a Gregorian date to Bikram Sambat.
+
+    Parameters
+    ----------
+    ad_date : str
+        The Gregorian date, YYYY-MM-DD.
+    as_json : bool, optional
+        Emit machine-readable JSON instead of plain text. Default is False.
+    """
     with _reported_as_exit_code():
         ad = _parse_ad(ad_date)
         bs = ad_to_bs(ad)
@@ -333,9 +534,15 @@ def ad_to_bs_command(
         typer.echo(f"{_format_bs(bs)} {weekday_name(ad)}")
 
 
-@app.command("today")
+@app.command("today", help="Print today's date in both calendars.")
 def today_command(as_json: JsonOption = False) -> None:
-    """Print today's date in both calendars."""
+    """Print today's date in both calendars.
+
+    Parameters
+    ----------
+    as_json : bool, optional
+        Emit machine-readable JSON instead of plain text. Default is False.
+    """
     ad = _today()
     with _reported_as_exit_code():
         bs = ad_to_bs(ad)
@@ -351,9 +558,15 @@ def today_command(as_json: JsonOption = False) -> None:
     typer.echo(f"AD {ad.isoformat()} {day}")
 
 
-@app.command("range")
+@app.command("range", help="Print the date range nepkit has data for.")
 def range_command(as_json: JsonOption = False) -> None:
-    """Print the date range nepkit has data for."""
+    """Print the date range nepkit has data for.
+
+    Parameters
+    ----------
+    as_json : bool, optional
+        Emit machine-readable JSON instead of plain text. Default is False.
+    """
     bs_min, bs_max = f"{MIN_BS_YEAR:04d}-01-01", _format_bs(ad_to_bs(MAX_AD_DATE))
     if as_json:
         typer.echo(
@@ -372,14 +585,27 @@ def range_command(as_json: JsonOption = False) -> None:
     typer.echo(f"AD {MIN_AD_DATE.isoformat()} .. {MAX_AD_DATE.isoformat()}")
 
 
-@app.command("calbs")
+@app.command("calbs", help="Display a Bikram Sambat month.")
 def calbs_command(
     year: YearArg = None,
     month: MonthArg = None,
     as_json: JsonOption = False,
     color: ColorOption = ColorMode.auto,
 ) -> None:
-    """Display a Bikram Sambat month."""
+    """Display a Bikram Sambat month.
+
+    Parameters
+    ----------
+    year : int or None, optional
+        The BS year. Defaults to the current one.
+    month : int or None, optional
+        The BS month, 1-12. Defaults to the current one.
+    as_json : bool, optional
+        Emit machine-readable JSON instead of a rendered grid. Default is
+        False.
+    color : ColorMode, optional
+        When to colourise the grid. Default is `ColorMode.auto`.
+    """
     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:
@@ -393,14 +619,27 @@ def calbs_command(
     _emit_grid(grid, "bs", as_json=as_json, color=color)
 
 
-@app.command("calad")
+@app.command("calad", help="Display a Gregorian month.")
 def calad_command(
     year: YearArg = None,
     month: MonthArg = None,
     as_json: JsonOption = False,
     color: ColorOption = ColorMode.auto,
 ) -> None:
-    """Display a Gregorian month."""
+    """Display a Gregorian month.
+
+    Parameters
+    ----------
+    year : int or None, optional
+        The Gregorian year. Defaults to the current one.
+    month : int or None, optional
+        The Gregorian month, 1-12. Defaults to the current one.
+    as_json : bool, optional
+        Emit machine-readable JSON instead of a rendered grid. Default is
+        False.
+    color : ColorMode, optional
+        When to colourise the grid. Default is `ColorMode.auto`.
+    """
     with _reported_as_exit_code():
         today = _today()
         grid = ad_month_grid(year or today.year, month or today.month, today=today)

{nepkit-0.2.0 → nepkit-0.3.0}/src/nepkit/convert.py

@@ -26,23 +26,68 @@ 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."""
+    """A Bikram Sambat date, validated on construction against the bundled table.
+
+    Parameters
+    ----------
+    year : int
+        The Bikram Sambat year.
+    month : int
+        The Bikram Sambat month, 1-12.
+    day : int
+        The day of the month.
+
+    Raises
+    ------
+    InvalidDateError
+        If `(year, month, day)` is not a real BS date.
+    DateOutOfRangeError
+        If `year` is outside the bundled table's range.
+    """
 
     year: int
     month: int
     day: int
 
     def __post_init__(self) -> None:
+        """Validate the date against the bundled table."""
         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."""
+    """Convert a Bikram Sambat date to its Gregorian equivalent.
+
+    Parameters
+    ----------
+    bs : BSDate
+        The Bikram Sambat date to convert.
+
+    Returns
+    -------
+    date
+        The equivalent Gregorian date.
+    """
     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."""
+    """Convert a Gregorian date to its Bikram Sambat equivalent.
+
+    Parameters
+    ----------
+    ad : date
+        The Gregorian date to convert.
+
+    Returns
+    -------
+    BSDate
+        The equivalent Bikram Sambat date.
+
+    Raises
+    ------
+    DateOutOfRangeError
+        If `ad` is outside `[MIN_AD_DATE, MAX_AD_DATE]`.
+    """
     if not (MIN_AD_DATE <= ad <= MAX_AD_DATE):
         raise DateOutOfRangeError(
             f"AD {ad.isoformat()} is outside the convertible window "

nepkit-0.3.0/src/nepkit/data/__init__.py

@@ -0,0 +1 @@
+"""Bundled calendar data package: calendar.json and its provenance notes in DATA.md."""

nepkit-0.3.0/src/nepkit/exceptions.py

@@ -0,0 +1,34 @@
+"""Nepkit's exception hierarchy.
+
+Every error nepkit raises descends from `NepkitError`, split into two
+branches: a malformed bundled calendar table (`CalendarDataError`, raised at
+import) and a bad date input (`DateError`, raised at call time), further
+split into `InvalidDateError` and `DateOutOfRangeError`.
+"""
+
+
+class NepkitError(Exception):
+    """Base class for every error nepkit raises."""
+
+
+class CalendarDataError(NepkitError):
+    """Raised when the bundled calendar table is malformed.
+
+    Raised at import time, since the table is loaded and validated as soon
+    as `nepkit.calendar_data` is imported.
+    """
+
+
+class DateError(NepkitError):
+    """Base class for date-input problems."""
+
+
+class InvalidDateError(DateError):
+    """Raised when a date is syntactically parseable but not a real BS date.
+
+    For example, BS month 13, or day 33 in a 32-day month.
+    """
+
+
+class DateOutOfRangeError(DateError):
+    """Raised when a date is real but outside the bundled table's range."""

{nepkit-0.2.0 → nepkit-0.3.0}/src/nepkit/render.py

@@ -37,22 +37,48 @@ TODAY_STYLE: Final[str] = f"bold bright_{ACCENT}"
 
 @dataclass(frozen=True, slots=True)
 class MonthGrid:
-    """One month laid out as Sunday-first weeks, plus its two heading lines."""
+    """One month laid out as Sunday-first weeks, plus its two heading lines.
+
+    Parameters
+    ----------
+    title : str
+        The month and year, e.g. "Shrawan 2081".
+    subtitle : str
+        The span this month covers in the other calendar.
+    weeks : tuple of tuple of (int or None)
+        Each week as 7 cells, Sunday first. A cell is None where the month
+        has no day, either before day 1 or after the last day.
+    today : int or None, optional
+        Day of this month to highlight, or None when today falls outside it.
+        Default is None.
+    """
 
     title: str
     subtitle: str
     weeks: tuple[tuple[int | None, ...], ...]
     today: int | None = None
-    """Day of this month to highlight, or None when today falls outside it."""
 
 
 def _sunday_first_index(day: date) -> int:
-    """Python weeks start Monday; Nepali (and `cal`) calendars start Sunday."""
+    """Map a Gregorian date to its Sunday-first weekday index.
+
+    Python weeks start Monday; Nepali (and `cal`) calendars start Sunday.
+
+    Parameters
+    ----------
+    day : date
+        The date to index.
+
+    Returns
+    -------
+    int
+        0 for Sunday through 6 for Saturday.
+    """
     return (day.weekday() + 1) % _DAYS_PER_WEEK
 
 
 def weekday_name(day: date) -> str:
-    """Sunday-first weekday abbreviation for a Gregorian date.
+    """Look up the Sunday-first weekday abbreviation for a Gregorian date.
 
     Deliberately not strftime("%a"), which is locale-dependent: under
     LC_TIME=fr_FR that yields "mer." while the grid header still says "Wed".
@@ -60,11 +86,35 @@ def weekday_name(day: date) -> str:
     it sits under can never disagree, and the output is byte-identical on every
     machine -- which DEMO.md's captured blocks rely on, and CI now checks on
     three platforms.
+
+    Parameters
+    ----------
+    day : date
+        The date to name.
+
+    Returns
+    -------
+    str
+        A three-letter abbreviation, e.g. "Wed".
     """
     return WEEKDAY_ABBREVIATIONS[_sunday_first_index(day)]
 
 
 def _build_weeks(lead_blanks: int, total_days: int) -> tuple[tuple[int | None, ...], ...]:
+    """Lay `total_days` numbered cells into Sunday-first weeks.
+
+    Parameters
+    ----------
+    lead_blanks : int
+        Empty cells before day 1, i.e. the Sunday-first index of day 1.
+    total_days : int
+        The number of days in the month.
+
+    Returns
+    -------
+    tuple of tuple of (int or None)
+        Each week as 7 cells; None marks a cell outside the month.
+    """
     cells: list[int | None] = [None] * lead_blanks + list(range(1, total_days + 1))
     while len(cells) % _DAYS_PER_WEEK:
         cells.append(None)
@@ -79,6 +129,28 @@ def bs_month_grid(year: int, month: int, *, today: BSDate | None = None) -> Mont
 
     `today` is passed in rather than read from the clock so this stays pure and
     the caller keeps one seam for the current date.
+
+    Parameters
+    ----------
+    year : int
+        The Bikram Sambat year.
+    month : int
+        The Bikram Sambat month, 1-12.
+    today : BSDate or None, optional
+        The current BS date, used to mark today's cell if it falls inside
+        this month. Default is None.
+
+    Returns
+    -------
+    MonthGrid
+        The laid-out month.
+
+    Raises
+    ------
+    InvalidDateError
+        If `month` is not `1-12`.
+    DateOutOfRangeError
+        If `year` is outside the bundled table's range.
     """
     first_bs = BSDate(year=year, month=month, day=1)  # validates year and month
     total_days = days_in_month(year, month)
@@ -100,6 +172,27 @@ def ad_month_grid(year: int, month: int, *, today: date | None = None) -> MonthG
 
     A Gregorian month never lines up with a BS month, so the subtitle names
     both ends rather than pretending there is a single corresponding month.
+
+    Parameters
+    ----------
+    year : int
+        The Gregorian year.
+    month : int
+        The Gregorian month, 1-12.
+    today : date or None, optional
+        The current Gregorian date, used to mark today's cell if it falls
+        inside this month. Default is None.
+
+    Returns
+    -------
+    MonthGrid
+        The laid-out month.
+
+    Raises
+    ------
+    DateOutOfRangeError
+        If `month` is not `1-12`, or if the month is not fully inside the
+        convertible AD window.
     """
     if not (1 <= month <= 12):
         raise DateOutOfRangeError(f"AD month {month} is outside [1, 12]")
@@ -131,24 +224,71 @@ def ad_month_grid(year: int, month: int, *, today: date | None = None) -> MonthG
 
 
 def _cell(day: int | None) -> str:
+    """Format one grid cell.
+
+    Parameters
+    ----------
+    day : int or None
+        The day number, or None for a blank cell.
+
+    Returns
+    -------
+    str
+        The day right-aligned to `_CELL_WIDTH`, or that many spaces.
+    """
     return f"{day:>{_CELL_WIDTH}}" if day is not None else " " * _CELL_WIDTH
 
 
 def block_width(grid: MonthGrid) -> int:
-    """How wide the rendered block is: the grid, unless a heading is wider."""
+    """Compute how wide the rendered block is.
+
+    Parameters
+    ----------
+    grid : MonthGrid
+        The grid to measure.
+
+    Returns
+    -------
+    int
+        The grid's width, unless a heading is wider.
+    """
     return max(len(WEEKDAY_HEADER), len(grid.title), len(grid.subtitle))
 
 
 def _indent(grid: MonthGrid) -> str:
-    """Left pad that centres the week columns under a wider heading.
+    """Compute the left pad that centres the week columns under a wider heading.
 
     Applied identically to every row, including the weekday header, so the
     columns stay in step however far the block has to shift.
+
+    Parameters
+    ----------
+    grid : MonthGrid
+        The grid being rendered.
+
+    Returns
+    -------
+    str
+        The left-padding spaces.
     """
     return " " * ((block_width(grid) - len(WEEKDAY_HEADER)) // 2)
 
 
 def _rows(grid: MonthGrid, *, mark_today: bool) -> list[str]:
+    """Render each week of `grid` as one padded, space-joined line.
+
+    Parameters
+    ----------
+    grid : MonthGrid
+        The grid to render.
+    mark_today : bool
+        Whether to wrap today's cell in rich markup.
+
+    Returns
+    -------
+    list of str
+        One line per week.
+    """
     pad = _indent(grid)
     rows: list[str] = []
     for week in grid.weeks:
@@ -163,21 +303,53 @@ def _rows(grid: MonthGrid, *, mark_today: bool) -> list[str]:
 
 
 def render_body(grid: MonthGrid) -> str:
-    """The weekday header and week rows, as plain text with no markup at all."""
+    """Render the weekday header and week rows as plain text with no markup at all.
+
+    Parameters
+    ----------
+    grid : MonthGrid
+        The grid to render.
+
+    Returns
+    -------
+    str
+        The header and week rows, newline-joined.
+    """
     return "\n".join([_indent(grid) + WEEKDAY_HEADER, *_rows(grid, mark_today=False)])
 
 
 def render_body_markup(grid: MonthGrid) -> str:
-    """Same grid, with today's cell wrapped in rich markup.
+    """Render the same grid as render_body, with today's cell wrapped in rich markup.
 
     Kept separate from render_body so the plain path cannot accidentally grow
     escape sequences: anything piping stdout depends on it staying inert.
+
+    Parameters
+    ----------
+    grid : MonthGrid
+        The grid to render.
+
+    Returns
+    -------
+    str
+        The header and week rows, with today's cell marked up.
     """
     return "\n".join([_indent(grid) + WEEKDAY_HEADER, *_rows(grid, mark_today=True)])
 
 
 def render_plain(grid: MonthGrid) -> str:
-    """The whole grid as plain text, every part centred on the same block."""
+    """Render the whole grid as plain text, every part centred on the same block.
+
+    Parameters
+    ----------
+    grid : MonthGrid
+        The grid to render.
+
+    Returns
+    -------
+    str
+        The title, subtitle, and body, newline-joined.
+    """
     width = block_width(grid)
     return "\n".join(
         [grid.title.center(width).rstrip(), grid.subtitle.center(width).rstrip(), render_body(grid)]

nepkit-0.2.0/src/nepkit/exceptions.py

@@ -1,18 +0,0 @@
-class NepkitError(Exception):
-    """Base for every error nepkit raises."""
-
-
-class CalendarDataError(NepkitError):
-    """The bundled calendar table is malformed. Raised at import."""
-
-
-class DateError(NepkitError):
-    """Base for date-input problems."""
-
-
-class InvalidDateError(DateError):
-    """Syntactically parseable, but not a real BS date."""
-
-
-class DateOutOfRangeError(DateError):
-    """Outside the range the bundled table covers."""