{"id":8884,"library":"business-duration","title":"Python Business Duration Calculator","description":"The `business-duration` library calculates the duration between two dates and times, excluding weekends, public holidays, and non-business hours. It provides a single function, `businessDuration`, that can compute results in days, hours, minutes, or seconds. The project is actively maintained with irregular releases, with the latest version (0.68) released in October 2025.","status":"active","version":"0.68","language":"en","source_language":"en","source_url":"https://github.com/gnaneshwar441/Business_Duration","tags":["business hours","duration","time calculation","holidays","weekends","datetime","scheduling"],"install":[{"cmd":"pip install business-duration","lang":"bash","label":"Install stable version"}],"dependencies":[{"reason":"Used in examples for datetime handling (e.g., `pd.to_datetime`).","package":"pandas","optional":true},{"reason":"Used in examples to provide a list of public holidays for exclusion.","package":"holidays","optional":true}],"imports":[{"symbol":"businessDuration","correct":"from business_duration import businessDuration"}],"quickstart":{"code":"from business_duration import businessDuration\nimport pandas as pd\nimport holidays as pyholidays\nfrom datetime import time\n\n# Start date must be in standard python datetime format\nstart_date = pd.to_datetime('2017-07-01 02:02:00')\n# End date must be in standard python datetime format\nend_date = pd.to_datetime('2017-07-07 04:48:00')\n\n# Business open hour must be in standard python time format (Hour, Min, Sec)\nbiz_open_time = time(7, 0, 0)\n# Business close hour must be in standard python time format (Hour, Min, Sec)\nbiz_close_time = time(17, 0, 0)\n\n# US public holidays for California\nUS_holiday_list = pyholidays.US(state='CA')\n\n# Business duration can be 'day', 'hour', 'min', 'sec'\nunit_hour = 'hour'\n\n# Calculate and print the business duration\nresult = businessDuration(\n    startdate=start_date,\n    enddate=end_date,\n    starttime=biz_open_time,\n    endtime=biz_close_time,\n    holidaylist=US_holiday_list,\n    unit=unit_hour\n)\n\nprint(f\"Business duration: {result} {unit_hour}s\")\n# Expected result: 30.0 hours (July 1st, 2nd are weekends, 4th is a US public holiday. 3 business days * 10 hours/day = 30 Hours).","lang":"python","description":"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."},"warnings":[{"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)`.","message":"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`.","severity":"gotcha","affected_versions":"All versions"},{"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.","message":"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.","severity":"gotcha","affected_versions":"All versions"},{"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.","message":"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`.","severity":"gotcha","affected_versions":"All versions"}],"env_vars":null,"last_verified":"2026-04-16T00:00:00.000Z","next_check":"2026-07-15T00:00:00.000Z","problems":[{"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)`.","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.","error":"ValueError: The truth value of a Series is ambiguous. Use a.empty, a.bool(), a.item(), a.any() or a.all()."},{"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.","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.","error":"TypeError: 'str' object cannot be interpreted as an integer"},{"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')`.","cause":"The `holidaylist` parameter is provided in an unexpected format, or the dates within it do not match the `datetime.date` objects being evaluated.","error":"Incorrect holiday exclusion / holidays are not being recognized."}]}