Skip to content

Calendar

Bases: Frame

Inline calendar widget for selecting dates.

Supports single or range selection modes with optional disabled dates and min/max bounds. Displays one month in single mode or two months in range mode.

value property writable 

value: date | None

The currently selected date.

This property provides convenient access to get() and set().

range property writable 

range: tuple[date | None, date | None]

The selected date range as (start, end).

This property provides convenient access to get_range() and set_range().

__init__ 

__init__(
    master: Master = None,
    *,
    value: date | datetime | str | None = None,
    start_date: date | datetime | str | None = None,
    end_date: date | datetime | str | None = None,
    disabled_dates: Iterable[date | datetime | str]
    | None = None,
    selection_mode: Literal["single", "range"] = "single",
    max_date: date | datetime | str | None = None,
    min_date: date | datetime | str | None = None,
    show_outside_days: bool | None = None,
    show_week_numbers: bool = False,
    first_weekday: int | None = None,
    accent: str = None,
    bootstyle: str = None,
    padding: int
    | tuple[int, int]
    | tuple[int, int, int, int]
    | str
    | None = None,
) -> None

Initialize a Calendar widget.

Parameters:

Name Type Description Default
master Master

Parent widget. If None, uses the default root window.

 None
value date | datetime | str

Initial selected date for single selection mode.

 None
start_date date | datetime | str

Range start date. Use value instead for single selection mode.

 None
end_date date | datetime | str

Range end date. Only used when selection_mode='range'.

 None
disabled_dates Iterable

Collection of dates that cannot be selected.

 None
selection_mode str

Selection mode - 'single' for single date or 'range' for date range selection.

 'single'
max_date date | datetime | str

Maximum selectable date. Dates after this are disabled.

 None
min_date date | datetime | str

Minimum selectable date. Dates before this are disabled.

 None
show_outside_days bool

Whether to show days from adjacent months. Defaults to True for single mode, False for range mode.

 None
show_week_numbers bool

Whether to display ISO week numbers in the leftmost column.

 False
first_weekday int | None

First day of the week. 0=Monday, 6=Sunday. If None, uses the locale default.

 None
accent str

Accent token for selected dates and highlights (e.g., 'primary', 'success').

 None
bootstyle str

DEPRECATED - Use accent instead.

 None
padding int | tuple | str

Padding around the widget.

 None

get 

get() -> date | None

Return the currently selected date.

Returns:

Type Description
date | None

The selected date, or None if no date is selected.

set 

set(value: date | datetime | str | None) -> None

Set the selected date programmatically.

This method does NOT emit <<DateSelect>>. Use for programmatic updates when you don't want to trigger event handlers.

Parameters:

Name Type Description Default
value date | datetime | str | None

The date to select. Accepts date, datetime, ISO string, or None to clear selection.

 required

get_range 

get_range() -> tuple[date | None, date | None]

Return the selected date range.

Returns:

Type Description
date | None

A tuple of (start, end) dates. If only a start is selected
date | None

(range in progress), end will be None. If no selection,
tuple[date | None, date | None]

both may be None.

set_range 

set_range(
    start: date | datetime | str | None,
    end: date | datetime | str | None = None,
) -> None

Set the selected date range programmatically.

This method does NOT emit <<DateSelect>>. Use for programmatic updates when you don't want to trigger event handlers.

If both start and end are provided and end < start, they are automatically normalized (swapped) to ensure start <= end.

Parameters:

Name Type Description Default
start date | datetime | str | None

The range start date. Accepts date, datetime, ISO string.

 required
end date | datetime | str | None

The range end date. If None, sets a range-in-progress.

 None

on_date_selected 

on_date_selected(callback: Callable) -> str

Bind to <<DateSelect>>. Callback receives event.data = {'date': date, 'range': tuple[date, date | None]}.

off_date_selected 

off_date_selected(bind_id: str | None = None) -> None

Unbind from <<DateSelect>>.