hebrewcal 0.1.0__tar.gz

hebrewcal-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Benjamin Schnabel
+
+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.

hebrewcal-0.1.0/PKG-INFO

@@ -0,0 +1,145 @@
+Metadata-Version: 2.4
+Name: hebrewcal
+Version: 0.1.0
+Summary: A pure-Python library for the Hebrew calendar: conversion, astronomy, holidays and religious times, computed entirely locally.
+Author-email: Benjamin Schnabel <Benjamin-777@gmx.de>
+License: MIT
+Project-URL: Homepage, https://github.com/bsesic/hebrewcal
+Project-URL: Repository, https://github.com/bsesic/hebrewcal
+Project-URL: Documentation, https://hebrewcal.readthedocs.io
+Project-URL: Issues, https://github.com/bsesic/hebrewcal/issues
+Project-URL: Changelog, https://github.com/bsesic/hebrewcal/blob/main/CHANGELOG.md
+Keywords: hebrew,calendar,jewish,zmanim,molad,gregorian,julian,calendrical
+Classifier: Development Status :: 2 - Pre-Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Religion
+Classifier: Intended Audience :: Science/Research
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Religion
+Classifier: Topic :: Scientific/Engineering :: Astronomy
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Typing :: Typed
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Provides-Extra: dev
+Requires-Dist: pytest>=8.0; extra == "dev"
+Requires-Dist: pytest-cov>=5.0; extra == "dev"
+Requires-Dist: ruff>=0.6; extra == "dev"
+Requires-Dist: flake8>=7.0; extra == "dev"
+Requires-Dist: mypy>=1.11; extra == "dev"
+Requires-Dist: pre-commit>=3.8; extra == "dev"
+Provides-Extra: docs
+Requires-Dist: sphinx>=7.0; extra == "docs"
+Requires-Dist: furo>=2024.1; extra == "docs"
+Requires-Dist: myst-parser>=3.0; extra == "docs"
+Dynamic: license-file
+
+# hebrewcal
+
+[![CI](https://github.com/bsesic/hebrewcal/actions/workflows/ci.yml/badge.svg)](https://github.com/bsesic/hebrewcal/actions/workflows/ci.yml)
+[![Documentation Status](https://readthedocs.org/projects/hebrewcal/badge/?version=latest)](https://hebrewcal.readthedocs.io/en/latest/?badge=latest)
+[![PyPI version](https://img.shields.io/pypi/v/hebrewcal.svg)](https://pypi.org/project/hebrewcal/)
+[![Python versions](https://img.shields.io/pypi/pyversions/hebrewcal.svg)](https://pypi.org/project/hebrewcal/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
+
+A pure-Python library for the Hebrew calendar.
+
+`hebrewcal` makes the Hebrew calendar usable programmatically and converts it
+bidirectionally against the Gregorian and Julian calendars. Every computation is
+performed locally — the library never issues network calls to any external service.
+
+It is built for two audiences:
+
+- **Religious use** — holidays (Israel and the Diaspora, including minority feasts and
+  Shushan Purim), Shabbat candle lighting and Havdalah, zmanim, Torah readings, the Omer
+  count, yahrzeit, and the sabbatical and jubilee cycle.
+- **Academic use** — historical, medieval and ancient dates, Babylonian and biblical
+  month names, proleptic calendars, the Julian/Gregorian reform, and the documented
+  "missing years" of the Anno Mundi count.
+
+> **Project status.** Early development. The calendar core, conversion and date handling
+> (Phase 1) are implemented. Astronomy, holidays and religious times follow on the
+> [roadmap](docs/specs/2026-06-03-architecture-roadmap.md).
+
+## Installation
+
+```bash
+pip install hebrewcal
+```
+
+`hebrewcal` requires Python 3.11+ and has **no runtime dependencies** (standard library
+only).
+
+## Quick start
+
+```python
+from hebrewcal import GregorianDate, HebrewDate, to_hebrew, to_gregorian, weekday
+
+# What Hebrew date and weekday corresponds to 31 October 1867?
+g = GregorianDate(1867, 10, 31)
+h = to_hebrew(g)
+print(h)            # HebrewDate(year=5628, month=8, day=2)  -> 2 Marheshvan 5628
+print(weekday(g).name)   # THURSDAY
+
+# Convert a Hebrew date back to Gregorian.
+print(to_gregorian(HebrewDate(5785, 7, 1)))   # GregorianDate(year=2024, month=10, day=3)
+```
+
+Every calendar reduces a date to an integer **Rata Die (RD)** day count and rebuilds a
+date from it, so any two calendars are interconvertible through RD:
+
+```python
+from hebrewcal import GregorianDate, to_julian
+
+GregorianDate(2026, 6, 26).to_rd()     # 739793
+to_julian(GregorianDate(2026, 6, 26))  # JulianDate(year=2026, month=6, day=13)
+```
+
+## Features
+
+- Proleptic **Gregorian** and **Julian** calendars, with an explicit, configurable
+  Julian/Gregorian reform helper.
+- A complete **Hebrew** calendar: molad and halakim, the dechiyot ("four gates"), year
+  typing (deficient / regular / complete), the keviah signature, and the Metonic cycle.
+- Bidirectional **conversion** between any supported calendars through Rata Die.
+- **Parsing** of Gregorian input (ISO 8601, DIN 5008 and slash form) and **formatting**
+  in numeric and named styles.
+- A **gematria** converter between integers and Hebrew numerals.
+- Month and weekday **name tables** (transliteration, Babylonian, biblical).
+- The **Anno Mundi** era with a documented "missing years" notice.
+
+## Documentation
+
+Full documentation, including a user guide with many examples, lives at
+**[hebrewcal.readthedocs.io](https://hebrewcal.readthedocs.io)**.
+
+## Development
+
+```bash
+git clone https://github.com/bsesic/hebrewcal.git
+cd hebrewcal
+python -m venv .venv && source .venv/bin/activate
+pip install -e ".[dev]"
+pre-commit install
+```
+
+Run the lint gate and the test suite:
+
+```bash
+flake8
+ruff check .
+mypy
+pytest
+```
+
+See [CONTRIBUTING.md](CONTRIBUTING.md) for the branching strategy and conventions.
+
+## License
+
+[MIT](LICENSE) © Benjamin Schnabel

hebrewcal-0.1.0/README.md

@@ -0,0 +1,103 @@
+# hebrewcal
+
+[![CI](https://github.com/bsesic/hebrewcal/actions/workflows/ci.yml/badge.svg)](https://github.com/bsesic/hebrewcal/actions/workflows/ci.yml)
+[![Documentation Status](https://readthedocs.org/projects/hebrewcal/badge/?version=latest)](https://hebrewcal.readthedocs.io/en/latest/?badge=latest)
+[![PyPI version](https://img.shields.io/pypi/v/hebrewcal.svg)](https://pypi.org/project/hebrewcal/)
+[![Python versions](https://img.shields.io/pypi/pyversions/hebrewcal.svg)](https://pypi.org/project/hebrewcal/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
+
+A pure-Python library for the Hebrew calendar.
+
+`hebrewcal` makes the Hebrew calendar usable programmatically and converts it
+bidirectionally against the Gregorian and Julian calendars. Every computation is
+performed locally — the library never issues network calls to any external service.
+
+It is built for two audiences:
+
+- **Religious use** — holidays (Israel and the Diaspora, including minority feasts and
+  Shushan Purim), Shabbat candle lighting and Havdalah, zmanim, Torah readings, the Omer
+  count, yahrzeit, and the sabbatical and jubilee cycle.
+- **Academic use** — historical, medieval and ancient dates, Babylonian and biblical
+  month names, proleptic calendars, the Julian/Gregorian reform, and the documented
+  "missing years" of the Anno Mundi count.
+
+> **Project status.** Early development. The calendar core, conversion and date handling
+> (Phase 1) are implemented. Astronomy, holidays and religious times follow on the
+> [roadmap](docs/specs/2026-06-03-architecture-roadmap.md).
+
+## Installation
+
+```bash
+pip install hebrewcal
+```
+
+`hebrewcal` requires Python 3.11+ and has **no runtime dependencies** (standard library
+only).
+
+## Quick start
+
+```python
+from hebrewcal import GregorianDate, HebrewDate, to_hebrew, to_gregorian, weekday
+
+# What Hebrew date and weekday corresponds to 31 October 1867?
+g = GregorianDate(1867, 10, 31)
+h = to_hebrew(g)
+print(h)            # HebrewDate(year=5628, month=8, day=2)  -> 2 Marheshvan 5628
+print(weekday(g).name)   # THURSDAY
+
+# Convert a Hebrew date back to Gregorian.
+print(to_gregorian(HebrewDate(5785, 7, 1)))   # GregorianDate(year=2024, month=10, day=3)
+```
+
+Every calendar reduces a date to an integer **Rata Die (RD)** day count and rebuilds a
+date from it, so any two calendars are interconvertible through RD:
+
+```python
+from hebrewcal import GregorianDate, to_julian
+
+GregorianDate(2026, 6, 26).to_rd()     # 739793
+to_julian(GregorianDate(2026, 6, 26))  # JulianDate(year=2026, month=6, day=13)
+```
+
+## Features
+
+- Proleptic **Gregorian** and **Julian** calendars, with an explicit, configurable
+  Julian/Gregorian reform helper.
+- A complete **Hebrew** calendar: molad and halakim, the dechiyot ("four gates"), year
+  typing (deficient / regular / complete), the keviah signature, and the Metonic cycle.
+- Bidirectional **conversion** between any supported calendars through Rata Die.
+- **Parsing** of Gregorian input (ISO 8601, DIN 5008 and slash form) and **formatting**
+  in numeric and named styles.
+- A **gematria** converter between integers and Hebrew numerals.
+- Month and weekday **name tables** (transliteration, Babylonian, biblical).
+- The **Anno Mundi** era with a documented "missing years" notice.
+
+## Documentation
+
+Full documentation, including a user guide with many examples, lives at
+**[hebrewcal.readthedocs.io](https://hebrewcal.readthedocs.io)**.
+
+## Development
+
+```bash
+git clone https://github.com/bsesic/hebrewcal.git
+cd hebrewcal
+python -m venv .venv && source .venv/bin/activate
+pip install -e ".[dev]"
+pre-commit install
+```
+
+Run the lint gate and the test suite:
+
+```bash
+flake8
+ruff check .
+mypy
+pytest
+```
+
+See [CONTRIBUTING.md](CONTRIBUTING.md) for the branching strategy and conventions.
+
+## License
+
+[MIT](LICENSE) © Benjamin Schnabel

hebrewcal-0.1.0/pyproject.toml

@@ -0,0 +1,104 @@
+[build-system]
+requires = ["setuptools>=68", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "hebrewcal"
+version = "0.1.0"
+description = "A pure-Python library for the Hebrew calendar: conversion, astronomy, holidays and religious times, computed entirely locally."
+readme = "README.md"
+requires-python = ">=3.11"
+license = { text = "MIT" }
+authors = [{ name = "Benjamin Schnabel", email = "Benjamin-777@gmx.de" }]
+keywords = [
+    "hebrew",
+    "calendar",
+    "jewish",
+    "zmanim",
+    "molad",
+    "gregorian",
+    "julian",
+    "calendrical",
+]
+classifiers = [
+    "Development Status :: 2 - Pre-Alpha",
+    "Intended Audience :: Developers",
+    "Intended Audience :: Religion",
+    "Intended Audience :: Science/Research",
+    "License :: OSI Approved :: MIT License",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: Religion",
+    "Topic :: Scientific/Engineering :: Astronomy",
+    "Topic :: Software Development :: Libraries :: Python Modules",
+    "Typing :: Typed",
+]
+# No runtime dependencies: everything is computed locally using the standard library only.
+dependencies = []
+
+[project.urls]
+Homepage = "https://github.com/bsesic/hebrewcal"
+Repository = "https://github.com/bsesic/hebrewcal"
+Documentation = "https://hebrewcal.readthedocs.io"
+Issues = "https://github.com/bsesic/hebrewcal/issues"
+Changelog = "https://github.com/bsesic/hebrewcal/blob/main/CHANGELOG.md"
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=8.0",
+    "pytest-cov>=5.0",
+    "ruff>=0.6",
+    "flake8>=7.0",
+    "mypy>=1.11",
+    "pre-commit>=3.8",
+]
+docs = [
+    "sphinx>=7.0",
+    "furo>=2024.1",
+    "myst-parser>=3.0",
+]
+
+[tool.setuptools]
+package-dir = { "" = "src" }
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.setuptools.package-data]
+hebrewcal = ["py.typed"]
+
+[tool.pytest.ini_options]
+minversion = "8.0"
+testpaths = ["tests"]
+addopts = "-ra --strict-markers"
+
+[tool.coverage.run]
+branch = true
+source = ["hebrewcal"]
+
+[tool.coverage.report]
+show_missing = true
+
+[tool.ruff]
+line-length = 100
+target-version = "py311"
+src = ["src", "tests"]
+
+[tool.ruff.lint]
+select = ["E", "F", "W", "I", "N", "UP", "B", "C4", "SIM", "RUF"]
+# This library deliberately embeds Hebrew text in strings, comments and
+# docstrings. The ambiguous-unicode checks (homoglyph detection for Latin code)
+# are false positives in that context, so they are disabled project-wide.
+ignore = ["RUF001", "RUF002", "RUF003"]
+
+[tool.ruff.lint.isort]
+known-first-party = ["hebrewcal"]
+
+[tool.mypy]
+python_version = "3.11"
+strict = true
+warn_unreachable = true
+files = ["src", "tests"]

hebrewcal-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

hebrewcal-0.1.0/src/hebrewcal/__init__.py

@@ -0,0 +1,37 @@
+"""hebrewcal — a pure-Python library for the Hebrew calendar.
+
+The library makes the Hebrew calendar usable programmatically and converts it
+bidirectionally against the Gregorian and Julian calendars. Every computation is
+performed locally; the library never issues network calls to any external service.
+
+The whole design pivots on the Rata Die (RD) day count from Dershowitz & Reingold,
+*Calendrical Calculations*: every calendar implements only ``to_rd`` and ``from_rd``,
+and conversion between any two calendars always goes through RD.
+"""
+
+from __future__ import annotations
+
+from importlib import metadata
+
+from hebrewcal.calendars.gregorian import GregorianDate
+from hebrewcal.calendars.hebrew import HebrewDate
+from hebrewcal.calendars.julian import JulianDate
+from hebrewcal.conversion import to_gregorian, to_hebrew, to_julian, weekday
+from hebrewcal.core.calendar import Weekday
+
+try:
+    __version__ = metadata.version("hebrewcal")
+except metadata.PackageNotFoundError:  # pragma: no cover - source checkout without install
+    __version__ = "0.0.0.dev0"
+
+__all__ = [
+    "GregorianDate",
+    "HebrewDate",
+    "JulianDate",
+    "Weekday",
+    "__version__",
+    "to_gregorian",
+    "to_hebrew",
+    "to_julian",
+    "weekday",
+]

hebrewcal-0.1.0/src/hebrewcal/astro/__init__.py

@@ -0,0 +1,7 @@
+"""Astronomy and locations — pure Python, no dependencies.
+
+Implements solar position, sunrise/sunset and twilight (Meeus / NOAA algorithms),
+a geographic ``Location`` type, and time-zone handling via the standard-library
+``zoneinfo`` module. This is the foundation for all time-of-day religious
+calculations.
+"""

hebrewcal-0.1.0/src/hebrewcal/calendars/__init__.py

@@ -0,0 +1,5 @@
+"""Concrete calendars: Gregorian, Julian and Hebrew.
+
+Each calendar converts to and from the Rata Die day count, which makes every
+calendar interconvertible without any pairwise conversion code.
+"""

hebrewcal-0.1.0/src/hebrewcal/calendars/gregorian.py

@@ -0,0 +1,90 @@
+"""The proleptic Gregorian calendar.
+
+Valid for all years, including years <= 0 (proleptic). The RD value matches the
+Python standard-library proleptic Gregorian ordinal, which makes cross-checking
+straightforward.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+from hebrewcal.core.rata_die import RD_EPOCH
+
+_MONTH_LENGTHS = (31, 28, 31, 30, 31, 30, 31, 31, 30, 31, 30, 31)
+
+
+def is_leap_year(year: int) -> bool:
+    """Return whether ``year`` is a Gregorian leap year."""
+    return year % 4 == 0 and (year % 100 != 0 or year % 400 == 0)
+
+
+def last_day_of_month(year: int, month: int) -> int:
+    """Return the number of days in ``month`` of ``year``."""
+    if month == 2 and is_leap_year(year):
+        return 29
+    return _MONTH_LENGTHS[month - 1]
+
+
+@dataclass(frozen=True, order=True)
+class GregorianDate:
+    """A date in the proleptic Gregorian calendar."""
+
+    year: int
+    month: int
+    day: int
+
+    def __post_init__(self) -> None:
+        if not 1 <= self.month <= 12:
+            raise ValueError(f"month out of range: {self.month}")
+        if not 1 <= self.day <= last_day_of_month(self.year, self.month):
+            raise ValueError(f"day out of range: {self.day}")
+
+    def to_rd(self) -> int:
+        """Return the Rata Die day count for this date."""
+        y = self.year
+        if self.month <= 2:
+            correction = 0
+        elif is_leap_year(y):
+            correction = -1
+        else:
+            correction = -2
+        return (
+            RD_EPOCH
+            - 1
+            + 365 * (y - 1)
+            + (y - 1) // 4
+            - (y - 1) // 100
+            + (y - 1) // 400
+            + (367 * self.month - 362) // 12
+            + correction
+            + self.day
+        )
+
+    @classmethod
+    def from_rd(cls, rd: int) -> GregorianDate:
+        """Reconstruct a Gregorian date from an RD value."""
+        year = _year_from_rd(rd)
+        prior_days = rd - cls(year, 1, 1).to_rd()
+        if rd < cls(year, 3, 1).to_rd():
+            correction = 0
+        elif is_leap_year(year):
+            correction = 1
+        else:
+            correction = 2
+        month = (12 * (prior_days + correction) + 373) // 367
+        day = rd - cls(year, month, 1).to_rd() + 1
+        return cls(year, month, day)
+
+
+def _year_from_rd(rd: int) -> int:
+    """Return the Gregorian year containing the given RD value."""
+    d0 = rd - RD_EPOCH
+    n400, d1 = divmod(d0, 146097)
+    n100, d2 = divmod(d1, 36524)
+    n4, d3 = divmod(d2, 1461)
+    n1 = d3 // 365
+    year = 400 * n400 + 100 * n100 + 4 * n4 + n1
+    if n100 == 4 or n1 == 4:
+        return year
+    return year + 1

hebrewcal-0.1.0/src/hebrewcal/calendars/hebrew.py

@@ -0,0 +1,65 @@
+"""The Hebrew calendar date type.
+
+Month numbering is standard (Nisan = 1 ... Tishri = 7 ... Adar/Adar I = 12,
+Adar II = 13). The civil year begins at Tishri. Conversion to and from RD uses
+the year-typing machinery in :mod:`hebrewcal.hebrew`.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+from hebrewcal.hebrew.yeartype import (
+    last_day_of_month,
+    last_month_of_year,
+    new_year_rd,
+)
+
+_TISHRI = 7
+
+
+@dataclass(frozen=True, order=True)
+class HebrewDate:
+    """A date in the Hebrew calendar."""
+
+    year: int
+    month: int
+    day: int
+
+    def __post_init__(self) -> None:
+        if not 1 <= self.month <= last_month_of_year(self.year):
+            raise ValueError(f"month out of range: {self.month}")
+        if not 1 <= self.day <= last_day_of_month(self.year, self.month):
+            raise ValueError(f"day out of range: {self.day}")
+
+    def to_rd(self) -> int:
+        """Return the Rata Die day count for this date."""
+        if self.month < _TISHRI:
+            # Months Nisan..Elul fall in the second half of the civil year.
+            months_after_tishri = range(_TISHRI, last_month_of_year(self.year) + 1)
+            months_before = range(1, self.month)
+        else:
+            months_after_tishri = range(_TISHRI, self.month)
+            months_before = range(0, 0)  # empty
+        days_before = sum(
+            last_day_of_month(self.year, m) for m in months_after_tishri
+        ) + sum(last_day_of_month(self.year, m) for m in months_before)
+        return new_year_rd(self.year) + days_before + self.day - 1
+
+    @classmethod
+    def from_rd(cls, rd: int) -> HebrewDate:
+        """Reconstruct a Hebrew date from an RD value."""
+        # Estimate the year, then correct by direct comparison.
+        approx = (rd - new_year_rd(1)) // 366 + 1
+        year = approx
+        while new_year_rd(year + 1) <= rd:
+            year += 1
+        while new_year_rd(year) > rd:
+            year -= 1
+        # Determine the starting month: Nisan (1) if on/after 1 Nisan, else Tishri (7).
+        start = 1 if rd >= cls(year, 1, 1).to_rd() else _TISHRI
+        month = start
+        while rd > cls(year, month, last_day_of_month(year, month)).to_rd():
+            month += 1
+        day = rd - cls(year, month, 1).to_rd() + 1
+        return cls(year, month, day)

hebrewcal-0.1.0/src/hebrewcal/calendars/julian.py

@@ -0,0 +1,95 @@
+"""The proleptic Julian calendar with explicit reform handling.
+
+The library never performs a silent Julian/Gregorian switch. Everything is
+computed through RD; the historical 1582 (and later, regional) reform is exposed
+as an explicit, configurable helper so callers decide when the cutover applies.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+from hebrewcal.calendars.gregorian import GregorianDate
+
+# RD of Julian 1 January 1 == Gregorian 30 December 0 == -1.
+JULIAN_EPOCH: int = -1
+
+_MONTH_LENGTHS = (31, 28, 31, 30, 31, 30, 31, 31, 30, 31, 30, 31)
+
+
+def is_leap_year(year: int) -> bool:
+    """Return whether ``year`` is a Julian leap year (proleptic, no year 0)."""
+    if year > 0:
+        return year % 4 == 0
+    # There is no year 0; proleptically, leap years satisfy year % 4 == 3.
+    return year % 4 == 3
+
+
+def last_day_of_month(year: int, month: int) -> int:
+    """Return the number of days in ``month`` of ``year``."""
+    if month == 2 and is_leap_year(year):
+        return 29
+    return _MONTH_LENGTHS[month - 1]
+
+
+@dataclass(frozen=True, order=True)
+class JulianDate:
+    """A date in the proleptic Julian calendar."""
+
+    year: int
+    month: int
+    day: int
+
+    def __post_init__(self) -> None:
+        if self.year == 0:
+            raise ValueError("Julian calendar has no year 0")
+        if not 1 <= self.month <= 12:
+            raise ValueError(f"month out of range: {self.month}")
+        if not 1 <= self.day <= last_day_of_month(self.year, self.month):
+            raise ValueError(f"day out of range: {self.day}")
+
+    def to_rd(self) -> int:
+        """Return the Rata Die day count for this date."""
+        y = self.year + 1 if self.year < 0 else self.year
+        if self.month <= 2:
+            correction = 0
+        elif is_leap_year(self.year):
+            correction = -1
+        else:
+            correction = -2
+        return (
+            JULIAN_EPOCH
+            - 1
+            + 365 * (y - 1)
+            + (y - 1) // 4
+            + (367 * self.month - 362) // 12
+            + correction
+            + self.day
+        )
+
+    @classmethod
+    def from_rd(cls, rd: int) -> JulianDate:
+        """Reconstruct a Julian date from an RD value."""
+        approx = (4 * (rd - JULIAN_EPOCH) + 1464) // 1461
+        year = approx - 1 if approx <= 0 else approx
+        prior_days = rd - cls(year, 1, 1).to_rd()
+        if rd < cls(year, 3, 1).to_rd():
+            correction = 0
+        elif is_leap_year(year):
+            correction = 1
+        else:
+            correction = 2
+        month = (12 * (prior_days + correction) + 373) // 367
+        day = rd - cls(year, month, 1).to_rd() + 1
+        return cls(year, month, day)
+
+
+def last_gregorian_before_reform() -> GregorianDate:
+    """Return the last Gregorian-labelled date before the 1582 papal cutover.
+
+    The papal bull skipped from Julian Thursday 4 October 1582 to Gregorian
+    Friday 15 October 1582. Adoption was regional and much later in many places;
+    callers that need a different cutover should supply their own date. This
+    helper exists so the default reference point is explicit, not implicit.
+    """
+    return GregorianDate(1582, 10, 4)