Julian Dates from Proleptic Gregorian and Julian Calendars

1.4.1 · maintenance · verified Fri Apr 10

jdcal is a Python module designed for converting between Julian dates and calendar dates, supporting both proleptic Gregorian and Julian calendars. It enhances precision by storing Julian dates as a pair of floating-point numbers. The library provides functions for conversions in both directions (e.g., `gcal2jd` for Gregorian to Julian Date, and `jd2gcal` for the reverse). The current version is 1.4.1, with its last update in April 2019, suggesting a maintenance-focused release cadence.

Warnings

gotcha Julian dates are returned and expected as two separate floating-point numbers (jd1, jd2) to maintain maximum precision. Always handle both components for calculations.
Fix: Always pass and receive Julian dates as a tuple of two floats. For the full Julian date, sum `jd1 + jd2`.
gotcha The library uses 'proleptic' calendars, meaning Gregorian and Julian calendar rules are applied to dates even before their historical adoption. This may not align with historical calendar usage in specific regions.
Fix: Be aware that conversions for dates far in the past apply modern calendar rules. For historical accuracy, external logic might be needed to determine the correct calendar system for a given date.
breaking Installation of `jdcal==1.0` via `pip` was problematic due to a missing `LICENSE.txt` file in the PyPI tarball, leading to installation failures.
Fix: Avoid installing version 1.0 directly. Use the latest stable version (`pip install jdcal`) or a version greater than 1.0.
gotcha Older versions of `openpyxl` (a dependency of `jdcal` for some users, but not a direct dependency *of* `jdcal`) had integration issues leading to `ImportError` if `jdcal` was not installed or if installation order was incorrect.
Fix: Ensure `jdcal` is installed before `openpyxl` if using older versions of `openpyxl` that explicitly relied on it, or upgrade `openpyxl` to a newer version where this is less of an issue. `jdcal` itself does not have a dependency on `openpyxl`.

Install

pip install jdcal Install jdcal

Imports

gcal2jd
```
from jdcal import gcal2jd
```
jd2gcal
```
from jdcal import jd2gcal
```
jcal2jd
```
from jdcal import jcal2jd
```
jd2jcal
```
from jdcal import jd2jcal
```

Quickstart

This example demonstrates how to convert a Gregorian date to a Julian date using `gcal2jd` and then convert it back to a Gregorian date using `jd2gcal`.

from jdcal import gcal2jd, jd2gcal

# Convert Gregorian date to Julian date
year, month, day = 2000, 1, 1
jd1, jd2 = gcal2jd(year, month, day)
print(f"Gregorian {year}-{month}-{day} is Julian Date: {jd1} + {jd2} = {jd1 + jd2}")

# Convert Julian date back to Gregorian date
g_year, g_month, g_day, g_fraction = jd2gcal(jd1, jd2)
print(f"Julian Date {jd1} + {jd2} converts to Gregorian: {g_year}-{g_month}-{g_day} (fraction: {g_fraction})")

view raw JSON →