calendar-generator is a zero-dependency Python module that generates complete calendar-dimension data including year, month, day, quarter, weekday, and more. It is designed to be extremely fast by primarily using integer math. The only date object instantiated is the initial date for a simple weekday check, making it highly efficient for generating large date ranges.
I wrote this initially to teach myself how to back into dates/date properties via integer math and generate a calendar table for my Django application. It turned out to be reasonably performant, generating all calendar dates from 1900 - 2100 in .0635s on average vs. .1s~ for stdlib object-based loops (i.e. using calendar or datetime), but slower than vectorized date ranges generated by NumPy/C-based libraries that run in .03s~. But, since this is dependency-free/framework agnostic, I decided to share this code in case others would find it useful! I think it is also useful as a reference to understand how the underlying functions work as integer math.
At the end of the day, we're only talking about fractions of a second - so this only really matters if you're generating a lot of date data repeatedly over multiple years. This just showing what's possible with very simple loops/integer math.
- Any application requiring fast, detailed calendar data generation.
- Integrating with Django or other web frameworks for calendar-based features.
- Populating date dimension tables in data warehouses.
- Data analytics and business intelligence reporting pipelines.
I was going to publish this via PyPi and make it accessible via pip, but since the code is really only 200-300 lines of core functions, I suggest reading the source code and copying it/modifying it for your own use case. The current API/data generated is detailed below.
Generates a list of calendar date dictionaries from start_date to end_date (inclusive). Dates should be provided as integers (e.g. 2020). The full year(s) will be generated. Here is a simple example of how to import and use the generator:
from calendar_generator import generate_calendar_dates
# Generate calendar dates from 2020-01-01 to 2025-12-31.
calendar_dates = generate_calendar_dates(2020, 2025)
for date_info in calendar_dates:
print(date_info)Each entry in the generated list is a CalendarDate dictionary (TypedDict) with the following fields:
class CalendarDate(TypedDict):
d: str # A datestring generated in ISO format. e.g. 2022-01-07
year: int # The year of the date
quarter: int # The calendar quarter of the date
month: int # The month of the date (1-12)
day: int # The day of the date
day_of_year: int # The cumulative day of the year for the date, incremented from 1-365 (366 for leap years)
week: int # The week of the date (starts from 1 when the year changes)
weekday: int # The Python weekday of the date (0-6); 0 = Monday, 6 = Sunday
days_in_month: int # The number of days in the month of the date
days_in_year: int # The number of days in the year (365 for non-leap, 366 for leap)
is_leap_year: bool # True if the year is a leap, False otherwise
is_weekend: bool # True if the date's weekday is Sat/Sun (5 or 6), False if not.
is_month_end: bool # True if the day of the date == the days in the month.
is_quarter_end: bool # True if the date matches the end of the calendar quarter (e.g. 03/31 would be the end of Q1)
is_year_end: bool # True if the day_of_year is == the days in year. This triggers a shift to the next year in main loop.
- Generates comprehensive calendar dimension data: year, month, day, quarter, ISO week, weekday, etc.
- Uses integer arithmetic to maximize performance.
- No external dependencies - written in pure Python.
- Returns data as a list of
CalendarDateobjects for easy integration with data pipelines or web applications. - Suitable for large date ranges and high-performance applications.
This project is licensed under the MIT License. See the LICENSE file for details.