https://github.com/ddkasa/textual-timepiece
Various time related widgets & functionality for Textual.
https://github.com/ddkasa/textual-timepiece
library python textual time whenever
Last synced: 6 months ago
JSON representation
Various time related widgets & functionality for Textual.
- Host: GitHub
- URL: https://github.com/ddkasa/textual-timepiece
- Owner: ddkasa
- License: mit
- Created: 2025-01-14T10:34:06.000Z (over 1 year ago)
- Default Branch: main
- Last Pushed: 2025-11-24T15:08:42.000Z (8 months ago)
- Last Synced: 2025-11-28T03:49:11.748Z (7 months ago)
- Topics: library, python, textual, time, whenever
- Language: Python
- Homepage: https://ddkasa.github.io/textual-timepiece/
- Size: 1.89 MB
- Stars: 16
- Watchers: 1
- Forks: 3
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE.md
Awesome Lists containing this project
README
[](https://pypi.org/project/textual-timepiece/)
[](https://pypi.org/project/textual-timepiece/)
[](https://github.com/ddkasa/textual-timepiece/actions/workflows/ci.yaml)
[](https://codecov.io/github/ddkasa/textual-timepiece)
[](https://textual.textualize.io/)
# Textual Timepiece
> Various time management related widgets for the [Textual](https://github.com/Textualize/textual) framework.
[Documentation](https://ddkasa.github.io/textual-timepiece/) | [Changelog](/docs/CHANGELOG.md) | [PyPi](https://pypi.org/project/textual-timepiece/)
Included Widgets
| Pickers | Description |
| :--------------------------------------------------------------------------------------------------------------------------------------- | :-------------------------------------------------------------- |
| [DatePicker](https://ddkasa.github.io/textual-timepiece/reference/pickers/#textual_timepiece.pickers.DatePicker) | A visual date picker with an input and overlay. |
| [DurationPicker](https://ddkasa.github.io/textual-timepiece/reference/pickers/#textual_timepiece.pickers.DurationPicker) | Visual duration picker with duration up to 99 hours. |
| [TimePicker](https://ddkasa.github.io/textual-timepiece/reference/pickers/#textual_timepiece.pickers.TimePicker) | Visual time picker for setting a time in a 24 hour clock. |
| [DateTimePicker](https://ddkasa.github.io/textual-timepiece/reference/pickers/#textual_timepiece.pickers.DateTimePicker) | Datetime picker that combines a date and time. |
| [DateRangePicker](https://ddkasa.github.io/textual-timepiece/reference/pickers/#textual_timepiece.pickers.DateRangePicker) | Date range picker for picking an interval between two dates. |
| [DateTimeRangePicker](https://ddkasa.github.io/textual-timepiece/reference/pickers/#textual_timepiece.pickers.DateTimeRangePicker) | Range picker for picking an interval between two times. |
| [DateTimeDurationPicker](https://ddkasa.github.io/textual-timepiece/reference/pickers/#textual_timepiece.pickers.DateTimeDurationPicker) | Pick an interval between two times, including a duration input. |
| Activity Heatmap | Description |
| :------------------------------------------------------------------------------------------------------------------------------------------- | :------------------------------------------------------------------------------------ |
| [ActivityHeatmap](https://ddkasa.github.io/textual-timepiece/reference/activity_heatmap/#textual_timepiece.activity_heatmap.ActivityHeatmap) | Activity Heatmap for displaying yearly data similar to the GitHub contribution graph. |
| [HeatmapManager](https://ddkasa.github.io/textual-timepiece/reference/activity_heatmap/#textual_timepiece.activity_heatmap.HeatmapManager) | Widget for browsing the Activity Heatmap with yearly navigation builtin. |
| Timeline | Description |
| :----------------------------------------------------------------------------------------------------------------------------------------------------- | :---------------------------------------------------------------- |
| [HorizontalEntry](https://ddkasa.github.io/textual-timepiece/reference/timeline/#textual_timepiece.timeline.HorizontalEntry) | Horizontal entry for a horizontal timeline layout. |
| [HorizontalRuler](https://ddkasa.github.io/textual-timepiece/reference/timeline/#textual_timepiece.timeline.HorizontalRuler) | Horizontal ruler for marking horizontal timelines. |
| [HorizontalTimeline](https://ddkasa.github.io/textual-timepiece/reference/timeline/#textual_timepiece.timeline.HorizontalTimeline) | Basic timeline widget that displays entries in a horizontal view. |
| [HorizontalTimelineNavigation](https://ddkasa.github.io/textual-timepiece/reference/timeline/#textual_timepiece.timeline.HorizontalTimelineNavigation) | Horizontal widget containing a horizontal timeline and header. |
| [RuledHorizontalTimeline](https://ddkasa.github.io/textual-timepiece/reference/timeline/#textual_timepiece.timeline.RuledHorizontalTimeline) | Ruled horizontal timeline with markers. |
| [RuledVerticalTimeline](https://ddkasa.github.io/textual-timepiece/reference/timeline/#textual_timepiece.timeline.RuledVerticalTimeline) | Ruled vertical timeline with markers. |
| [VerticalEntry](https://ddkasa.github.io/textual-timepiece/reference/timeline/#textual_timepiece.timeline.VerticalEntry) | Vertical entry for a vertical timeline layout. |
| [VerticalRuler](https://ddkasa.github.io/textual-timepiece/reference/timeline/#textual_timepiece.timeline.VerticalRuler) | Vertical ruler for marking vertical timelines. |
| [VerticalTimeline](https://ddkasa.github.io/textual-timepiece/reference/timeline/#textual_timepiece.timeline.VerticalTimeline) | Basic timeline widget that displays entries in a vertical view. |
| [VerticalTimelineNavigation](https://ddkasa.github.io/textual-timepiece/reference/timeline/#textual_timepiece.timeline.VerticalTimelineNavigation) | Vertical widget containing a vertical timeline and header. |
| Selector | Description |
| :------------------------------------------------------------------------------------------------------------------------- | :-------------------------------------------------------------------- |
| [DateSelect](https://ddkasa.github.io/textual-timepiece/reference/selectors/#textual_timepiece.pickers.DateSelect) | Date selection widget with calendar panes. |
| [TimeSelect](https://ddkasa.github.io/textual-timepiece/reference/selectors/#textual_timepiece.pickers.TimeSelect) | Time selection widget with various times in 30 minute intervals. |
| [DurationSelect](https://ddkasa.github.io/textual-timepiece/reference/selectors/#textual_timepiece.pickers.DurationSelect) | Duration selection widget with modifiers for adjust time or duration. |
| Input | Description |
| :------------------------------------------------------------------------------------------------------------------- | :------------------------------------------------------------- |
| [DateInput](https://ddkasa.github.io/textual-timepiece/reference/input/#textual_timepiece.pickers.DateInput) | Date input which takes in a iso-format date. |
| [TimeInput](https://ddkasa.github.io/textual-timepiece/reference/input/#textual_timepiece.pickers.TimeInput) | Time input that takes in 24 hour clocked in a HH:MM:SS format. |
| [DurationInput](https://ddkasa.github.io/textual-timepiece/reference/input/#textual_timepiece.pickers.DurationInput) | Duration input with a duration up to 99 hours. |
| [DateTimeInput](https://ddkasa.github.io/textual-timepiece/reference/input/#textual_timepiece.pickers.DateTimeInput) | An input with a combination of a date and time in iso-format. |
## Demo
### [UVX](https://docs.astral.sh/uv/)
```sh
uvx textual-timepiece
```
### [PIPX](https://github.com/pypa/pipx)
```sh
pipx run textual-timepiece
```
## Install
### Pip
```sh
pip install textual-timepiece
```
### [UV](https://docs.astral.sh/uv/)
```sh
uv add textual-timepiece
```
### [Poetry](https://python-poetry.org)
```sh
poetry add textual-timepiece
```
> [!NOTE]
> Requires [whenever](https://github.com/ariebovenberg/whenever) as an additional dependency.
## Quick Start
#### DatePicker
##### Code
```py
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
```py
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
```py
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](https://ddkasa.github.io/textual-timepiece/examples)
## License
MIT. Check [LICENSE](LICENSE.md) for more information.