feat: add month calendar

docs/examples/widgets/month_calendar.py

@@ -0,0 +1,12 @@
+from textual.app import App, ComposeResult
+from textual.widgets import MonthCalendar
+
+
+class MonthCalendarApp(App):
+    def compose(self) -> ComposeResult:
+        yield MonthCalendar(year=2021, month=6)
+
+
+if __name__ == "__main__":
+    app = MonthCalendarApp()
+    app.run()

src/textual/widgets/__init__.py

@@ -26,6 +26,7 @@
     from ._loading_indicator import LoadingIndicator
     from ._log import Log
     from ._markdown import Markdown, MarkdownViewer
+    from ._month_calendar import MonthCalendar
     from ._option_list import OptionList
     from ._placeholder import Placeholder
     from ._pretty import Pretty
@@ -64,6 +65,7 @@
     "Log",
     "Markdown",
     "MarkdownViewer",
+    "MonthCalendar",
     "OptionList",
     "Placeholder",
     "Pretty",

src/textual/widgets/__init__.pyi

@@ -16,6 +16,7 @@ from ._loading_indicator import LoadingIndicator as LoadingIndicator
 from ._log import Log as Log
 from ._markdown import Markdown as Markdown
 from ._markdown import MarkdownViewer as MarkdownViewer
+from ._month_calendar import MonthCalendar as MonthCalendar
 from ._option_list import OptionList as OptionList
 from ._placeholder import Placeholder as Placeholder
 from ._pretty import Pretty as Pretty

src/textual/widgets/_month_calendar.py

@@ -0,0 +1,107 @@
+from __future__ import annotations
+
+import calendar
+import datetime
+
+from rich.text import Text
+from textual.app import ComposeResult
+from textual.reactive import Reactive, var
+from textual.widget import Widget
+from textual.widgets import DataTable
+
+
+class InvalidMonthNumber(Exception):
+    pass
+
+
+class InvalidWeekdayNumber(Exception):
+    pass
+
+
+class MonthCalendar(Widget):
+    year: Reactive[int | None] = Reactive[int | None](None)
+    month: Reactive[int | None] = Reactive[int | None](None)
+    first_weekday: Reactive[int] = Reactive(0)
+    _calendar: var[calendar.Calendar] = var(calendar.Calendar())
+
+    def __init__(
+        self,
+        year: int | None = None,
+        month: int | None = None,
+        first_weekday: int = 0,
+        *,
+        name: str | None = None,
+        id: str | None = None,
+        classes: str | None = None,
+        disabled: bool = False,
+    ) -> None:
+        super().__init__(name=name, id=id, classes=classes, disabled=disabled)
+        self.year = year
+        self.month = month
+        self.first_weekday = first_weekday
+
+    def compose(self) -> ComposeResult:
+        yield DataTable()
+
+    def on_mount(self) -> None:
+        self._update_week_header()
+        self._update_calendar_days()
+
+    def _update_week_header(self) -> None:
+        table = self.query_one(DataTable)
+        day_names = calendar.day_abbr
+        for day in self._calendar.iterweekdays():
+            table.add_column(day_names[day])
+
+    def _update_calendar_days(self) -> None:
+        table = self.query_one(DataTable)
+        table.clear()
+        for week in self.calendar_dates:
+            table.add_row(*[self._format_day(date) for date in week])
+
+    @property
+    def calendar_dates(self) -> list[list[datetime.date]]:
+        """
+        A matrix of `datetime.date` objects for this month calendar. Each row
+        represents a week, including dates before the start of the month
+        or after the end of the month that are required to get a complete week.
+        """
+        assert self.year is not None and self.month is not None
+        dates = list(self._calendar.itermonthdates(self.year, self.month))
+        return [dates[i : i + 7] for i in range(0, len(dates), 7)]
+
+    def _format_day(self, date: datetime.date) -> Text:
+        formatted_day = Text(str(date.day), justify="center")
+        if date.month != self.month:
+            formatted_day.style = "grey37"
+        return formatted_day
+
+    def _compute__calendar(self) -> calendar.Calendar:
+        return calendar.Calendar(self.first_weekday)
+
+    def validate_year(self, year: int | None) -> int:
+        if year is None:
+            current_year = datetime.date.today().year
+            return current_year
+        return year
+
+    def validate_month(self, month: int | None) -> int:
+        if month is None:
+            current_month = datetime.date.today().month
+            return current_month
+        if not 1 <= month <= 12:
+            raise InvalidMonthNumber("Month number must be 1-12.")
+        return month
+
+    def validate_first_weekday(self, first_weekday: int) -> int:
+        if not 0 <= first_weekday <= 6:
+            raise InvalidWeekdayNumber(
+                "Weekday number must be 0 (Monday) to 6 (Sunday)."
+            )
+        return first_weekday
+
+    # def watch_year(self) -> None:
+    #     self._update_calendar_days()
+
+    # def _watch_month(self) -> None:
+    #     self._update_calendar_days()

