Input

Note

All of the custom Input widgets have their Changed, Submitted and Blurred messages disabled by default.

Info

All inputs have an AbstractInput.action_adjust_time action which allows the user to adjust the value depending on the keyboard cursor location. This spinbox functionality can be accessed through clicking then dragging up/down, mouse wheel usage and up/down arrows.

---

textual_timepiece.pickers.DateInput

Bases: AbstractInput[Date]

Date picker for full dates.

PARAMETER	DESCRIPTION
day	Initial value to set. TYPE: Date | None DEFAULT: None
name	Name of the widget. TYPE: str | None DEFAULT: None
id	Unique dom identifier value. TYPE: str | None DEFAULT: None
classes	Any dom classes to add. TYPE: str | None DEFAULT: None
tooltip	Tooltip to show when hovering the widget. TYPE: str | None DEFAULT: 'YYYY-MM-DD Format.'
disabled	Whether to disable the widget. TYPE: bool DEFAULT: False
select_on_focus	Whether to place the cursor on focus. TYPE: bool DEFAULT: True
spinbox_sensitivity	Sensitivity setting for spinbox functionality. TYPE: int DEFAULT: 1

CLASS	DESCRIPTION
DateChanged	Message sent when the date changed.

METHOD	DESCRIPTION
action_adjust_time	Adjust date with an offset depending on the text cursor position.

ATTRIBUTE	DESCRIPTION
DEFAULT_CSS	TYPE: str
BINDINGS	All bindings for an AbstractInput. TYPE: list[BindingType]
date	Date that is set. Bound if using within a picker.

Source code in src/textual_timepiece/pickers/_date_picker.py

class DateInput(AbstractInput[Date]):
    """Date picker for full dates.

    Params:
        day: Initial value to set.
        name: Name of the widget.
        id: Unique dom identifier value.
        classes: Any dom classes to add.
        tooltip: Tooltip to show when hovering the widget.
        disabled: Whether to disable the widget.
        select_on_focus: Whether to place the cursor on focus.
        spinbox_sensitivity: Sensitivity setting for spinbox functionality.
    """

    @dataclass
    class DateChanged(BaseMessage):
        """Message sent when the date changed."""

        widget: DateInput
        date: Date | None

    PATTERN: ClassVar[str] = "0009-B9-99"
    DATE_FORMAT: ClassVar[str] = "%Y-%m-%d"
    ALIAS = "date"
    date = var[Date | None](None, init=False)
    """Date that is set. Bound if using within a picker."""

    def __init__(
        self,
        day: Date | None = None,
        name: str | None = None,
        id: str | None = None,
        classes: str | None = None,
        tooltip: str | None = "YYYY-MM-DD Format.",
        *,
        disabled: bool = False,
        select_on_focus: bool = True,
        spinbox_sensitivity: int = 1,
    ) -> None:
        super().__init__(
            value=day,
            name=name,
            id=id,
            classes=classes,
            disabled=disabled,
            tooltip=tooltip,
            select_on_focus=select_on_focus,
            spinbox_sensitivity=spinbox_sensitivity,
        )

    def watch_date(self, new: Date | None) -> None:
        # FIX: probably should prevent date changes
        with self.prevent(Input.Changed):
            self.value = (
                new.py_date().strftime(self.DATE_FORMAT) if new else ""
            )
        self.post_message(self.DateChanged(self, new))

    def _watch_value(self, value: str) -> None:
        if date := self.convert():
            self.date = date

    def action_adjust_time(self, offset: int) -> None:
        """Adjust date with an offset depending on the text cursor position."""

        try:
            if self.date is None:
                self.date = Date.today_in_system_tz()
            elif self._is_year_pos():
                self.date = self.date.add(years=offset)
            elif self._is_month_pos():
                self.date = self.date.add(months=offset)
            else:
                self.date = self.date.add(days=offset)
        except ValueError as err:
            self.log.debug(err)
            if not str(err).endswith("out of range"):
                raise

    def _is_year_pos(self) -> bool:
        return self.cursor_position < 4

    def _is_month_pos(self) -> bool:
        return 5 <= self.cursor_position < 7

    def _is_day_pos(self) -> bool:
        return 8 <= self.cursor_position

    def convert(self) -> Date | None:
        # NOTE: Pydate instead as I want to keep it open to standard formats.
        try:
            return Date.from_py_date(
                datetime.strptime(self.value, self.DATE_FORMAT).date()
            )
        except ValueError:
            return None

    def insert_text_at_cursor(self, text: str) -> None:
        if not text.isdigit():
            return

        # Extra Date Filtering
        if self.cursor_position == 6 and text not in "012":
            return

        if self.cursor_position == 5 and text not in "0123":
            return

        if (
            self.cursor_position == 6
            and self.value[5] == "3"
            and text not in "01"
        ):
            return

        super().insert_text_at_cursor(text)

