0
# Easter Date Calculation
1
2
Computation of Easter Sunday dates using Western, Orthodox, and Julian calendar algorithms for any given year. Supports three different calculation methods based on historical and regional requirements.
3
4
## Capabilities
5
6
### Easter Date Function
7
8
```python { .api }
9
def easter(year, method=EASTER_WESTERN):
10
"""
11
Calculate Easter date for a given year using specified method.
12
13
This implementation is based on algorithms by GM Arts and Claus Tondering,
14
derived from Ouding (1940) as quoted in "Explanatory Supplement to the
15
Astronomical Almanac" by P. Kenneth Seidelmann.
16
17
Parameters:
18
- year (int): Year for which to calculate Easter
19
- method (int, optional): Calculation method constant (default: EASTER_WESTERN)
20
21
Returns:
22
datetime.date: Easter Sunday date for the specified year
23
24
Raises:
25
ValueError: If year is outside valid range for the method
26
"""
27
```
28
29
### Method Constants
30
31
```python { .api }
32
EASTER_JULIAN = 1 # Original Julian calendar calculation (valid after 326 AD)
33
EASTER_ORTHODOX = 2 # Orthodox method in Gregorian calendar (1583-4099)
34
EASTER_WESTERN = 3 # Western/Gregorian method (1583-4099) - default
35
```
36
37
**Method Details:**
38
39
- **EASTER_JULIAN (1)**: Original calculation in Julian calendar, valid for dates after 326 AD
40
- **EASTER_ORTHODOX (2)**: Original method with date converted to Gregorian calendar, valid 1583-4099
41
- **EASTER_WESTERN (3)**: Revised method in Gregorian calendar, valid 1583-4099 (default)
42
43
## Usage Examples
44
45
### Basic Easter Calculation
46
47
```python
48
from dateutil.easter import easter, EASTER_WESTERN, EASTER_ORTHODOX, EASTER_JULIAN
49
from datetime import date
50
51
# Calculate Easter for different years using Western method (default)
52
easter_2023 = easter(2023) # April 9, 2023
53
easter_2024 = easter(2024) # March 31, 2024
54
easter_2025 = easter(2025) # April 20, 2025
55
56
print(f"Easter 2023: {easter_2023}")
57
print(f"Easter 2024: {easter_2024}")
58
print(f"Easter 2025: {easter_2025}")
59
```
60
61
### Different Calculation Methods
62
63
```python
64
from dateutil.easter import easter, EASTER_WESTERN, EASTER_ORTHODOX, EASTER_JULIAN
65
66
year = 2023
67
68
# Compare different methods for the same year
69
western_easter = easter(year, EASTER_WESTERN)
70
orthodox_easter = easter(year, EASTER_ORTHODOX)
71
julian_easter = easter(year, EASTER_JULIAN)
72
73
print(f"Western Easter {year}: {western_easter}") # April 9, 2023
74
print(f"Orthodox Easter {year}: {orthodox_easter}") # April 16, 2023
75
print(f"Julian Easter {year}: {julian_easter}") # April 16, 2023
76
```
77
78
### Easter Date Range Analysis
79
80
```python
81
from dateutil.easter import easter
82
from datetime import date
83
84
def analyze_easter_dates(start_year, end_year):
85
"""Analyze Easter date patterns over a range of years."""
86
easter_dates = []
87
88
for year in range(start_year, end_year + 1):
89
easter_date = easter(year)
90
easter_dates.append((year, easter_date))
91
92
# Find earliest and latest Easter dates
93
earliest = min(easter_dates, key=lambda x: (x[1].month, x[1].day))
94
latest = max(easter_dates, key=lambda x: (x[1].month, x[1].day))
95
96
print(f"Easter date analysis ({start_year}-{end_year}):")
97
print(f"Earliest: {earliest[1]} in {earliest[0]}")
98
print(f"Latest: {latest[1]} in {latest[0]}")
99
100
return easter_dates
101
102
# Analyze Easter dates for a decade
103
easter_analysis = analyze_easter_dates(2020, 2030)
104
```
105
106
### Integration with Other dateutil Components
107
108
```python
109
from dateutil.easter import easter
110
from dateutil.relativedelta import relativedelta
111
from datetime import datetime
112
113
def get_easter_week_dates(year):
114
"""Get dates for entire Easter week."""
115
easter_sunday = easter(year)
116
117
# Calculate related dates
118
palm_sunday = easter_sunday - relativedelta(weeks=1)
119
maundy_thursday = easter_sunday - relativedelta(days=3)
120
good_friday = easter_sunday - relativedelta(days=2)
121
easter_monday = easter_sunday + relativedelta(days=1)
122
123
return {
124
'palm_sunday': palm_sunday,
125
'maundy_thursday': maundy_thursday,
126
'good_friday': good_friday,
127
'easter_sunday': easter_sunday,
128
'easter_monday': easter_monday
129
}
130
131
# Get Easter week dates for 2023
132
easter_week_2023 = get_easter_week_dates(2023)
133
for day_name, date_obj in easter_week_2023.items():
134
print(f"{day_name.replace('_', ' ').title()}: {date_obj}")
135
```
136
137
### Business Applications
138
139
```python
140
from dateutil.easter import easter
141
from dateutil.relativedelta import relativedelta
142
143
def get_holiday_schedule(year):
144
"""Generate common Easter-related holidays for business calendar."""
145
easter_date = easter(year)
146
147
holidays = {
148
'good_friday': easter_date - relativedelta(days=2),
149
'easter_sunday': easter_date,
150
'easter_monday': easter_date + relativedelta(days=1),
151
}
152
153
return holidays
154
155
def is_easter_holiday(date_obj, year=None):
156
"""Check if a date is an Easter-related holiday."""
157
if year is None:
158
year = date_obj.year
159
160
holidays = get_holiday_schedule(year)
161
return date_obj in holidays.values()
162
163
# Example usage
164
from datetime import date
165
166
test_date = date(2023, 4, 7) # Good Friday 2023
167
print(f"Is {test_date} an Easter holiday? {is_easter_holiday(test_date)}")
168
```
169
170
### Historical Analysis
171
172
```python
173
from dateutil.easter import easter, EASTER_WESTERN, EASTER_ORTHODOX
174
175
def compare_easter_methods(year_range):
176
"""Compare Western and Orthodox Easter dates over time."""
177
differences = []
178
179
for year in year_range:
180
western = easter(year, EASTER_WESTERN)
181
orthodox = easter(year, EASTER_ORTHODOX)
182
183
if western != orthodox:
184
day_diff = (orthodox - western).days
185
differences.append((year, western, orthodox, day_diff))
186
187
return differences
188
189
# Compare methods for recent years
190
recent_years = range(2020, 2031)
191
easter_differences = compare_easter_methods(recent_years)
192
193
print("Years where Western and Orthodox Easter differ:")
194
for year, western, orthodox, diff in easter_differences:
195
print(f"{year}: Western {western}, Orthodox {orthodox} ({diff} days difference)")
196
```
197
198
## Algorithm Background
199
200
The Easter calculation algorithms implement three different approaches:
201
202
1. **Julian Method**: Original algorithm valid after 326 AD, based on Julian calendar
203
2. **Orthodox Method**: Uses original algorithm but converts result to Gregorian calendar
204
3. **Western Method**: Revised algorithm designed for Gregorian calendar
205
206
All methods are based on the lunar cycle and astronomical calculations established by the Council of Nicaea in 325 AD, which defined Easter as the first Sunday after the first full moon occurring on or after the spring equinox.
207
208
## References
209
210
- **GM Arts**: [Easter Algorithms](http://www.gmarts.org/index.php?go=415)
211
- **Claus Tondering**: [The Calendar FAQ: Easter](https://www.tondering.dk/claus/cal/easter.php)
212
- **Explanatory Supplement to the Astronomical Almanac** by P. Kenneth Seidelmann
213
214
## Types
215
216
```python { .api }
217
from datetime import date
218
219
# Easter calculation function
220
def easter(year: int, method: int = EASTER_WESTERN) -> date: ...
221
222
# Method constants
223
EASTER_JULIAN: int = 1
224
EASTER_ORTHODOX: int = 2
225
EASTER_WESTERN: int = 3
226
227
# Parameter and return types
228
EasterMethod = int # One of the three method constants
229
EasterYear = int # Year for calculation (valid ranges depend on method)
230
EasterDate = date # Returned Easter date
231
```