src/textual/widgets/month_calendar.py

@@ -0,0 +1,6 @@
+from ._month_calendar import InvalidMonthNumber, InvalidWeekdayNumber
+
+__all__ = [
+    "InvalidMonthNumber",
+    "InvalidWeekdayNumber",
+]

tests/test_month_calendar.py

@@ -0,0 +1,103 @@
+import datetime
+
+import pytest
+from textual.app import App, ComposeResult
+from textual.coordinate import Coordinate
+from textual.widgets import DataTable, MonthCalendar
+from textual.widgets.month_calendar import InvalidMonthNumber, InvalidWeekdayNumber
+
+
+def test_year_defaults_to_current_year_if_none_provided():
+    month_calendar = MonthCalendar()
+    current_year = datetime.date.today().year
+    assert month_calendar.year == current_year
+
+
+def test_month_defaults_to_current_month_if_none_provided():
+    month_calendar = MonthCalendar()
+    current_month = datetime.date.today().month
+    assert month_calendar.month == current_month
+
+
+def test_invalid_month_number_raises_exception():
+    with pytest.raises(InvalidMonthNumber):
+        month_calendar = MonthCalendar(month=13)
+
+
+def test_invalid_weekday_number_raises_exception():
+    with pytest.raises(InvalidWeekdayNumber):
+        month_calendar = MonthCalendar(first_weekday=7)
+
+
+def test_first_weekday_computes_calendar_object():
+    month_calendar = MonthCalendar(first_weekday=6)
+    assert month_calendar._calendar.firstweekday == 6
+    month_calendar.first_weekday = 0
+    assert month_calendar._calendar.firstweekday == 0
+
+
+def test_calendar_dates_property():
+    month_calendar = MonthCalendar(year=2021, month=6)
+    first_monday = datetime.date(2021, 5, 31)
+    expected_date = first_monday
+    for week in range(len(month_calendar.calendar_dates)):
+        for day in range(0, 7):
+            assert month_calendar.calendar_dates[week][day] == expected_date
+            expected_date += datetime.timedelta(days=1)
+
+
+class MonthCalendarApp(App):
+    def compose(self) -> ComposeResult:
+        yield MonthCalendar(year=2021, month=6)
+
+
+async def test_calendar_table_week_header():
+    app = MonthCalendarApp()
+    async with app.run_test() as pilot:
+        month_calendar = pilot.app.query_one(MonthCalendar)
+        table = month_calendar.query_one(DataTable)
+        actual_labels = [col.label.plain for col in table.columns.values()]
+        expected_labels = ["Mon", "Tue", "Wed", "Thu", "Fri", "Sat", "Sun"]
+        assert actual_labels == expected_labels
+
+
+async def test_calendar_table_days():
+    app = MonthCalendarApp()
+    async with app.run_test() as pilot:
+        month_calendar = pilot.app.query_one(MonthCalendar)
+        table = month_calendar.query_one(DataTable)
+        for row, week in enumerate(month_calendar.calendar_dates):
+            for column, date in enumerate(week):
+                actual_day = table.get_cell_at(Coordinate(row, column)).plain
+                expected_day = str(date.day)
+                assert actual_day == expected_day
+
+
+# async def test_calendar_table_after_reactive_year_change():
+#     app = MonthCalendarApp()
+#     async with app.run_test() as pilot:
+#         month_calendar = pilot.app.query_one(MonthCalendar)
+#
+#         month_calendar.year = 2023
+#
+#         table = month_calendar.query_one(DataTable)
+#         for row, week in enumerate(month_calendar.calendar_dates):
+#             for column, date in enumerate(week):
+#                 actual_day = table.get_cell_at(Coordinate(row, column)).plain
+#                 expected_day = str(date.day)
+#                 assert actual_day == expected_day
+#
+#
+# async def test_calendar_table_after_reactive_month_change():
+#     app = MonthCalendarApp()
+#     async with app.run_test() as pilot:
+#         month_calendar = pilot.app.query_one(MonthCalendar)
+#
+#         month_calendar.month = 7
+#
+#         table = month_calendar.query_one(DataTable)
+#         for row, week in enumerate(month_calendar.calendar_dates):
+#             for column, date in enumerate(week):
+#                 actual_day = table.get_cell_at(Coordinate(row, column)).plain
+#                 expected_day = str(date.day)
+#                 assert actual_day == expected_day