Python Business Duration Calculator

Common errors

• ValueError: The truth value of a Series is ambiguous. Use a.empty, a.bool(), a.item(), a.any() or a.all().

  cause Attempting to pass a pandas Series (e.g., a DataFrame column) directly to `startdate`, `enddate`, or other parameters of `businessDuration` that expect single scalar values.
  fix Apply the `businessDuration` function row-wise or in a loop. For example, `df.apply(lambda row: businessDuration(startdate=row['start_col'], enddate=row['end_col'], ...), axis=1)`.

• TypeError: 'str' object cannot be interpreted as an integer

  cause Passing a string to a parameter that expects an integer or a `datetime.time` object, often related to `starttime` or `endtime` if not correctly constructed.
  fix Ensure `starttime` and `endtime` are `datetime.time` objects (e.g., `time(9, 0, 0)` for 9:00 AM) and `startdate`/`enddate` are `datetime.datetime` or `datetime.date` objects.

• Incorrect holiday exclusion / holidays are not being recognized.

  cause The `holidaylist` parameter is provided in an unexpected format, or the dates within it do not match the `datetime.date` objects being evaluated.
  fix Verify that your `holidaylist` contains `datetime.date` objects. If using the `holidays` library, ensure it's imported as `pyholidays` and correctly initialized, e.g., `US_holiday_list = pyholidays.US(state='CA')`.

Warnings

• gotcha The `businessDuration` function expects `datetime.datetime` or `datetime.date` objects for `startdate` and `enddate`, and `datetime.time` objects for `starttime` and `endtime`. Passing pandas Series directly to these parameters will result in a `ValueError`.
  Fix: Iterate over the DataFrame or apply the function row-wise, ensuring individual datetime objects are passed for each calculation. Convert Series elements using `.dt.to_pydatetime()` or `pd.to_datetime(series_element)`.
• gotcha Holiday lists must be compatible with the format expected by the `holidaylist` parameter. The recommended way is to use the `holidays` library (e.g., `holidays.US()`), which provides a dictionary-like object of dates. Simply passing a list of strings or improperly formatted date objects may lead to holidays not being excluded.
  Fix: Ensure `holidaylist` is an iterable of `datetime.date` objects or an object from the `holidays` library, as shown in the quickstart. For custom holidays, create a list of `datetime.date` objects.
• gotcha The library primarily handles duration based on provided local dates/times and does not inherently manage timezones or Daylight Saving Time (DST) transitions. If timezone-aware calculations are critical, ensure your input `datetime` objects are timezone-aware and handle any DST implications externally before passing to `businessDuration`.
  Fix: Convert `datetime` objects to a consistent timezone (e.g., UTC) or apply timezone-aware adjustments before calling `businessDuration` if DST or differing timezones are a concern.

Install

• pip install business-duration Install stable version

Imports

• businessDuration

  from business_duration import businessDuration

Quickstart

This example calculates the business duration in hours between two specific dates, excluding weekends and US public holidays in California, and considering a defined daily business hour range.

from business_duration import businessDuration
import pandas as pd
import holidays as pyholidays
from datetime import time

# Start date must be in standard python datetime format
start_date = pd.to_datetime('2017-07-01 02:02:00')
# End date must be in standard python datetime format
end_date = pd.to_datetime('2017-07-07 04:48:00')

# Business open hour must be in standard python time format (Hour, Min, Sec)
biz_open_time = time(7, 0, 0)
# Business close hour must be in standard python time format (Hour, Min, Sec)
biz_close_time = time(17, 0, 0)

# US public holidays for California
US_holiday_list = pyholidays.US(state='CA')

# Business duration can be 'day', 'hour', 'min', 'sec'
unit_hour = 'hour'

# Calculate and print the business duration
result = businessDuration(
    startdate=start_date,
    enddate=end_date,
    starttime=biz_open_time,
    endtime=biz_close_time,
    holidaylist=US_holiday_list,
    unit=unit_hour
)

print(f"Business duration: {result} {unit_hour}s")
# Expected result: 30.0 hours (July 1st, 2nd are weekends, 4th is a US public holiday. 3 business days * 10 hours/day = 30 Hours).