v1.4.0

Reworks the Karaite calendar into an astronomical estimate of the observational calendar.

Changed

• The Karaite calendar now begins each month on estimated first crescent visibility over Jerusalem — the first sunset at least ~20 hours after the true lunar conjunction — and sets the year by the equinox-based aviv rule (Passover on/after the vernal equinox). It replaces the previous mean-lunar approximation.
• Built on verified astronomy (true conjunction, sunset, equinox) and clearly documented as an estimate, not authoritative Karaite observance; now limited to the years datetime supports (1–9999). The Samaritan computed model is unchanged.

No new runtime dependencies.

Installation

pip install hebrewcal

Requires Python 3.11+. Documentation: https://hebrewcal.readthedocs.io

v1.3.0

Adds zmanim opinions and an elevation correction.

Added

• Configurable solar depression on alot_hashachar, misheyakir and tzeit_hakochavim, plus fixed-minute variants alot_hashachar_fixed, tzeit_fixed and tzeit_rabbeinu_tam (Rabbeinu Tam).
• Optional elevation horizon-dip correction for sunrise/sunset (elevation=True), using the geometric acos(R/(R+h)) formula consistent with common zmanim software.

No new runtime dependencies.

Installation

pip install hebrewcal

Requires Python 3.11+. Documentation: https://hebrewcal.readthedocs.io

v1.2.0

Adds the true astronomical new moon (lunar conjunction).

Added

• hebrewcal.astro.lunar: nth_new_moon, new_moon_at_or_after and new_moon_before, using the Meeus periodic terms — distinct from the calendar's mean molad (the two differ by up to ~14 hours). Returned as UTC-aware datetimes (underlying value Terrestrial Time; ΔT ≈ tens of seconds). Verified against an independent ephemeris to ~1 minute.

No new runtime dependencies.

Installation

pip install hebrewcal

Requires Python 3.11+. Documentation: https://hebrewcal.readthedocs.io

v1.1.0

Adds native Hebrew-script output.

Added

• Hebrew month names via hebrew_month_name(..., system="hebrew") (including Adar I/II) and weekday names via weekday_name(..., hebrew=True).
• format_hebrew(date, style="hebrew") renders the date in Hebrew script with the day and year as gematria numerals (e.g. א׳ תשרי ה׳תשפ״ה).
• A hebrewcal convert --hebrew command-line flag.

No new runtime dependencies.

Installation

pip install hebrewcal

Requires Python 3.11+. Documentation: https://hebrewcal.readthedocs.io

v1.0.0

First stable release. hebrewcal is a pure-Python library for the Hebrew calendar — no runtime dependencies, no network calls. This release completes the roadmap; the public API is now considered stable.

Features

• Calendars & conversion: proleptic Gregorian and Julian (with an explicit reform helper) and a complete Hebrew calendar (molad/halakim, dechiyot, year typing, keviah, Metonic cycle), interconvertible through Rata Die. Parsing, formatting, gematria numerals, name tables, and the Anno Mundi era.
• Astronomy: solar position, sunrise/sunset, twilight, and the molad as a civil instant.
• Holidays: festivals, fasts (with postponement), modern Israeli days, minority feasts, Rosh Chodesh, the Omer and the special Shabbatot — Israel and Diaspora.
• Religious times: candle lighting and Havdalah, zmanim, the molad announcement, yahrzeit, Torah readings, and the Shmita cycle.
• Alternative calendars: the Qumran 364-day calendar plus documented computed Samaritan and Karaite models.
• An optional command-line interface (hebrewcal).

Installation

pip install hebrewcal

Requires Python 3.11+. Documentation: https://hebrewcal.readthedocs.io

v0.5.0

Phase 5 of the roadmap: alternative calendars, via the same Rata Die interface.

Added

• Qumran / Jubilees 364-day calendar — exact: four 91-day quarters, every year starts on the same weekday, no intercalation.
• Samaritan computed mean-lunar model and Karaite computed approximation (mean conjunction plus a one-day sighting lag), both clearly documented as computed models that are not verified against an authoritative source; the Karaite model does not replace observation.

Installation

pip install hebrewcal

Requires Python 3.11+. Documentation: https://hebrewcal.readthedocs.io

v0.4.0

Phase 4 of the roadmap: the religious-time layer, built on the astronomy and calendar layers, with no runtime dependencies.

Added

• Shabbat candle lighting and Havdalah (configurable offsets / depression).
• Zmanim: alot, misheyakir, sunrise, sof zman Shma/Tefilla (GRA and MGA), chatzot, mincha gedola/ketana, plag hamincha, sunset, tzeit.
• Molad / Rosh Chodesh announcement (Shabbat Mevarchim).
• Yahrzeit with the 30th-of-month and Adar edge cases.
• Torah readings: the annual cycle (Israel and Diaspora) plus a triennial helper, verified against an independent reference on 10,024 Shabbatot with zero structural mismatches.
• Shmita (sabbatical) and Jubilee cycle.

Installation

pip install hebrewcal

Requires Python 3.11+. Documentation: https://hebrewcal.readthedocs.io

v0.3.0

Phase 3 of the roadmap: the holiday engine. This release completes the MVP — calendar core, astronomy, and holidays.

Added

• Holiday engine: holidays(year, diaspora=True) and holidays_on(date), with a Holiday type and Category enum.
• Major festivals with Israel/Diaspora differences (yom tov sheni, Simchat Torah placement, 7- vs 8-day Pesach, 1 vs 2 days Shavuot) and Chol HaMoed.
• Minor festivals and Rosh Chodesh (Hanukkah, Tu BiShvat, Purim/Shushan Purim incl. leap-year Adar II, Lag BaOmer, Tu B'Av, Pesach Sheni, Hoshana Rabbah).
• Fasts with postponement rules.
• Modern Israeli days with the statutory weekday adjustments.
• Minority feasts (Sigd, Mimouna).
• The Omer count and the special Shabbatot.

Installation

pip install hebrewcal

Requires Python 3.11+. Documentation: https://hebrewcal.readthedocs.io

v0.2.0

Phase 2 of the roadmap: a pure-Python astronomy layer, with no runtime dependencies and no network calls.

Added

• Location value type (coordinates, elevation, IANA time zone).
• Julian Day time base derived from the Rata Die count, and an RD/UTC-minutes ↔ timezone-aware datetime bridge.
• NOAA/Meeus solar model: sunrise, sunset, solar_noon (agreeing with reference implementations to ~15-20 s at mid latitudes), plus solar_declination and equation_of_time.
• Twilight: civil, nautical and astronomical dawn/dusk with a configurable depression angle.
• Molad as a civil instant in Jerusalem mean time.

Installation

pip install hebrewcal

Requires Python 3.11+. Documentation: https://hebrewcal.readthedocs.io

v0.1.1

Maintenance release adding citation and archival metadata.

Changed

• Add CITATION.cff (Citation File Format 1.2.0) and .zenodo.json so the project is citable and each release is archived on Zenodo with a DOI.
• README gains a Citation section.

No functional code changes since v0.1.0.

Installation

pip install hebrewcal

Requires Python 3.11+. Documentation: https://hebrewcal.readthedocs.io