Python API

Calendar

class RPA.Calendar.Calendar

Library for handling different operations for date and time handling especially in business days and holiday contexts.

Utilizing pendulum and holidays packages.

Library is by default using days from Monday to Friday as business days, but that can be changed by giving list of weekdays to Set Business Days keyword. A weekday is given as a integer, the 0 for Sunday and 6 for Saturday.

Common country holidays are respected when getting next and previous business days, but custom holidays can be added into consideration using keyword Add Custom Holidays keyword.

Some dates containing for example month names are in English (en), but the locale of the library can be changed with keyword Set Locale or for specific keyword if that has a locale parameter.

ROBOT_AUTO_KEYWORDS = False

ROBOT_LIBRARY_DOC_FORMAT = 'REST'

ROBOT_LIBRARY_SCOPE = 'GLOBAL'

add_custom_holidays(days: Union[str, date, DateTime, List[Union[str, date, DateTime]]]) → List

Add a day or list of days which are considered as holidays in addition to country specific holidays when calculating

Parameters: days – string or list of dates to consider as holidays
Returns: list of current custom holidays

Python example.

library = Calendar()
custom_holidays = library.add_custom_holidays("2023-03-08")
# custom_holidays == ["2023-03-08"]
custom_holidays = library.add_custom_holidays([
    "2023-03-09", "2023-03-10"
])
# custom_holidays == ["2023-03-08", "2023-03-09", "2023-03-10"]

Robot Framework example.

@{custom_holidays}=   Add Custom Holidays   2023-03-08
# ${custom_holidays} == ["2023-03-08"]
@{more_holidays}=   Create List   2023-03-09   2023-03-10
@{custom_holidays}=   Add Custom Holidays   ${more_holidays}
# ${custom_holidays} == ["2023-03-08", "2023-03-09", "2023-03-10"]

compare_times(time1: Union[str, date, DateTime], time2: Union[str, date, DateTime])

Compares given times and returns True if time2 is more recent than time1.

Parameters

time1 – first time for comparison
time2 – second time for comparison

Returns

True if time2 is more recent than time1

Python example.

recent = Calendar().compare_times("2023-03-09 13:02", "2023-03-09 13:47")
if recent:
    print("2023-03-09 13:47 is more recent")

Robot Framework example.

${recent}=  Compare Times   2023-03-09 13:02   2023-03-09 13:47
IF  ${recent}
    Log  2023-03-09 13:47 is more recent
END

create_time(date_string: str, date_format_in: Optional[str] = None, timezone: Optional[str] = None, date_format_out: Optional[str] = None) → Union[DateTime, str]

This keyword tries to construct valid calendar instance from given date string and its expected date format.

See https://pendulum.eustace.io/docs/#tokens for valid tokens for the date format. Tokens are used to form correct date and time format.

Parameters

date_string – for example. “22 May 19”
date_format_in – for example. “DD MMM YY”
timezone – default timezone is “UTC”
date_format_out – for example. “DD-MM-YY”

Returns

set datetime as an object or string if date_format_out has been set

Python example.

date = Calendar().create_time(
    "22 May 19",
    "DD MMM YY"
)

Robot Framework example.

${date}=  Create Time
...  22 May 19
...  DD MMM YY

first_business_day_of_the_month(date: Union[str, date, DateTime], country: Optional[str] = None)

Return first business day of the month.

If country is not given then holidays are not considered.

Parameters

date – date describing the month
country – country code, default None

Returns

first business of the month

Python example.

first_day = Calendar().first_business_day_of_the_month("2024-06-01")
# first_day == "2024-06-03"

Robot Framework example.

${first_day}=  First Business Day of the Month  2024-06-01
# ${first_day} == "2024-06-03"

get_iso_calendar(date: Union[str, date, DateTime])

Get ISO calendar information for the given date.

Parameters: date – input date
Returns: ISO calendar object containing year, week number and weekday.

Python example.

iso_cal = Calendar().get_iso_calendar("2023-03-09")
print(iso_cal.year)
print(iso_cal.week)
print(iso_cal.weekday)

