PyCalverter

1.6.1 verified Fri May 01 auth: no python

PyCalverter is a Python library for converting between various calendar systems, including Gregorian, Julian, Islamic, Hebrew, Persian, Indian civil, Baháʼí, and more. Version 1.6.1 is the current release, with intermittent updates.

pip install pycalverter

Common errors

error ModuleNotFoundError: No module named 'pycalverter' ↓

cause Library not installed or installed in incorrect environment.

fix

Run 'pip install pycalverter' in the active Python environment.

error KeyError: 'GREGORIAN' ↓

cause Using wrong case for calendar name or calendar not supported.

fix

Use exactly 'GREGORIAN', 'JULIAN', 'ISLAMIC', 'HEBREW', 'PERSIAN', 'INDIAN_CIVIL', 'BAHAI'. Check spelling and caps.

error AttributeError: module 'pycalverter' has no attribute 'CalendarConverter' ↓

cause Trying to import CalendarConverter incorrectly (e.g., import pycalverter then pycalverter.CalendarConverter).

fix

Use 'from pycalverter import CalendarConverter'.

Warnings

gotcha Calendar converter instances are stateful: calling to_jdn multiple times with different calendars will reuse internal state, causing incorrect results. Reinitialize or use separate instances. ↓

fix Create a new CalendarConverter for each conversion or use the module-level functions if available (but there are none). Safer: conv = CalendarConverter(...) per call.

gotcha Calendar names are case-sensitive and must be exactly as defined (e.g., 'GREGORIAN', 'ISLAMIC'). Wrong casing leads to KeyError. ↓

fix Use uppercase strings exactly: 'GREGORIAN', 'JULIAN', 'ISLAMIC', 'HEBREW', 'PERSIAN', 'INDIAN_CIVIL', 'BAHAI'.

breaking In version 1.6.0, the API changed: CalendarConverter initialization no longer accepts a calendar argument; it is now passed to the conversion methods. Older code using conv = CalendarConverter('GREGORIAN') will break. ↓

fix Use conv = CalendarConverter() and specify calendar in to_jdn and from_jdn: conv.to_jdn(year, month, day, 'GREGORIAN')

Imports

CalendarConverter
wrong
```
import pycalverter
```
correct
```
from pycalverter import CalendarConverter
```
The class is not directly at the top level; you need to import CalendarConverter explicitly.
JULIAN
```
from pycalverter import JULIAN
```
Calendar constants are also available from the package.

Quickstart

Initialize a CalendarConverter, use to_jdn/from_jdn for conversions. Supported calendars: GREGORIAN, JULIAN, ISLAMIC, HEBREW, PERSIAN, INDIAN_CIVIL, BAHAI, etc.

from pycalverter import CalendarConverter

# Convert Gregorian date to Julian Day Number
conv = CalendarConverter()
jdn = conv.to_jdn(2025, 5, 1, 'GREGORIAN')
print(jdn)  # e.g. 2460783

# Convert from Julian Day Number to Islamic date
year, month, day = conv.from_jdn(jdn, 'ISLAMIC')
print(f"Islamic: {year}-{month}-{day}")