Skip to content

codex_services.calendar.engine

engine

codex_services.calendar.engine

Universal calendar generator. Framework-agnostic (does not depend on Django).

Classes

CalendarEngine

Day matrix generator for a calendar.

Used for rendering UI (website, bot).

Source code in src/codex_services/calendar/engine.py 
 18
 19
 20
 21
 22
 23
 24
 25
 26
 27
 28
 29
 30
 31
 32
 33
 34
 35
 36
 37
 38
 39
 40
 41
 42
 43
 44
 45
 46
 47
 48
 49
 50
 51
 52
 53
 54
 55
 56
 57
 58
 59
 60
 61
 62
 63
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
class CalendarEngine:
    """
    Day matrix generator for a calendar.

    Used for rendering UI (website, bot).
    """

    @staticmethod
    def get_month_matrix(
        year: int,
        month: int,
        today: date,
        selected_date: date | None = None,
        holidays_subdiv: str = "ST",  # Default: Saxony-Anhalt
    ) -> list[dict[str, Any]]:
        """
        Generates a list of days for the calendar grid.

        Args:
            year: Year.
            month: Month.
            today: Current date (to determine past days).
            selected_date: Selected date (for 'active' status).
            holidays_subdiv: German region for holidays.

        Returns:
            List of dictionaries with day data.
        """
        de_holidays = holidays.country_holidays("DE", subdiv=holidays_subdiv, years=year)

        cal = calendar.Calendar(firstweekday=0)  # Mon - first day
        month_days = cal.itermonthdays(year, month)

        result: list[dict[str, Any]] = []
        for day_num in month_days:
            if day_num == 0:
                result.append({"num": "", "status": "empty"})
                continue

            calc_date = date(year, month, day_num)
            weekday = calc_date.weekday()

            # Base status
            status = "available"

            if calc_date < today or weekday == 6:
                status = "disabled"
            elif calc_date in de_holidays:
                status = "holiday"

            if selected_date and calc_date == selected_date:
                status = "active"

            day_data: dict[str, Any] = {
                "num": str(day_num),
                "date": calc_date.isoformat(),
                "status": status,
                "is_holiday": calc_date in de_holidays,
                "weekday": weekday,
            }
            result.append(day_data)

        return result

    @staticmethod
    def get_month_label(year: int, month: int, locale: str = "ru") -> str:
        """Returns the month name and year."""
        month_names_ru = {
            1: "Январь",
            2: "Февраль",
            3: "Март",
            4: "Апрель",
            5: "Май",
            6: "Июнь",
            7: "Июль",
            8: "Август",
            9: "Сентябрь",
            10: "Октябрь",
            11: "Ноябрь",
            12: "Декабрь",
        }
        # Other languages (de, en) can be added if necessary
        name = month_names_ru.get(month, "")
        return f"{name} {year}"
Functions
get_month_matrix(year, month, today, selected_date=None, holidays_subdiv='ST') staticmethod

Generates a list of days for the calendar grid.

Parameters:

Name Type Description Default
year int

Year.

 required
month int

Month.

 required
today date

Current date (to determine past days).

 required
selected_date date | None

Selected date (for 'active' status).

 None
holidays_subdiv str

German region for holidays.

 'ST'

Returns:

Type Description
list[dict[str, Any]]

List of dictionaries with day data.
Source code in src/codex_services/calendar/engine.py 
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
@staticmethod
def get_month_matrix(
    year: int,
    month: int,
    today: date,
    selected_date: date | None = None,
    holidays_subdiv: str = "ST",  # Default: Saxony-Anhalt
) -> list[dict[str, Any]]:
    """
    Generates a list of days for the calendar grid.

    Args:
        year: Year.
        month: Month.
        today: Current date (to determine past days).
        selected_date: Selected date (for 'active' status).
        holidays_subdiv: German region for holidays.

    Returns:
        List of dictionaries with day data.
    """
    de_holidays = holidays.country_holidays("DE", subdiv=holidays_subdiv, years=year)

    cal = calendar.Calendar(firstweekday=0)  # Mon - first day
    month_days = cal.itermonthdays(year, month)

    result: list[dict[str, Any]] = []
    for day_num in month_days:
        if day_num == 0:
            result.append({"num": "", "status": "empty"})
            continue

        calc_date = date(year, month, day_num)
        weekday = calc_date.weekday()

        # Base status
        status = "available"

        if calc_date < today or weekday == 6:
            status = "disabled"
        elif calc_date in de_holidays:
            status = "holiday"

        if selected_date and calc_date == selected_date:
            status = "active"

        day_data: dict[str, Any] = {
            "num": str(day_num),
            "date": calc_date.isoformat(),
            "status": status,
            "is_holiday": calc_date in de_holidays,
            "weekday": weekday,
        }
        result.append(day_data)

    return result
get_month_label(year, month, locale='ru') staticmethod

Returns the month name and year.

Source code in src/codex_services/calendar/engine.py 
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
@staticmethod
def get_month_label(year: int, month: int, locale: str = "ru") -> str:
    """Returns the month name and year."""
    month_names_ru = {
        1: "Январь",
        2: "Февраль",
        3: "Март",
        4: "Апрель",
        5: "Май",
        6: "Июнь",
        7: "Июль",
        8: "Август",
        9: "Сентябрь",
        10: "Октябрь",
        11: "Ноябрь",
        12: "Декабрь",
    }
    # Other languages (de, en) can be added if necessary
    name = month_names_ru.get(month, "")
    return f"{name} {year}"