Quick start

This page walks through the most common tasks. Every example is runnable as-is and the printed output is exactly what the current version produces.

Import the public API

The package root re-exports the everyday surface:

from hebrewcal import (
    GregorianDate,
    JulianDate,
    HebrewDate,
    Weekday,
    to_gregorian,
    to_julian,
    to_hebrew,
    weekday,
)

Create dates

Each calendar has an immutable date type. Construction validates the date and raises ValueError on impossible values (e.g. 30 Iyyar, a month that only has 29 days).

GregorianDate(2026, 6, 26)
JulianDate(1582, 10, 4)
HebrewDate(5785, 7, 1)   # 1 Tishri 5785

Hebrew month numbering

Months are numbered in the standard scheme: Nisan = 1, Iyyar = 2, …, Tishri = 7, …, Adar (or Adar I in a leap year) = 12, Adar II = 13. The civil year begins at Tishri. See Month and weekday names for the full table.

Convert between calendars

>>> from hebrewcal import GregorianDate, HebrewDate, to_hebrew, to_gregorian, to_julian
>>> to_hebrew(GregorianDate(2024, 10, 3))
HebrewDate(year=5785, month=7, day=1)
>>> to_gregorian(HebrewDate(5785, 7, 1))
GregorianDate(year=2024, month=10, day=3)
>>> to_julian(GregorianDate(2026, 6, 26))
JulianDate(year=2026, month=6, day=13)

Find the weekday

>>> from hebrewcal import GregorianDate, weekday
>>> weekday(GregorianDate(1867, 10, 31))
<Weekday.THURSDAY: 4>
>>> weekday(GregorianDate(1867, 10, 31)).name
'THURSDAY'

Work with the Rata Die day count

Every date exposes to_rd() and from_rd():

>>> from hebrewcal import GregorianDate
>>> GregorianDate(2026, 6, 26).to_rd()
739793
>>> GregorianDate.from_rd(739793)
GregorianDate(year=2026, month=6, day=26)

Parse and format

>>> from hebrewcal.parsing.dates import parse_gregorian
>>> parse_gregorian("26.06.2026")
GregorianDate(year=2026, month=6, day=26)

>>> from hebrewcal.formatting.dates import format_hebrew
>>> from hebrewcal import HebrewDate
>>> format_hebrew(HebrewDate(5785, 7, 1), style="named")
'1 Tishri 5785'

Hebrew numerals (gematria)

>>> from hebrewcal.numerals import to_hebrew_numeral, from_hebrew_numeral
>>> to_hebrew_numeral(5785)
'ה׳תשפ״ה'
>>> from_hebrew_numeral("ה׳תשפ״ה")
5785

Where to go next: the User guide explains each subsystem in depth, and Examples collects longer, real-world snippets.