Robot Framework example.

${iso_cal}=  Get ISO Calendar  2023-03-09
${iso_year}=  Set Variable  ${iso_cal.year}
${iso_week}=  Set Variable  ${iso_cal.week}
${iso_weekday}=  Set Variable  ${iso_cal.weekday}

is_the_date_business_day(date: Union[str, date, DateTime], country: Optional[str] = None) → bool

Is the date a business day in a country.

If country is not given then holidays are not considered.

Parameters

date – input date
country – country code, default None

Returns

True if the day is a business day, False if not

Python example.

for day in range(1,32):
    date = f"2023-1-{day}"
    is_business_day = Calendar().is_the_date_business_day(date, "FI")
    if is_business_day:
        print(f'It is time for the work on {date}')
    else:
        print(f'It is time to relax on {date}')

Robot Framework example.

FOR  ${day}  IN RANGE  1  32
    ${date}=   Set Variable   2023-1-${day}
    ${is_business_day}=   Is the date business day  ${date}  FI
    IF   ${is_business_day}
        Log To Console   It is time for the work on ${date}
    ELSE
        Log To Console   It is time to relax on ${date}
    END
END

is_the_date_holiday(date: Union[str, date, DateTime], country: Optional[str] = None)

Is the date a holiday in a country. If country is not given then checks only if date is in custom holiday list.

Parameters

date_in – input date
country – country code, default None

Returns

True if the day is a holiday, False if not

Python example.

is_holiday = Calendar().is_the_date_holiday("2022-12-26", "FI")
if is_holiday:
    print('Time to relax')
else:
    print('Time for the work')

Robot Framework example.

${is_holiday}=   Is the date holiday   2022-12-26   FI
IF   ${is_holiday}
    Log  Time to relax
ELSE
    Log  Time for the work
END

last_business_day_of_the_month(date: Union[str, date, DateTime], country: Optional[str] = None)

Return last business day of the month.

If country is not given then holidays are not considered.

Parameters

date – date describing the month
country – country code, default None

Returns

last business day of the month

Python example.

last_day = Calendar().last_business_day_of_the_month("2023-12-01")
# last_day == "2023-12-29"

Robot Framework example.

${last_day}=  Last Business Day of the Month  2023-12-01
# ${last_day} == "2023-12-29"

reset_custom_holidays() → None: Reset custom holiday list into empty list.

return_holidays(years: Union[int, List[int]], country: Optional[str] = None) → Dict

Return holidays for a country. If country is not given then only custom holidays are returned.

Parameters

years – single year or list of years to list holidays for
country – country code, default None

Returns

holidays in a dictionary, the key is the date and the value is name of the holiday

Python example.

holidays = Calendar().return_holidays(2023, "FI")
for date, holiday_name in holidays.items():
    print(f"{date} is {holiday_name}")

Robot Framework example.

&{holidays}=  Return Holidays  2023  FI
FOR  ${date}  IN   @{holidays.keys()}
    Log To Console   ${date} is ${holidays}[${date}]
END

return_next_business_day(date: Union[str, date, DateTime], country: Optional[str] = None, return_format: str = 'YYYY-MM-DD', locale: Optional[str] = None)

Return the next business day.

Parameters

date – day of origin
country – country code, default None
return_format – dates can be formatted for the resulting list, defaults to “YYYY-MM-DD”
locale – name of the locale

Returns

the next business day from day of origin

Python example.

next_business = Calendar().return_next_business_day("2023-01-05", "FI")
# next_business == "2023-01-09"

Robot Framework example.

${next_business}=  Return Next Business Day  2023-01-05  FI
# ${next_business} == "2023-01-09"

return_previous_business_day(date: Union[str, date, DateTime], country: Optional[str] = None, return_format: str = 'YYYY-MM-DD', locale: Optional[str] = None)

Return the previous business day.

Parameters

date – day of origin
country – country code, default None
return_format – dates can be formatted for the resulting list, defaults to “YYYY-MM-DD”
locale – name of the locale