DEFAULT_CSS class-attribute

AbstractInput {
    background: transparent;
    width: auto;
    border: none;
}

BINDINGS class-attribute

BINDINGS: list[BindingType] = [
    Binding("escape", "leave", "Defocus", tooltip="Defocus the input."),
    Binding(
        "up",
        "adjust_time(1)",
        "Increment",
        tooltip="Increment value depending on keyboard cursor location.",
        priority=True,
    ),
    Binding(
        "down",
        "adjust_time(-1)",
        "Decrement",
        tooltip="Decrement value depending on keyboard cursor location.",
        priority=True,
    ),
]

All bindings for an AbstractInput.

Key(s)	Description
escape	Defocus the input.
up	Increment value depending on keyboard cursor location.
down	Decrement value depending on keyboard cursor location.

date class-attribute instance-attribute

date = var[Date | None](None, init=False)

Date that is set. Bound if using within a picker.

DateChanged dataclass

Bases: BaseMessage

Message sent when the date changed.

Source code in src/textual_timepiece/pickers/_date_picker.py

@dataclass
class DateChanged(BaseMessage):
    """Message sent when the date changed."""

    widget: DateInput
    date: Date | None

action_adjust_time

action_adjust_time(offset: int) -> None

Adjust date with an offset depending on the text cursor position.

Source code in src/textual_timepiece/pickers/_date_picker.py

def action_adjust_time(self, offset: int) -> None:
    """Adjust date with an offset depending on the text cursor position."""

    try:
        if self.date is None:
            self.date = Date.today_in_system_tz()
        elif self._is_year_pos():
            self.date = self.date.add(years=offset)
        elif self._is_month_pos():
            self.date = self.date.add(months=offset)
        else:
            self.date = self.date.add(days=offset)
    except ValueError as err:
        self.log.debug(err)
        if not str(err).endswith("out of range"):
            raise

---

textual_timepiece.pickers.TimeInput

Bases: AbstractInput[Time]

Time input for a HH:MM:SS format

CLASS	DESCRIPTION
TimeChanged	Message sent when the time is updated.

METHOD	DESCRIPTION
action_adjust_time	Adjust time with an offset depending on the text cursor position.

ATTRIBUTE	DESCRIPTION
DEFAULT_CSS	TYPE: str
BINDINGS	All bindings for an AbstractInput. TYPE: list[BindingType]
time	Currently set time or none if its empty.

Source code in src/textual_timepiece/pickers/_time_picker.py

class TimeInput(AbstractInput[Time]):
    """Time input for a HH:MM:SS format"""

    @dataclass
    class TimeChanged(BaseMessage):
        """Message sent when the time is updated."""

        widget: TimeInput
        new_time: Time | None

    PATTERN = "00:00:00"
    ALIAS = "time"

    time = var[Time | None](None, init=False)
    """Currently set time or none if its empty."""

    def _watch_time(self, time: Time | None) -> None:
        with self.prevent(Input.Changed), suppress(ValueError):
            if time:
                self.value = time.format_common_iso()
            else:
                self.value = ""

        self.post_message(self.TimeChanged(self, self.time))

    def _watch_value(self, value: str) -> None:
        if (ts := self.convert()) is not None and ts != self.time:
            self.time = ts
        super()._watch_value(value)

    def convert(self) -> Time | None:
        try:
            return Time.parse_common_iso(self.value)
        except ValueError:
            return None

    def insert_text_at_cursor(self, text: str) -> None:
        if self.cursor_position > 7:
            return

        if text not in digits:
            self.cursor_position += 1
            return

        if self.cursor_position == 0:
            self.value = text + self.value[1:]
        elif self.cursor_position == 7:
            self.value = self.value[:-1] + text
            return
        elif self.cursor_position in {4, 1} or (
            self.value[self.cursor_position] != ":" and text in "543210"
        ):
            self.value = (
                self.value[: self.cursor_position]
                + text
                + self.value[self.cursor_position + 1 :]
            )

        self.cursor_position += 1

    def action_delete_right(self) -> None:
        return

    def action_delete_left(self) -> None:
        if self.cursor_position < 0:
            return

        elif self.cursor_position == 8:
            self.value = self.value[:-1] + "0"

        elif self.cursor_position not in {2, 5}:
            self.value = (
                self.value[: self.cursor_position]
                + "0"
                + self.value[self.cursor_position + 1 :]
            )

        if self.cursor_position > 0:
            self.cursor_position -= 1

    def action_adjust_time(self, offset: int) -> None:
        """Adjust time with an offset depending on the text cursor position."""
        if 0 <= self.cursor_position < 2:
            self.time = add_time(self.time or Time(), hours(offset))
        elif 3 <= self.cursor_position < 5:
            self.time = add_time(self.time or Time(), minutes(offset))
        elif 6 <= self.cursor_position:
            self.time = add_time(self.time or Time(), seconds(offset))

