Calendar#

Basic usage#

Calendar widget allows you to display the keyboard in the form of a calendar, flip through the months and select the date. The initial state looks like the days of the current month. It is possible to switch to the state for choosing the month of the current year or in the state of choosing years.

from datetime import date

from aiogram.types import CallbackQuery

from aiogram_dialog import DialogManager
from aiogram_dialog.widgets.kbd import Calendar

async def on_date_selected(callback: CallbackQuery, widget,
                           manager: DialogManager, selected_date: date):
    await callback.answer(str(selected_date))

calendar = Calendar(id='calendar', on_click=on_date_selected)

Customization#

Providing calendar config during calendar initialization you can change basic params like minimal/maximal selected date or number of columns.

For deeper customization you need to inherit calendar and overload some methods. In _init_views you can create instances of built-in classes or create you own implementations. If using existing ones you can provide text widgets to customize representation of each button.

While rendering text the date field can be used to render text, and data is original data retrieved from window getter. For more details refer to source code.

Note

Though calendar supports setting timezone and first day of the week it doesn’t translate any dates. If you want localized month or week day names you should provide your own Text widget with support of that.

For example, if you want to change first day of the week to Sunday, replace days view header and show today’s button as *** the code will look like this:

from typing import Dict

from aiogram_dialog import DialogManager
from aiogram_dialog.widgets.kbd import (
    Calendar, CalendarScope, CalendarUserConfig,
)
from aiogram_dialog.widgets.kbd.calendar_kbd import (
    CalendarDaysView, CalendarMonthView, CalendarScopeView, CalendarYearsView,
)
from aiogram_dialog.widgets.text import Const, Format


class CustomCalendar(Calendar):
    def _init_views(self) -> Dict[CalendarScope, CalendarScopeView]:
        return {
            CalendarScope.DAYS: CalendarDaysView(
                self._item_callback_data, self.config,
                today_text=Format("***"),
                header_text=Format("> {date: %B %Y} <"),
            ),
            CalendarScope.MONTHS: CalendarMonthView(
                self._item_callback_data, self.config,
            ),
            CalendarScope.YEARS: CalendarYearsView(
                self._item_callback_data, self.config,
            ),
        }

    async def _get_user_config(
            self,
            data: Dict,
            manager: DialogManager,
    ) -> CalendarUserConfig:
        return CalendarUserConfig(
            firstweekday=7,
        )

Classes#

class aiogram_dialog.widgets.kbd.calendar_kbd.OnDateSelected(*args, **kwargs)#

async __call__(event, widget, dialog_manager, date)#

Call self as a function.

Parameters:

event (CallbackQuery | Message | DialogUpdateEvent | ChatMemberUpdated | ChatJoinRequest) –
widget (ManagedCalendar) –
dialog_manager (DialogManager) –
date (date) –

Return type:

Any

class aiogram_dialog.widgets.kbd.Calendar(id, on_click=None, config=None, when=None)#

Calendar widget.

Used to render keyboard for date selection.

Parameters:

id (str) –
on_click (Union[OnDateSelected, WidgetEventProcessor, None]) –
config (Optional[CalendarConfig]) –
when (WhenCondition) –

__init__(id, on_click=None, config=None, when=None)#

Init calendar widget.

Parameters:

id (str) – ID of widget
on_click (OnDateSelected | WidgetEventProcessor | None) – Function to handle date selection
config (CalendarConfig | None) – Calendar configuration
when (str | MagicFilter | Predicate | None) – Condition when to show widget

Return type:

None

async _get_user_config(data, manager)#

User related config getter.

Override this method to customize how user config is retrieved.

Parameters:

data (Dict) – data from window getter
manager (DialogManager) – dialog manager instance

Returns:

Return type:

CalendarUserConfig

_init_views()#

Calendar scopes view initializer.

Override this method customize how calendar is rendered. You can either set Text widgets for buttons in default views or create own implementation of views

Return type:: Dict[CalendarScope, CalendarScopeView]

class aiogram_dialog.widgets.kbd.ManagedCalendar(widget, manager)#

Parameters:

widget (W) –
manager (DialogManager) –

get_offset()#

Get current offset from which calendar is shown.

Return type:: date | None

get_scope()#

Get current scope showing in calendar.

Return type:: CalendarScope

set_offset(new_offset)#

Set current offset for calendar paging.

Parameters:: new_offset (date) –
Return type:: None

set_scope(new_scope)#

Set current scope showing in calendar.

Parameters:: new_scope (CalendarScope) –
Return type:: None

class aiogram_dialog.widgets.kbd.CalendarUserConfig(firstweekday: 'int' = 0, timezone: 'timezone' = datetime.timezone(datetime.timedelta(0), 'UTC'))#

Parameters:

firstweekday (int) –
timezone (timezone) –

class aiogram_dialog.widgets.kbd.CalendarConfig(min_date: 'date' = datetime.date(1900, 1, 1), max_date: 'date' = datetime.date(2100, 12, 31), month_columns: 'int' = 3, years_per_page: 'int' = 20, years_columns: 'int' = 5)#

Parameters:

min_date (date) –
max_date (date) –
month_columns (int) –
years_per_page (int) –
years_columns (int) –

class aiogram_dialog.widgets.kbd.calendar_kbd.CalendarScopeView(*args, **kwargs)#

Calendar widget part.

Used to represent keyboard for one of calendar scopes.

async render(config, offset, data, manager)#

Render keyboard for current scope.

Parameters:

config (CalendarUserConfig) – configuration related to current user
offset (date) – current offset from which we show dates
data (Dict) – data received from window getter
manager (DialogManager) – dialog manager instance

Returns:

rendered keyboard

Return type:

List[List[InlineKeyboardButton]]