API reference¶
This section is generated from the package docstrings.
Package root¶
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.
- class hebrewcal.GregorianDate(year, month, day)[source]¶
A date in the proleptic Gregorian calendar.
- class hebrewcal.HebrewDate(year, month, day)[source]¶
A date in the Hebrew calendar.
- class hebrewcal.JulianDate(year, month, day)[source]¶
A date in the proleptic Julian calendar.
- hebrewcal.to_gregorian(date)[source]¶
Convert any supported date to a Gregorian date.
- Parameters:
date (CalendarDate)
- Return type:
- hebrewcal.to_hebrew(date)[source]¶
Convert any supported date to a Hebrew date.
- Parameters:
date (CalendarDate)
- Return type:
- hebrewcal.to_julian(date)[source]¶
Convert any supported date to a Julian date.
- Parameters:
date (CalendarDate)
- Return type:
- hebrewcal.weekday(date)[source]¶
Return the weekday of any supported date.
- Parameters:
date (CalendarDate)
- Return type:
Core¶
The Rata Die (RD) day count — the conversion pivot of the whole library.
RD is a continuous integer count of days. RD 1 is Monday, 1 January 1 in the proleptic Gregorian calendar (Dershowitz & Reingold, Calendrical Calculations). Every calendar converts to and from RD, so any two calendars are interconvertible through it.
- hebrewcal.core.rata_die.weekday_from_rd(rd)[source]¶
Return the day of week for an RD value.
0 = Sunday, 1 = Monday, …, 6 = Saturday. RD 1 is a Monday, so
1 % 7 == 1.
- hebrewcal.core.rata_die.add_days(rd, days)[source]¶
Return the RD value
daysafterrd(daysmay be negative).
The abstract calendar interface and cross-calendar conversion.
Any calendar date is a value that can produce an RD (to_rd) and be rebuilt
from an RD (from_rd). That pair is the entire contract a calendar must meet
to interoperate with every other calendar in the library.
- class hebrewcal.core.calendar.Weekday(*values)[source]¶
Day of week with Sunday = 0, matching
weekday_from_rd.
- class hebrewcal.core.calendar.CalendarDate(*args, **kwargs)[source]¶
Structural type for any value that can produce a Rata Die day count.
- hebrewcal.core.calendar.convert(date, target)[source]¶
Convert
dateto thetargetcalendar by routing through RD.- Parameters:
date (CalendarDate)
target (type[T])
- Return type:
T
- hebrewcal.core.calendar.weekday(date)[source]¶
Return the
Weekdayof any calendar date.- Parameters:
date (CalendarDate)
- Return type:
Calendars¶
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.
- hebrewcal.calendars.gregorian.is_leap_year(year)[source]¶
Return whether
yearis a Gregorian leap year.
- hebrewcal.calendars.gregorian.last_day_of_month(year, month)[source]¶
Return the number of days in
monthofyear.
- class hebrewcal.calendars.gregorian.GregorianDate(year, month, day)[source]¶
A date in the proleptic Gregorian calendar.
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.
- hebrewcal.calendars.julian.is_leap_year(year)[source]¶
Return whether
yearis a Julian leap year (proleptic, no year 0).
- hebrewcal.calendars.julian.last_day_of_month(year, month)[source]¶
Return the number of days in
monthofyear.
- class hebrewcal.calendars.julian.JulianDate(year, month, day)[source]¶
A date in the proleptic Julian calendar.
- hebrewcal.calendars.julian.last_gregorian_before_reform()[source]¶
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 type:
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 hebrewcal.hebrew.
Conversion¶
High-level, ergonomic conversion between the supported calendars.
Every function routes through RD via hebrewcal.core.calendar.convert().
- hebrewcal.conversion.to_gregorian(date)[source]¶
Convert any supported date to a Gregorian date.
- Parameters:
date (CalendarDate)
- Return type:
- hebrewcal.conversion.to_julian(date)[source]¶
Convert any supported date to a Julian date.
- Parameters:
date (CalendarDate)
- Return type:
- hebrewcal.conversion.to_hebrew(date)[source]¶
Convert any supported date to a Hebrew date.
- Parameters:
date (CalendarDate)
- Return type:
- hebrewcal.conversion.weekday(date)[source]¶
Return the weekday of any supported date.
- Parameters:
date (CalendarDate)
- Return type:
Command-line interface¶
A small command-line interface for hebrewcal.
Exposed as the hebrewcal console script and via python -m hebrewcal.
Uses only the standard library (argparse).
Hebrew arithmetic engine¶
The 19-year Metonic cycle.
Seven of every nineteen Hebrew years are leap years (a 13th month, Adar I, is
inserted). A year y is leap iff (7 * y + 1) mod 19 < 7.
- hebrewcal.hebrew.metonic.is_leap_year(year)[source]¶
Return whether the Hebrew
yearis a leap (13-month) year.
- hebrewcal.hebrew.metonic.months_in_year(year)[source]¶
Return the number of months in the Hebrew
year(12 or 13).
Molad arithmetic and the calendar-elapsed-days function.
Time in the Hebrew calendar is measured in halakim (parts): there are 1080
parts in an hour and therefore 25920 in a day. A helek is one part. The molad
is the mean lunar conjunction; calendar_elapsed_days converts a year to the
number of days elapsed from the epoch to that year’s Tishri, applying the
molad-zaken / lo-ADU portion of the postponement logic (Dershowitz & Reingold).
- hebrewcal.hebrew.molad.months_until(year)[source]¶
Return the number of months elapsed before Tishri of
year.
- hebrewcal.hebrew.molad.molad_parts(year, month)[source]¶
Return the molad of
monthinyearas total parts since the epoch.monthuses standard numbering (Tishri = 7). The returned value is an absolute parts count;value // HALAKIM_PER_DAYis the day andvalue % HALAKIM_PER_DAYthe parts within that day.
- hebrewcal.hebrew.molad.calendar_elapsed_days(year)[source]¶
Return days from the Hebrew epoch to Tishri 1 of
year.This is the value before year-length correction, with the molad-zaken adjustment already applied.
The four postponement rules (dechiyot), expressed as a year-length correction.
Rosh Hashanah cannot fall on certain weekdays, and two cases adjust the length
of the year so that no year is illegally short or long. Together with the
molad-zaken adjustment inside calendar_elapsed_days these implement the
classical “four gates”. The correction here adds 0, 1, or 2 days based on the
gap between consecutive years’ elapsed-day counts (Dershowitz & Reingold).
- hebrewcal.hebrew.dechiyot.year_length_correction(year)[source]¶
Return the 0, 1, or 2 day correction applied to
year’s new year.
Hebrew year typing: new-year RD, year length, and month lengths.
The length of a Hebrew year (353/354/355 common, 383/384/385 leap) determines whether Marheshvan is long (30) and whether Kislev is short (29), which is what makes a year deficient, regular, or complete.
- hebrewcal.hebrew.yeartype.last_month_of_year(year)[source]¶
Return the last month number of
year(12 common, 13 leap).
- hebrewcal.hebrew.yeartype.new_year_rd(year)[source]¶
Return the RD of 1 Tishri of the Hebrew
year(Rosh Hashanah).
- hebrewcal.hebrew.yeartype.is_long_marheshvan(year)[source]¶
Return whether Marheshvan has 30 days in
year.
- hebrewcal.hebrew.yeartype.last_day_of_month(year, month)[source]¶
Return the number of days in
monthof the Hebrewyear.
The keviah — the compact signature classifying a Hebrew year.
A year is classified by three facts: whether it is a leap year, the weekday of Rosh Hashanah, and whether it is deficient (chaser), regular (kesidran), or complete (shalem). Those three determine the entire layout of the year.
- class hebrewcal.hebrew.keviah.YearKind(*values)[source]¶
Whether a year is deficient, regular, or complete.
Parsing and formatting¶
Parse Gregorian dates supplied in several textual formats.
Supported forms: ISO 8601 (YYYY-MM-DD), DIN 5008 (DD.MM.YYYY) and the
slash form (YYYY/MM/DD). The result is always a normalised
GregorianDate; ambiguous or invalid input
raises ValueError.
- hebrewcal.parsing.dates.parse_gregorian(text)[source]¶
Parse
textinto aGregorianDate.Raises
ValueErrorif the input matches no known format or denotes an invalid calendar date.- Parameters:
text (str)
- Return type:
Render dates in numeric and named output formats.
- hebrewcal.formatting.dates.format_gregorian(date, style='iso')[source]¶
Format a Gregorian date as ISO 8601 or DIN 5008.
- Parameters:
date (GregorianDate)
style (Literal['iso', 'din'])
- Return type:
- hebrewcal.formatting.dates.format_hebrew(date, style='named')[source]¶
Format a Hebrew date.
Styles:
"numeric"(e.g.5785-07-01),"named"(transliterated month name, e.g.1 Tishri 5785), or"hebrew"(native Hebrew script with the day and year as gematria numerals, e.g.א׳ תשרי ה׳תשפ״ה).- Parameters:
date (HebrewDate)
style (Literal['named', 'numeric', 'hebrew'])
- Return type:
Numerals and names¶
Convert between integers and Hebrew numerals (gematria).
Hebrew numerals are additive letter values. Conventions implemented here:
15 and 16 are written ט״ו and ט״ז (9+6, 9+7) to avoid spelling fragments of the divine name.
A geresh (׳) marks a single-letter number; a gershayim (״) is inserted before the last letter of a multi-letter number.
Thousands are written as the hundreds-or-less value followed by a geresh, then the remainder (e.g. 5785 -> ה׳תשפ״ה).
- hebrewcal.numerals.to_hebrew_numeral(number)[source]¶
Convert a positive integer to its Hebrew numeral string.
Note: an exact multiple of 1000 with no remainder (e.g. 1000) is ambiguous in this additive notation and round-trips to its sub-1000 value; year-style numbers (a thousands group followed by a remainder, e.g. 5785) are unambiguous.
- hebrewcal.numerals.from_hebrew_numeral(text)[source]¶
Convert a Hebrew numeral string back to an integer.
Month and weekday name tables in several naming systems.
Month numbering is standard (Nisan = 1 … Tishri = 7 … Adar/Adar I = 12, Adar II = 13). In a leap year month 12 is “Adar I” and month 13 is “Adar II”; in a common year month 12 is simply “Adar”.
Eras¶
The Anno Mundi (AM) era.
The AM year is the Hebrew calendar year number; conversion is computationally exact and unambiguous. The library does NOT silently “correct” the well-known discrepancy between the traditional reckoning and academic-historical chronology for the Persian period (the “missing years”); instead it documents it and offers the gap as data for academic use.
- hebrewcal.eras.anno_mundi.anno_mundi_year(date)[source]¶
Return the Anno Mundi year of a Hebrew date (identical to its year).
- Parameters:
date (HebrewDate)
- Return type:
Astronomy¶
The geographic location type used by all astronomical computations.
- class hebrewcal.astro.location.Location(latitude, longitude, elevation=0.0, timezone='UTC')[source]¶
A geographic location.
- property tzinfo: ZoneInfo¶
Return the
zoneinfo.ZoneInfofor this location’s time zone.
Astronomical time base: Julian Day and Julian centuries.
The Julian Day is derived from the library’s Rata Die day count, which keeps the astronomy layer exactly consistent with the calendar core:
JD(00:00 UTC) = RD + 1721424.5
so RD 1 (proleptic Gregorian 0001-01-01) is JD 1721425.5 at midnight.
- hebrewcal.astro.timekeeping.julian_day_from_rd(rd, day_fraction=0.0)[source]¶
Return the Julian Day for an RD value plus a fraction of a day.
- hebrewcal.astro.timekeeping.julian_day(year, month, day, day_fraction=0.0)[source]¶
Return the Julian Day for a proleptic Gregorian date plus a day fraction.
- hebrewcal.astro.timekeeping.julian_centuries(jd)[source]¶
Return Julian centuries since J2000.0 for the given Julian Day.
Bridge between the integer RD day count and timezone-aware datetimes.
An astronomical instant is expressed as an RD value plus either a fraction of a day or a number of minutes past 00:00 UTC. Minutes outside [0, 1440) are allowed and roll into adjacent civil days, which is what high-latitude events need.
- hebrewcal.astro.timezone.utc_datetime(rd, day_fraction=0.0, minutes=None)[source]¶
Return a UTC-aware datetime for an RD value.
Provide either
day_fraction(0.0–1.0+) orminutespast 00:00 UTC;minutestakes precedence when given and may lie outside a single day.
- hebrewcal.astro.timezone.local_datetime(rd, day_fraction=0.0, minutes=None, timezone='UTC')[source]¶
Return the same instant as
utc_datetime(), in the given time zone.
The solar position model and the events derived from it.
Implements the NOAA solar equations (after Meeus, Astronomical Algorithms) in pure Python. Sunrise and sunset agree with reference implementations to within about 15-20 seconds at mid latitudes after a two-pass refinement.
- hebrewcal.astro.solar.elevation_depression(elevation_m)[source]¶
Return the extra horizon dip (degrees) for an observer at
elevation_m.Uses the geometric dip
acos(R / (R + h))consistent with common zmanim software (e.g. KosherJava). Returns 0 for non-positive elevations.
- hebrewcal.astro.solar.solar_declination(year, month, day, day_fraction=0.5)[source]¶
Return the sun’s declination in degrees for the given date (default local noon-ish).
- hebrewcal.astro.solar.equation_of_time(year, month, day, day_fraction=0.5)[source]¶
Return the equation of time in minutes for the given date.
- hebrewcal.astro.solar.sunrise(date, location, *, elevation=False)[source]¶
Return the sunrise as a local datetime, or None if the sun does not rise.
With
elevation=Truethe observer’s elevation (location.elevation) lowers the visible horizon, making sunrise earlier.- Parameters:
date (GregorianDate)
location (Location)
elevation (bool)
- Return type:
datetime | None
- hebrewcal.astro.solar.sunset(date, location, *, elevation=False)[source]¶
Return the sunset as a local datetime, or None if the sun does not set.
With
elevation=Truethe observer’s elevation (location.elevation) lowers the visible horizon, making sunset later.- Parameters:
date (GregorianDate)
location (Location)
elevation (bool)
- Return type:
datetime | None
- hebrewcal.astro.solar.solar_noon(date, location)[source]¶
Return solar noon as a local datetime.
- Parameters:
date (GregorianDate)
location (Location)
- Return type:
- hebrewcal.astro.solar.dawn(date, location, depression=6.0)[source]¶
Return morning twilight for the given solar depression, or None at high latitudes.
- Parameters:
date (GregorianDate)
location (Location)
depression (float)
- Return type:
datetime | None
- hebrewcal.astro.solar.dusk(date, location, depression=6.0)[source]¶
Return evening twilight for the given solar depression, or None at high latitudes.
- Parameters:
date (GregorianDate)
location (Location)
depression (float)
- Return type:
datetime | None
The molad expressed as a civil instant (a mean lunar conjunction).
The molad is the mean conjunction used by the Hebrew calendar, reckoned in Jerusalem mean time, where the molad “day” begins at 18:00 the previous evening. It can differ from the true astronomical new moon by up to ~14 hours; this module exposes the molad for comparison rather than computing true syzygy.
The returned datetime is naive and represents Jerusalem mean time. It is
deliberately not tagged with the modern Asia/Jerusalem zone, whose standard
time (UTC+2) and daylight saving differ from mean solar time at Jerusalem.
- hebrewcal.astro.molad.molad_breakdown(year, month)[source]¶
Return (day_index, hours, parts) of the molad.
day_indexis the molad day counted from the Hebrew epoch;hoursandpartsare measured from 18:00 at the start of that day.
- hebrewcal.astro.molad.molad_moment(year, month)[source]¶
Return the molad as a naive datetime in Jerusalem mean time.
The true astronomical new moon (lunar conjunction / syzygy).
This computes the true new moon using the periodic terms of Meeus, Astronomical Algorithms (2nd ed.), chapter 49 — distinct from the calendar’s mean conjunction (the molad). The two can differ by up to about 14 hours.
The instants are returned as timezone-aware UTC datetimes. The underlying value is in Terrestrial Time (TT); the difference from UTC is ΔT (a few tens of seconds in the modern era, ~70 s around 2024), which is well within the intended use (academic comparison with the molad). The implementation agrees with an independent ephemeris to ~1 minute.
- hebrewcal.astro.lunar.nth_new_moon(n)[source]¶
Return the
n-th true new moon as a UTC datetime (n = 0 is 2000-01-06).
- hebrewcal.astro.lunar.new_moon_at_or_after(date)[source]¶
Return the first true new moon at or after 00:00 UTC on
date.- Parameters:
date (GregorianDate)
- Return type:
- hebrewcal.astro.lunar.new_moon_before(date)[source]¶
Return the last true new moon strictly before 00:00 UTC on
date.- Parameters:
date (GregorianDate)
- Return type:
Religious observances¶
The holiday engine for the Hebrew year.
Each category contributes a list of Holiday for a given Hebrew year;
holidays() aggregates and sorts them chronologically. Month numbering is the
library standard (Nisan = 1 … Tishri = 7 … Adar / Adar I = 12, Adar II = 13).
- class hebrewcal.religious.holidays.Holiday(name, date, category)[source]¶
A single observance on a specific Hebrew date.
- Parameters:
name (str)
date (HebrewDate)
category (Category)
- hebrewcal.religious.holidays.rosh_chodesh(year)[source]¶
Return the Rosh Chodesh days of the year (one or two per month, not Tishri).
When the preceding month has 30 days, its 30th is the first of the two Rosh Chodesh days. The civil-year month order is Tishri … Elul; 1 Tishri is Rosh Hashanah and is never labelled Rosh Chodesh.
- hebrewcal.religious.holidays.holidays(year, diaspora=True)[source]¶
Return all observances of the Hebrew
year, sorted chronologically.
- hebrewcal.religious.holidays.holidays_on(date, diaspora=True)[source]¶
Return the observances falling on the given Hebrew date.
- Parameters:
date (HebrewDate)
diaspora (bool)
- Return type:
Sefirat HaOmer - the count of the Omer.
The count runs for 49 days, from 16 Nisan (day 1) to 5 Sivan (day 49); Shavuot falls on the next day (6 Sivan).
- hebrewcal.religious.omer.omer_count(date)[source]¶
Return the Omer day (1-49) for
date, or None if outside the count.- Parameters:
date (HebrewDate)
- Return type:
int | None
- hebrewcal.religious.omer.omer_week_day(date)[source]¶
Return (weeks, days) of the Omer for
date, or None outside the count.- Parameters:
date (HebrewDate)
- Return type:
Shabbat (and yom tov) candle lighting and Havdalah.
Candle lighting is a fixed number of minutes before sunset (18 by default; some communities use 40, e.g. Jerusalem). Havdalah is nightfall, given either as a solar depression below the horizon (8.5 degrees by default) or as a fixed number of minutes after sunset.
- hebrewcal.religious.shabbat.candle_lighting(date, location, minutes_before_sunset=18)[source]¶
Return candle-lighting time, or None if the sun does not set that day.
- Parameters:
date (GregorianDate)
location (Location)
minutes_before_sunset (int)
- Return type:
datetime | None
- hebrewcal.religious.shabbat.havdalah(date, location, depression=8.5, minutes_after_sunset=None)[source]¶
Return Havdalah time.
With
minutes_after_sunsetset, use that fixed offset after sunset; otherwise use nightfall at the given solardepression. Returns None at high latitudes where the relevant event does not occur.- Parameters:
date (GregorianDate)
location (Location)
depression (float)
minutes_after_sunset (int | None)
- Return type:
datetime | None
Zmanim - the halachic times of the day.
Seasonal (“proportional”) hours divide the daylight span into twelve. The GRA day runs from sunrise to sunset; the MGA day runs from dawn to nightfall at 16.1 degrees. Deadlines are expressed as a number of seasonal hours after the start of the relevant day. Each method returns a timezone-aware datetime, or None at high latitudes where a required event does not occur.
- class hebrewcal.religious.zmanim.Zmanim(date, location)[source]¶
Halachic times for a date and location.
- Parameters:
date (GregorianDate)
location (Location)
- alot_hashachar(degrees=16.1)[source]¶
Dawn at the given solar depression (default 16.1°, the MGA opinion).
- alot_hashachar_fixed(minutes=72.0)[source]¶
Dawn as a fixed number of clock minutes before sunrise (default 72).
- misheyakir(degrees=11.0)[source]¶
Earliest tallit/tefillin time at the given depression (default 11°).
- tzeit_hakochavim(degrees=8.5)[source]¶
Nightfall (three stars) at the given depression (default 8.5°).
The molad and Rosh Chodesh announcement (Shabbat Mevarchim).
- class hebrewcal.religious.announce.MonthAnnouncement(molad, rosh_chodesh, shabbat_mevarchim)[source]¶
Information announced on Shabbat Mevarchim for an upcoming month.
- Parameters:
molad (datetime)
rosh_chodesh (tuple[HebrewDate, ...])
shabbat_mevarchim (HebrewDate)
- hebrewcal.religious.announce.month_announcement(year, month)[source]¶
Return the molad, Rosh Chodesh day(s) and Shabbat Mevarchim for
month.- Parameters:
- Return type:
Yahrzeit - the Hebrew-calendar anniversary of a death.
Edge cases handled:
A death on the 30th of Marheshvan or Kislev: in a later year where that month has only 29 days, the yahrzeit moves to the 1st of the following month.
A death in Adar of a common year, or Adar II of a leap year, maps to Adar (month 12) in a common year and to Adar II (month 13) in a leap year.
A death in Adar I (month 12) of a leap year maps to Adar (month 12).
- hebrewcal.religious.yahrzeit.yahrzeit(death, year)[source]¶
Return the yahrzeit date in the Hebrew
yearfor a death ondeath.- Parameters:
death (HebrewDate)
year (int)
- Return type:
The weekly Torah reading (parashat hashavua).
The annual cycle begins with Bereshit on the first Shabbat after Simchat Torah and
runs through Ha’azinu the following autumn (Vezot Haberachah is read on Simchat
Torah itself, not on a Shabbat). Which of the seven combinable pairs are read
together is fixed by the year type (leap, Rosh Hashanah weekday, year length, and
Israel vs Diaspora); the table below was verified against an independent reference
on thousands of Shabbatot. Shabbatot coinciding with a festival have no weekly
parasha (a festival reading is used instead) and are returned as None.
- hebrewcal.religious.torah.parasha(date, israel=False)[source]¶
Return the parashah read on the Shabbat
date, or None.None is returned when
dateis not a Saturday, or when the Shabbat carries a festival reading instead of the weekly parashah.- Parameters:
date (HebrewDate)
israel (bool)
- Return type:
str | None
- hebrewcal.religious.torah.triennial_portion(date, israel=False)[source]¶
Return which third (1, 2 or 3) of the weekly parashah is read under the common triennial cycle, or None if there is no weekly parashah that Shabbat.
- Parameters:
date (HebrewDate)
israel (bool)
- Return type:
int | None
The Shmita (sabbatical) and Yovel (jubilee) cycle.
A year is a Shmita year when year % 7 == 0 in the conventional reckoning used
today (5782 was the most recent Shmita year). The cycle year runs 1-7, with 7 being
Shmita. The Jubilee (50th year) has not been observed since Temple times and its
reckoning is disputed; this module exposes a conventional year % 50 == 0 test
and documents that it is nominal.
- hebrewcal.religious.sabbatical.is_shmita(year)[source]¶
Return whether the Hebrew
yearis a Shmita (sabbatical) year.
Alternative calendars¶
The Qumran / Jubilees 364-day solar calendar.
The calendar found in the Dead Sea Scrolls and the Book of Jubilees has a fixed 364-day year: four quarters of 91 days, each quarter being three months of 30, 30 and 31 days (so months 3, 6, 9 and 12 have 31 days). Because 364 = 52 weeks exactly, every year — and every festival — falls on the same weekday each year. The calendar has no intercalation, so it drifts against the seasons over time.
The epoch is conventional: year 1, month 1, day 1 is anchored to the Wednesday on or after the proleptic Gregorian March equinox of year 1 (the Jubilees New Year is traditionally a Wednesday, the day the luminaries were created). Year numbering is therefore nominal; the calendar’s defining properties are its 364-day structure and fixed weekday alignment, both of which are exact.
- hebrewcal.calendars_alt.qumran.days_in_year()[source]¶
Return the (constant) length of a Qumran year, 364 days.
- Return type:
- hebrewcal.calendars_alt.qumran.last_day_of_month(month)[source]¶
Return the number of days in
month(30, or 31 for months 3, 6, 9, 12).
- class hebrewcal.calendars_alt.qumran.QumranDate(year, month, day)[source]¶
A date in the Qumran / Jubilees 364-day calendar.
The Samaritan calendar - a computed model.
Warning
This is a computed mean-lunar model, not an authoritative reproduction of the Samaritan calendar. The living Samaritan calendar is fixed by the Samaritan High Priesthood using their own calculation, and the absolute correspondence and year numbering here are conventional. This module has NOT been verified against an authoritative Samaritan source; it is provided to demonstrate the extensible calendar interface and the mean-lunar structure.
The model is a mean-conjunction lunar calendar (mean synodic month, 12 or 13 months on the 19-year Metonic cycle), anchored to the Anno Mundi epoch so that year numbers approximate the traditional count. Month lengths are 29 or 30 days.
- hebrewcal.calendars_alt.samaritan.last_day_of_month(year, month)[source]¶
Return the number of days in
monthofyear(29 or 30).
- class hebrewcal.calendars_alt.samaritan.SamaritanDate(year, month, day)[source]¶
A date in the Samaritan computed-model calendar.
The Karaite calendar — an astronomical estimate of the observational calendar.
Warning
The authentic Karaite calendar is observational: each month begins with the first naked-eye sighting of the new crescent over the Land of Israel, and the year is intercalated by the ripeness of the spring barley (aviv). Neither can be reduced to a formula, and actual practice depends on reports from observers.
This module provides an astronomical estimate, not the authentic calendar:
A month begins on the evening of the first estimated crescent visibility over Jerusalem — modelled as the first sunset, at or after the true lunar conjunction (see
hebrewcal.astro.lunar), at which the moon is at leastMIN_MOON_AGE_HOURShours old. This is a simple age criterion, not a full first-visibility model (it ignores the moon’s altitude and elongation).The year begins with the month whose 15th day (Passover) is the first on or after the vernal equinox — a standard approximation of the aviv rule.
The underlying astronomy (true conjunction, sunset, equinox) is verified, but the resulting calendar is not validated against actual Karaite practice and must not be used to determine observance.
- hebrewcal.calendars_alt.karaite.months_in_year(year)[source]¶
Return the number of months in the Karaite
year(12 or 13).
- hebrewcal.calendars_alt.karaite.last_day_of_month(year, month)[source]¶
Return the number of days in
monthofyear(29 or 30).