DEFAULT_CSS class-attribute

AbstractInput {
    background: transparent;
    width: auto;
    border: none;
}

BINDINGS class-attribute

BINDINGS: list[BindingType] = [
    Binding("escape", "leave", "Defocus", tooltip="Defocus the input."),
    Binding(
        "up",
        "adjust_time(1)",
        "Increment",
        tooltip="Increment value depending on keyboard cursor location.",
        priority=True,
    ),
    Binding(
        "down",
        "adjust_time(-1)",
        "Decrement",
        tooltip="Decrement value depending on keyboard cursor location.",
        priority=True,
    ),
]

All bindings for an AbstractInput.

Key(s)	Description
escape	Defocus the input.
up	Increment value depending on keyboard cursor location.
down	Decrement value depending on keyboard cursor location.

time class-attribute instance-attribute

time = var[Time | None](None, init=False)

Currently set time or none if its empty.

TimeChanged dataclass

Bases: BaseMessage

Message sent when the time is updated.

Source code in src/textual_timepiece/pickers/_time_picker.py

@dataclass
class TimeChanged(BaseMessage):
    """Message sent when the time is updated."""

    widget: TimeInput
    new_time: Time | None

action_adjust_time

action_adjust_time(offset: int) -> None

Adjust time with an offset depending on the text cursor position.

Source code in src/textual_timepiece/pickers/_time_picker.py

def action_adjust_time(self, offset: int) -> None:
    """Adjust time with an offset depending on the text cursor position."""
    if 0 <= self.cursor_position < 2:
        self.time = add_time(self.time or Time(), hours(offset))
    elif 3 <= self.cursor_position < 5:
        self.time = add_time(self.time or Time(), minutes(offset))
    elif 6 <= self.cursor_position:
        self.time = add_time(self.time or Time(), seconds(offset))

---

textual_timepiece.pickers.DurationInput

Bases: AbstractInput[TimeDelta]

Duration input for time deltas.

CLASS	DESCRIPTION
DurationChanged	Message sent when the duration changes through input or spinbox.

METHOD	DESCRIPTION
action_adjust_time	Adjust time with an offset depending on the text cursor position.

ATTRIBUTE	DESCRIPTION
DEFAULT_CSS	TYPE: str
BINDINGS	All bindings for an AbstractInput. TYPE: list[BindingType]
duration	Current duration in a TimeDelta or None if empty.

Source code in src/textual_timepiece/pickers/_time_picker.py

class DurationInput(AbstractInput[TimeDelta]):
    """Duration input for time deltas."""

    @dataclass
    class DurationChanged(BaseMessage):
        """Message sent when the duration changes through input or spinbox."""

        widget: DurationInput
        duration: TimeDelta | None

    ALIAS = "duration"
    MIN: Final[TimeDelta] = TimeDelta()
    MAX: Final[TimeDelta] = TimeDelta(hours=99, minutes=59, seconds=59)

    PATTERN = "99:99:99"

    duration = var[TimeDelta | None](None, init=False)
    """Current duration in a `TimeDelta` or None if empty.

    This value is capped at 99 hours, 59 minutes and 59 seconds.
    """

    def _validate_duration(
        self,
        duration: TimeDelta | None,
    ) -> TimeDelta | None:
        if duration is None:
            return None

        return max(self.MIN, min(self.MAX, duration))

    def _watch_duration(self, duration: TimeDelta | None) -> None:
        with self.prevent(Input.Changed), suppress(ValueError):
            if isinstance(duration, TimeDelta):
                self.value = format_seconds(int(duration.in_seconds()))
            else:
                self.value = ""

        self.post_message(self.DurationChanged(self, self.duration))

    def _watch_value(self, value: str) -> None:
        if dur := self.convert():
            self.duration = dur
        super()._watch_value(value)

    def convert(self) -> TimeDelta | None:
        try:
            hours, minutes, seconds = tuple(map(int, self.value.split(":")))
        except ValueError:
            return None
        if hours + minutes + seconds == 0:
            return TimeDelta()
        return TimeDelta(seconds=seconds, minutes=minutes, hours=hours)

    def action_adjust_time(self, offset: int) -> None:
        """Adjust time with an offset depending on the text cursor position."""
        if self.duration is None:
            self.duration = TimeDelta()
        elif 0 <= self.cursor_position < 2:
            self.duration += hours(offset)
        elif 3 <= self.cursor_position < 5:
            self.duration += minutes(offset)
        elif 6 <= self.cursor_position:
            self.duration += seconds(offset)