Returns

the previous business day from day of origin

Python example.

prev_business = Calendar().return_previous_business_day("2023-01-09", "FI")
# prev == "2023-01-05"

Robot Framework example.

${previous_business}=  Return Previous Business Day  2023-01-09  FI
# ${previous_business} == "2023-01-05"

set_business_days(days: List[int]) → List

Set weekdays which are considered as business days for calculating previous and next business day.

Parameters: days – list of integers denoting weekdays
Returns: previous list of weekdays

Python example.

# set 4 day work week
previous = Calendar().set_business_days([1,2,3,4])
# previous == [1,2,3,4,5]

Robot Framework example.

@{4days}=   Create List   1  2  3  4
@{previous}=    Set Business Days  ${days}
# ${previous} == [1,2,3,4,5]

set_locale(locale_name: str) → str

Set locale globally for the library

Parameters: locale_name – name of the locale
Returns: name of the previous locale

Python example.

library = Calendar()
library.set_locale("es")
now = library.time_now(return_format="dddd DD MMMM YYYY")
# now == "jueves 09 marzo 2023"
library.set_locale("en")
now = library.time_now(return_format="dddd DD MMMM YYYY")
# now == "Thursday 09 March 2023"

Robot Framework example.

Set Locale   es
${now}=  Time Now  return_format=dddd DD MMMM YYYY
# ${now} == "jueves 09 marzo 2023"
Set Locale   en
${now}=  Time Now  return_format=dddd DD MMMM YYYY
# ${now} == "Thursday 09 March 2023"

sort_list_of_dates(dates: List[Union[str, date, DateTime]], return_format: Optional[str] = None, reverse: bool = False) → List

Sort list of dates.

Parameters

dates – list of dates to sort
return_format – dates can be formatted for the resulting list
reverse – True return latest to oldest, defaults to False, which means order from oldest to latest

Returns

list of sorted dates

Python example.

datelist = [
    "2023-07-02 12:02:31",
    "2023-07-03 12:02:35",
    "2023-07-03 12:02:31"
]
sorted = Calendar().sort_list_of_dates(datelist)
# sorted[0] == "2023-07-03 12:02:35"
# sorted[-1] == "2023-07-02 12:02:31"
sorted = Calendar().sort_list_of_dates(datelist, reverse=True)
# sorted[0] == "2023-07-02 12:02:31"
# sorted[-1] == "2023-07-03 12:02:35"

Robot Framework example.

@{datelist}=  Create List
...   2023-07-02 12:02:31
...   2023-07-03 12:02:35
...   2023-07-03 12:02:31
${sorted}=  Sort List Of Dates   ${datelist}
# ${sorted}[0] == "2023-07-03 12:02:35"
# ${sorted}[-1] == "2023-07-02 12:02:31"
${sorted}=  Sort List Of Dates   ${datelist}  reverse=True
# ${sorted}[0] == "2023-07-02 12:02:31"
# ${sorted}[-1] == "2023-07-03 12:02:35"

time_difference(start_date: Union[str, date, DateTime], end_date: Union[str, date, DateTime], start_timezone: Optional[str] = None, end_timezone: Optional[str] = None) → Dict

Compare 2 dates and get the time difference.

Returned dictionary contains following properties:

end_date_is_later, True if end_date is more recent than start_date, otherwise False

years, time difference in years

months, time difference in months

days, time difference in days

hours, time difference in hours (in addition to the days)

minutes, time difference in minutes (in addition to the hours)

seconds, time difference in seconds (in addition to the minutes)

Parameters

start_date – starting date for the comparison
end_date – ending date for the comparison
start_timezone – timezone for the starting date, defaults to None
end_timezone – timezone for the ending date, defaults to None

Returns

dictionary containing comparison result

Python example.

diff = Calendar().time_difference(
    "1975-05-22T18:00:00",
    "1975-05-22T22:45:30"
)
# diff['end_date_is_later'] == True
# diff['days'] == 0
# diff['hours'] == 4
# diff['minutes'] == 45
# diff['seconds'] == 30

