RPA.Calendar

module RPA.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.

variable ROBOT_AUTO_KEYWORDS

ROBOT_AUTO_KEYWORDS = False

variable ROBOT_LIBRARY_DOC_FORMAT

ROBOT_LIBRARY_DOC_FORMAT = 'REST'

variable ROBOT_LIBRARY_SCOPE

ROBOT_LIBRARY_SCOPE = 'GLOBAL'

method add_custom_holidays

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

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.

method compare_times

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.

method create_time

create_time(date_string: str, date_format_in: Optional[str] = None, timezone: Optional[str] = None, date_format_out: Optional[str] = None)

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.

method first_business_day_of_the_month

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.

method get_iso_calendar

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.

method is_the_date_business_day

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

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.

method is_the_date_holiday

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.

method last_business_day_of_the_month

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.

method reset_custom_holidays

reset_custom_holidays()

Reset custom holiday list into empty list.

method return_holidays

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

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.

method return_next_business_day

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.

method return_previous_business_day

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.

method set_business_days

set_business_days(days: List[int])

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.

method set_locale

set_locale(locale_name: 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.

method sort_list_of_dates

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

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.

method time_difference

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

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.

method time_difference_between_timezones

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.

method time_difference_in_days

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.

method time_difference_in_hours

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.

method time_difference_in_minutes

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.

method time_difference_in_months

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.

method time_now

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

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.