Textual Timepiece

Various time management related widgets for the Textual framework.

Documentation | Changelog | PyPi

Included Widgets

Pickers	Description
DatePicker	A visual date picker with an input and overlay.
DurationPicker	Visual duration picker with duration up to 99 hours.
TimePicker	Visual time picker for setting a time in a 24 hour clock.
DateTimePicker	Datetime picker that combines a date and time.
DateRangePicker	Date range picker for picking an interval between two dates.
DateTimeRangePicker	Range picker for picking an interval between two times.
DateTimeDurationPicker	Pick an interval between two times, including a duration input.

Activity Heatmap	Description
ActivityHeatmap	Activity Heatmap for displaying yearly data similar to the GitHub contribution graph.
HeatmapManager	Widget for browsing the Activity Heatmap with yearly navigation builtin.

Timeline	Description
HorizontalEntry	Horizontal entry for a horizontal timeline layout.
HorizontalRuler	Horizontal ruler for marking horizontal timelines.
HorizontalTimeline	Basic timeline widget that displays entries in a horizontal view.
HorizontalTimelineNavigation	Horizontal widget containing a horizontal timeline and header.
RuledHorizontalTimeline	Ruled horizontal timeline with markers.
RuledVerticalTimeline	Ruled vertical timeline with markers.
VerticalEntry	Vertical entry for a vertical timeline layout.
VerticalRuler	Vertical ruler for marking vertical timelines.
VerticalTimeline	Basic timeline widget that displays entries in a vertical view.
VerticalTimelineNavigation	Vertical widget containing a vertical timeline and header.

Selector	Description
DateSelect	Date selection widget with calendar panes.
TimeSelect	Time selection widget with various times in 30 minute intervals.
DurationSelect	Duration selection widget with modifiers for adjust time or duration.

Input	Description
DateInput	Date input which takes in a iso-format date.
TimeInput	Time input that takes in 24 hour clocked in a HH:MM:SS format.
DurationInput	Duration input with a duration up to 99 hours.
DateTimeInput	An input with a combination of a date and time in iso-format.

Demo

UVX

uvx textual-timepiece

PIPX

pipx run textual-timepiece

Install

Pip

pip install textual-timepiece

UV

uv add textual-timepiece

Poetry

poetry add textual-timepiece

Note

Requires whenever as an additional dependency.

Quick Start

DatePicker

Code

from textual.app import App, ComposeResult
from textual_timepiece.pickers import DatePicker
from whenever import Date

class DatePickerApp(App[None]):
    def compose(self) -> ComposeResult:
        yield DatePicker(Date(2025, 3, 4))

if __name__ == "__main__":
    DatePickerApp().run()

Result

DateTimePicker

Code

from textual.app import App, ComposeResult
from textual_timepiece.pickers import DateTimePicker
from whenever import SystemDateTime

class DateTimePickerApp(App[None]):
    def compose(self) -> ComposeResult:
        yield DateTimePicker(SystemDateTime(2025, 3, 4, 9, 42, 47)))

if __name__ == "__main__":
    DateTimePickerApp().run()

Result

ActivityHeatmap

Code

import random
from collections import defaultdict

from textual.app import App, ComposeResult
from textual_timepiece.activity_heatmap import ActivityHeatmap, HeatmapManager


class ActivityApp(App[None]):
    def _on_heatmap_manager_year_changed(
        self,
        message: HeatmapManager.YearChanged,
    ) -> None:
        message.stop()
        self.set_heatmap_data(message.year)

    def retrieve_data(self, year: int) -> ActivityHeatmap.ActivityData:
        """Placeholder example on how the data could be generated."""
        random.seed(year)
        template = ActivityHeatmap.generate_empty_activity(year)
        return defaultdict(
            lambda: 0,
            {
                day: random.randint(6000, 20000)
                for week in template
                for day in week
                if day
            },
        )

    def set_heatmap_data(self, year: int) -> None:
        """Sets the data based on the current data."""
        self.query_one(ActivityHeatmap).values = self.retrieve_data(year)

    def _on_mount(self) -> None:
        self.set_heatmap_data(2025)

    def compose(self) -> ComposeResult:
        yield HeatmapManager(2025)


if __name__ == "__main__":
    ActivityApp().run()

Result

• More examples can be found here

License

MIT. Check LICENSE for more information.