DEFAULT_CSS class-attribute

AbstractInput {
    background: transparent;
    width: auto;
    border: none;
}

BINDINGS class-attribute

BINDINGS: list[BindingType] = [
    Binding("escape", "leave", "Defocus", tooltip="Defocus the input."),
    Binding(
        "up",
        "adjust_time(1)",
        "Increment",
        tooltip="Increment value depending on keyboard cursor location.",
        priority=True,
    ),
    Binding(
        "down",
        "adjust_time(-1)",
        "Decrement",
        tooltip="Decrement value depending on keyboard cursor location.",
        priority=True,
    ),
]

All bindings for an AbstractInput.

Key(s)	Description
escape	Defocus the input.
up	Increment value depending on keyboard cursor location.
down	Decrement value depending on keyboard cursor location.

duration class-attribute instance-attribute

duration = var[TimeDelta | None](None, init=False)

Current duration in a TimeDelta or None if empty.

This value is capped at 99 hours, 59 minutes and 59 seconds.

DurationChanged dataclass

Bases: BaseMessage

Message sent when the duration changes through input or spinbox.

Source code in src/textual_timepiece/pickers/_time_picker.py

@dataclass
class DurationChanged(BaseMessage):
    """Message sent when the duration changes through input or spinbox."""

    widget: DurationInput
    duration: TimeDelta | None

action_adjust_time

action_adjust_time(offset: int) -> None

Adjust time with an offset depending on the text cursor position.

Source code in src/textual_timepiece/pickers/_time_picker.py

def action_adjust_time(self, offset: int) -> None:
    """Adjust time with an offset depending on the text cursor position."""
    if self.duration is None:
        self.duration = TimeDelta()
    elif 0 <= self.cursor_position < 2:
        self.duration += hours(offset)
    elif 3 <= self.cursor_position < 5:
        self.duration += minutes(offset)
    elif 6 <= self.cursor_position:
        self.duration += seconds(offset)

---

textual_timepiece.pickers.DateTimeInput

Bases: AbstractInput[LocalDateTime]

Input that combines both date and time into one.

CLASS	DESCRIPTION
DateTimeChanged	Sent when the datetime is changed.

METHOD	DESCRIPTION
action_adjust_time	Adjust date with an offset depending on the text cursor position.

ATTRIBUTE	DESCRIPTION
DEFAULT_CSS	TYPE: str
BINDINGS	All bindings for an AbstractInput. TYPE: list[BindingType]
datetime	Current datetime or none if nothing is set.

Source code in src/textual_timepiece/pickers/_datetime_picker.py

