KTcalendars

KTCalendars is a library providing utility classes for country-specific holiday-aware calendars and dates.

It builds on the holidays package and provides:

• KTDay — a rich day object with date parsing, arithmetic, comparisons and holiday/work-day checks.
• KTCalendar — a calendar.Calendar subclass bound to a country calendar, with configurable weekend days and work-day and week iteration helpers.
• AbstractConfiguration — a pluggable configuration class centralising holiday overrides (e.g. company closures) and the default country calendar code.
• KTDateRange — a psycopg DateRange subclass with PostgreSQL-canonical [) bounds, KTDay iteration and rich comparison, containment and intersection helpers (requires the psycopg extra).

from ktcalendars import KTCalendar

cal = KTCalendar(country_code="IT")
day = cal.get_ktday("2025-06-02")  # Festa della Repubblica
day.is_holiday                     # True
day.is_workday                     # False
cal.get_work_days("2025-06-01", "2025-06-08")
# [K2025-06-03, K2025-06-04, K2025-06-05, K2025-06-06]

Day parsing, arithmetic and comparisons

from ktcalendars import KTDay

day = KTDay("2025-06-02")   # also "2025/06/02", "20250602", a date, a KTDay or None (today)
day.day_of_week             # 'Monday'
day + 7                     # K2025-06-09
day - KTDay("2025-05-31")   # 2 (days)
day == "2025-06-02"         # True
list(KTDay("2025-06-01").range_to("2025-06-03"))
# [K2025-06-01, K2025-06-02, K2025-06-03]

Weekend days per country

KTCalendar(country_code="EG").weekend_days   # (4, 5) — Friday and Saturday
KTCalendar(country_code="IT").weekend_days   # (5, 6) — Saturday and Sunday

cal = KTCalendar(country_code="IT", weekends=(6,))  # Sunday-only weekend
cal.get_ktday("2025-06-07").is_weekend       # False (a Saturday)

Week and month iteration

cal = KTCalendar(country_code="IT")
cal.week_for("2025-06-04")           # (K2025-06-02, K2025-06-08)
list(cal.iter_week("2025-06-04"))    # the seven days of that week
list(cal.month_weeks_days(2025, 6))  # complete weeks covering June 2025

Date ranges

KTDateRange (requires the psycopg extra) stores date ranges in the PostgreSQL canonical form — lower bound included, upper bound excluded:

from ktcalendars.ranges import KTDateRange

r = KTDateRange("2025-06-01", "2025-06-04")           # upper bound excluded
list(r)                                               # [K2025-06-01, K2025-06-02, K2025-06-03]
KTDateRange.from_start_end("2025-06-01", "2025-06-03")  # both bounds included, same range

"2025-06-03" in r                                     # True
r.overlap(KTDateRange("2025-06-03", "2025-06-10"))    # True
r.intersection(("2025-06-03", "2025-06-10"))          # [2025-06-03:2025-06-04)
r.precedes("2025-06-04")                              # True — adjacent, just before that day

Company-specific holidays

Point the KTCALENDAR_CONFIG environment variable to a subclass of AbstractConfiguration to add your own holidays on top of the official country calendars:

import datetime

from ktcalendars import AbstractConfiguration


class CompanyConfiguration(AbstractConfiguration):
    def get_holiday_overrides(self, country_calendar_code, from_date=None, to_date=None):
        return {datetime.date(2025, 12, 24): "Christmas Eve closure"}

export KTCALENDAR_CONFIG=mypackage.config.CompanyConfiguration

See the documentation for configuration and usage, and the changelog for notable changes between releases.

Requirements

• Python 3.10 or later

Installation

Install ktcalendars using your package manager of choice, e.g. Pip:

pip install ktcalendars

To use KTDateRange, install the psycopg extra:

pip install ktcalendars[psycopg]

Bug reports and requests for enhancements

Please open an issue on the project's issue tracker on GitHub.

Contributing to the project

See the contribution guide.

Licensing

Licensed under the Apache License 2.0.