Skip to main content

ALToolbox.business_days

holidays​

pd​

datetime​

dt​

as_datetime​

DADateTime​

Union​

Dict​

Iterable​

Mapping​

Optional​

__all__​

standard_holidays​

def standard_holidays(
        year,
        country="US",
        subdiv="MA",
        add_holidays: Optional[Mapping] = None,
        remove_holidays: Optional[Iterable[str]] = None
) -> holidays.HolidayBase

Get all holidays in the specified year, country, and state (or other subdivision). Note that this draws on the "holidays" package which may deviate slightly from holidays observed by a local court, but should be very close to accurate.

Arguments​

  • year - the year to get holidays for
  • country - the country to use holidays from (default: "US")
  • subdiv - the subdivision (e.g. state or province) to use holidays from (default: "MA")
  • add_holidays - a dictionary from date strings ("12-25") to the name of the holiday, to add custom holidays
  • remove_holidays - a list of holiday name strings to remove from the standard holidays

Returns​

A dictionary like-object that you can treat like:

{
    "2021-01-01": "New Year's Day",
    ...
    "2021-12-25": "Christmas Day",
}

In place of a string, the object that is returned can also be treated as though the keys are datetime.date objects.

Example​

Read the holiday name from the library’s Massachusetts calendar:

Input (Mako)

${ standard_holidays(2023, country="US", subdiv="MA")["2023-07-04"] }

Input (Jinja2)

{{ standard_holidays(2023, country="US", subdiv="MA")["2023-07-04"] }}

Output

Independence Day

non_business_days​

def non_business_days(year,
                      country="US",
                      subdiv="MA",
                      add_holidays: Optional[Mapping] = None,
                      remove_holidays: Optional[Iterable[str]] = None,
                      first_n_dates=0,
                      last_n_dates=0) -> dict

Get all non-business days (weekends and holidays) in the specified year, country, and state. This function returns a dictionary of all dates that are not business days, including both weekends (Saturdays and Sundays) and official holidays.

Arguments​

  • year - the year to get non-business days for
  • country - the country to use holidays from (default: "US")
  • subdiv - the subdivision (e.g. state or province) to use holidays from (default: "MA")
  • add_holidays - a dictionary from date strings ("12-25") to the name of the holiday, to add custom holidays
  • remove_holidays - a list of holiday name strings to remove from the standard holidays
  • first_n_dates - if specified, only return the first N non-business days of the year
  • last_n_dates - if specified, only return the last N non-business days of the year

Returns​

A dictionary where keys are date strings ("YYYY-MM-DD") and values are the name of the non-business day (e.g., "Saturday", "New Year's Day").

Example​

The value of closed_days contains the first two closed dates:

Input (interview YAML)

code: |
  closed_days = non_business_days(2023, country="US", subdiv="MA", first_n_dates=2)

Output

{'2023-01-01': "New Year's Day", '2023-01-02': "New Year's Day (observed)"}

is_business_day​

def is_business_day(date: Union[str, DADateTime],
                    country="US",
                    subdiv="MA",
                    add_holidays: Optional[Mapping] = None,
                    remove_holidays: Optional[Iterable[str]] = None) -> bool

Returns true if and only if the specified date is a business day (i.e., not a holiday) in the specified jurisdiction. Business days are considered to be:

  1. weekdays other than Saturday and Sunday and
  2. days that are not a federal or state-observed holiday

Arguments​

  • date - the date to check. Can be a date-formatted string (i.e. "2023-03-26", or "3-26-2023") or a DADateTime object
  • country - the country to use holidays from (default: "US")
  • subdiv - the subdivision (e.g. state or province) to use holidays from (default: "MA")
  • add_holidays - a dictionary from date strings ("12-25") to the name of the holiday, to add custom holidays
  • remove_holidays - a list of holiday name strings to remove from the standard holidays

Returns​

True if the date is a business day, False otherwise.

Example​

March 26, 2023 is a Sunday. The value of office_is_open is:

Input (interview YAML)

code: |
  office_is_open = is_business_day("2023-03-26", country="US", subdiv="MA")

Output

False

get_next_business_day​

def get_next_business_day(
        start_date: Union[str, DADateTime],
        wait_n_days=1,
        country="US",
        subdiv="MA",
        add_holidays: Optional[Mapping] = None,
        remove_holidays: Optional[Iterable[str]] = None) -> DADateTime

Returns the first day AFTER the specified start date that is not a federal or state holiday, Saturday or Sunday. Optionally, specify the parameter wait_n_days to get the first business day after at least, e.g., 10 days.

Relies on the Python holidays package, which has fairly good support for holidays around the world and in various states and provinces, but local court rules may differ. You can see what holidays are used at https://github.com/dr-prodigy/python-holidays/tree/master/holidays/countries

Arguments​

  • start_date - the date to start with. Can be a date-formatted string (i.e. "2023-03-26", or "3-26-2023") or a DADateTime object
  • wait_n_days - the number of days to find the find the date after. If 0, it returns the given date if it's a business day. (default: 1)
  • country - the country to use business days from (default: "US")
  • subdiv - the subdivision (e.g. state or province) to use business days from (default: "MA")
  • add_holidays - a dictionary from date strings ("12-25") to the name of the holiday, to add custom holidays to be considered
  • remove_holidays - a list of holiday name strings of dates that are no longer holidays

Returns​

A DADateTime object representing the next business day.

Example​

With appointment_date set to Friday, March 24, 2023, and the library’s Massachusetts holiday calendar, wait two calendar days, then advance to the next open day:

Input (Mako)

${ get_next_business_day(appointment_date, wait_n_days=2, country="US", subdiv="MA").format("yyyy-MM-dd") }

Input (Jinja2)

{{ get_next_business_day(appointment_date, wait_n_days=2, country="US", subdiv="MA").format("yyyy-MM-dd") }}

Output

2023-03-27

get_date_after_n_business_days​

def get_date_after_n_business_days(
        start_date: Union[str, DADateTime],
        wait_n_days=1,
        country="US",
        subdiv="MA",
        add_holidays: Optional[Mapping] = None,
        remove_holidays: Optional[Iterable[str]] = None) -> DADateTime

Returns a time period which contains a minimum of n business days.

Arguments​

  • start_date - the date to start with. Can be a date-formatted string (i.e. "2023-03-26", or "3-26-2023") or a DADateTime object
  • wait_n_days - the number of businesses days to wait for. For example, start_date is a Friday, and wait_n_days is 2, then the date returned will be the next Tuesday. (default: 1)
  • country - the country to use business days from (default: "US")
  • subdiv - the subdivision (e.g. state or province) to use business days from (default: "MA")
  • add_holidays - a dictionary from date strings ("12-25") to the name of the holiday, to add custom holidays to be considered
  • remove_holidays - a list of holiday name strings of dates that are no longer holidays

Returns​

A DADateTime object representing the date after exactly n business days.

Example​

With appointment_date set to Friday, March 24, 2023, and the library’s Massachusetts holiday calendar, count two business days after the starting date:

Input (Mako)

${ get_date_after_n_business_days(appointment_date, wait_n_days=2, country="US", subdiv="MA").format("yyyy-MM-dd") }

Input (Jinja2)

{{ get_date_after_n_business_days(appointment_date, wait_n_days=2, country="US", subdiv="MA").format("yyyy-MM-dd") }}

Output

2023-03-28