class DateTimeInput(AbstractInput[LocalDateTime]):
    """Input that combines both date and time into one."""

    @dataclass
    class DateTimeChanged(BaseMessage):
        """Sent when the datetime is changed."""

        widget: DateTimeInput
        datetime: LocalDateTime | None

    PATTERN: ClassVar[str] = r"0009-B9-99 99:99:99"
    FORMAT: ClassVar[str] = r"%Y-%m-%d %H:%M:%S"
    ALIAS = "datetime"

    datetime = var[LocalDateTime | None](None, init=False)
    """Current datetime or none if nothing is set."""

    def __init__(
        self,
        value: LocalDateTime | None = None,
        name: str | None = None,
        id: str | None = None,
        classes: str | None = None,
        tooltip: str | None = None,
        *,
        disabled: bool = False,
        select_on_focus: bool = True,
        spinbox_sensitivity: int = 1,
    ) -> None:
        super().__init__(
            value=value,
            name=name,
            id=id,
            classes=classes,
            tooltip=tooltip,
            disabled=disabled,
            select_on_focus=select_on_focus,
            spinbox_sensitivity=spinbox_sensitivity,
        )

    def watch_datetime(self, value: LocalDateTime | None) -> None:
        with self.prevent(Input.Changed):
            if value:
                self.value = value.py_datetime().strftime(self.FORMAT)
            else:
                self.value = ""

        self.post_message(self.DateTimeChanged(self, self.datetime))

    def _watch_value(self, value: str) -> None:
        if (dt := self.convert()) is not None:
            self.datetime = dt

    def convert(self) -> LocalDateTime | None:
        try:
            return LocalDateTime.strptime(self.value, self.FORMAT)
        except ValueError:
            return None

    def action_adjust_time(self, offset: int) -> None:
        """Adjust date with an offset depending on the text cursor position."""

        try:
            if self.datetime is None:
                self.datetime = SystemDateTime.now().local()
            elif self.cursor_position < 4:
                self.datetime = self.datetime.add(
                    years=offset,
                    ignore_dst=True,
                )
            elif 5 <= self.cursor_position < 7:
                self.datetime = self.datetime.add(
                    months=offset,
                    ignore_dst=True,
                )
            elif 8 <= self.cursor_position < 10:
                self.datetime = self.datetime.add(
                    days=offset,
                    ignore_dst=True,
                )
            elif 11 <= self.cursor_position < 13:
                self.datetime = self.datetime.add(
                    hours=offset,
                    ignore_dst=True,
                )
            elif 14 <= self.cursor_position < 16:
                self.datetime = self.datetime.add(
                    minutes=offset,
                    ignore_dst=True,
                )
            else:
                self.datetime = self.datetime.add(
                    seconds=offset,
                    ignore_dst=True,
                )
        except ValueError as err:
            self.log.debug(err)
            if not str(err).endswith("out of range"):
                raise

    def insert_text_at_cursor(self, text: str) -> None:
        if not text.isdigit():
            return

        # Extra Date Filtering
        if self.cursor_position == 6 and text not in "012":
            return

        if self.cursor_position == 5 and text not in "0123":
            return

        if (
            self.cursor_position == 6
            and self.value[5] == "3"
            and text not in "01"
        ):
            return

        # Extra Time Filtering
        if self.cursor_position == 11:
            if (
                text == "2"
                and len(self.value) >= 12
                and self.value[12] not in "0123"
            ):
                self.value = self.value[:12] + "3" + self.value[13:]
            elif text not in "012":
                return

        if (
            self.cursor_position == 12
            and self.value[11] == "2"
            and text not in "0123"
        ):
            return

        if self.cursor_position in {14, 17} and text not in "012345":
            return

        super().insert_text_at_cursor(text)

DEFAULT_CSS class-attribute

AbstractInput {
    background: transparent;
    width: auto;
    border: none;
}

BINDINGS class-attribute

BINDINGS: list[BindingType] = [
    Binding("escape", "leave", "Defocus", tooltip="Defocus the input."),
    Binding(
        "up",
        "adjust_time(1)",
        "Increment",
        tooltip="Increment value depending on keyboard cursor location.",
        priority=True,
    ),
    Binding(
        "down",
        "adjust_time(-1)",
        "Decrement",
        tooltip="Decrement value depending on keyboard cursor location.",
        priority=True,
    ),
]

All bindings for an AbstractInput.

Key(s)	Description
escape	Defocus the input.
up	Increment value depending on keyboard cursor location.
down	Decrement value depending on keyboard cursor location.

datetime class-attribute instance-attribute

datetime = var[LocalDateTime | None](None, init=False)

Current datetime or none if nothing is set.

DateTimeChanged dataclass

Bases: BaseMessage

Sent when the datetime is changed.

Source code in src/textual_timepiece/pickers/_datetime_picker.py

@dataclass
class DateTimeChanged(BaseMessage):
    """Sent when the datetime is changed."""

    widget: DateTimeInput
    datetime: LocalDateTime | None

action_adjust_time

action_adjust_time(offset: int) -> None

Adjust date with an offset depending on the text cursor position.

Source code in src/textual_timepiece/pickers/_datetime_picker.py

def action_adjust_time(self, offset: int) -> None:
    """Adjust date with an offset depending on the text cursor position."""

    try:
        if self.datetime is None:
            self.datetime = SystemDateTime.now().local()
        elif self.cursor_position < 4:
            self.datetime = self.datetime.add(
                years=offset,
                ignore_dst=True,
            )
        elif 5 <= self.cursor_position < 7:
            self.datetime = self.datetime.add(
                months=offset,
                ignore_dst=True,
            )
        elif 8 <= self.cursor_position < 10:
            self.datetime = self.datetime.add(
                days=offset,
                ignore_dst=True,
            )
        elif 11 <= self.cursor_position < 13:
            self.datetime = self.datetime.add(
                hours=offset,
                ignore_dst=True,
            )
        elif 14 <= self.cursor_position < 16:
            self.datetime = self.datetime.add(
                minutes=offset,
                ignore_dst=True,
            )
        else:
            self.datetime = self.datetime.add(
                seconds=offset,
                ignore_dst=True,
            )
    except ValueError as err:
        self.log.debug(err)
        if not str(err).endswith("out of range"):
            raise