Robot Framework example.

&{diff}=    Time Difference  1975-05-22T18:00:00  1975-05-22T22:45:30
# ${diff}[end_date_is_later] == True
# ${diff}[days] == 0
# ${diff}[hours] == 4
# ${diff}[minutes] == 45
# ${diff}[seconds] == 30

time_difference_between_timezones(start_timezone: str, end_timezone: str)

Return the hour difference between timezones.

Parameters

start_timezone – first timezone
end_timezone – second timezone

Returns

hour difference between the timezones

Python example.

diff = Calendar().time_difference_between_timezones(
    "America/New_York",
    "Europe/Helsinki"
)
# diff == 7

Robot Framework example.

${diff}=  Time Difference Between Timezones
...  America/New_York
...  Europe/Helsinki
# ${diff} == 7

time_difference_in_days(start_date: Union[str, date, DateTime], end_date: Union[str, date, DateTime], start_timezone: Optional[str] = None, end_timezone: Optional[str] = None)

Return the time difference of dates in days.

Parameters

start_date – the start date
end_date – the end date
start_timezone – timezone for the start date, defaults to None
end_timezone – timezone for the end date, defaults to None

Returns

difference in days

Python example.

diff = Calendar().time_difference_in_days(
    "2023-05-21",
    "2023-05-29"
)
# diff == 8

Robot Framework example.

${diff}=  Time Difference In Days
...  2023-05-21
...  2023-05-29
# ${diff} == 8

time_difference_in_hours(start_date: Union[str, date, DateTime], end_date: Union[str, date, DateTime], start_timezone: Optional[str] = None, end_timezone: Optional[str] = None)

Return the time difference of dates in hours.

Parameters

start_date – the start date
end_date – the end date
start_timezone – timezone for the start date, defaults to None
end_timezone – timezone for the end date, defaults to None

Returns

difference in hours

Python example.

diff = Calendar().time_difference_in_hours(
    "2023-08-21T22:00:00",
    "2023-08-22T04:00:00"
)
# diff == 6

Robot Framework example.

${diff}=  Time Difference In Hours
...  2023-08-21T22:00:00
...  2023-08-22T04:00:00
# ${diff} == 6

time_difference_in_minutes(start_date: Union[str, date, DateTime], end_date: Union[str, date, DateTime], start_timezone: Optional[str] = None, end_timezone: Optional[str] = None)

Return the time difference of dates in minutes.

Parameters

start_date – the start date
end_date – the end date
start_timezone – timezone for the start date, defaults to None
end_timezone – timezone for the end date, defaults to None

Returns

difference in minutes

Python example.

diff = Calendar().time_difference_in_minutes(
    "12:30",
    "16:35"
)
# diff == 245

Robot Framework example.

${diff}=  Time Difference In Minutes
...  12:30
...  16:35
# ${diff} == 245

time_difference_in_months(start_date: Union[str, date, DateTime], end_date: Union[str, date, DateTime], start_timezone: Optional[str] = None, end_timezone: Optional[str] = None)

Return time difference of dates in months.

Parameters

start_date – the start date
end_date – the end date
start_timezone – timezone for the start date, defaults to None
end_timezone – timezone for the end date, defaults to None

Returns

difference in months

Python example.

diff = Calendar().time_difference_in_months(
    "2022-05-21T22:00:00",
    "2023-08-21T22:00:00"
)
# diff == 15

Robot Framework example.

${diff}=  Time Difference In Months
...  2022-05-21T22:00:00
...  2023-08-21T22:00:00
# ${diff} == 15

time_now(timezone: Optional[str] = None, return_format: str = 'YYYY-MM-DD') → DateTime

Return current date and time

Parameters

timezone – optional, for example. “America/Boston”
return_format – dates can be formatted for the resulting list, defaults to “YYYY-MM-DD”

Returns

current datetime as an object

Python example.

now = Calendar().time_now("Europe/Helsinki")

Robot Framework example.

${now}=  Time Now   Europe/Helsinki