{"id":3427,"library":"businesstimedelta","title":"Business Time Delta","description":"Timedelta for business time. This module helps calculate the exact working time between two datetimes, supporting custom schedules, holidays, and time zones. It is currently at version 1.0.1 and appears to have a low but active release cadence, with the last update in 2018.","status":"active","version":"1.0.1","language":"python","source_language":"en","source_url":"https://github.com/seppemans/businesstimedelta","tags":["datetime","business-hours","timedelta","timezone","holidays","time-calculation"],"install":[{"cmd":"pip install businesstimedelta","lang":"bash","label":"Install stable version"}],"dependencies":[{"reason":"Used for timezone-aware calculations, as demonstrated in quickstart examples.","package":"pytz","optional":true},{"reason":"Used for defining holiday rules, as demonstrated in quickstart examples.","package":"holidays","optional":true}],"imports":[{"symbol":"WorkDayRule","correct":"from businesstimedelta import WorkDayRule"},{"symbol":"LunchTimeRule","correct":"from businesstimedelta import LunchTimeRule"},{"symbol":"HolidayRule","correct":"from businesstimedelta import HolidayRule"},{"symbol":"Rules","correct":"from businesstimedelta import Rules"},{"symbol":"BusinessTimeDelta","correct":"from businesstimedelta import BusinessTimeDelta"}],"quickstart":{"code":"import datetime\nimport pytz\nimport businesstimedelta\nimport holidays as pyholidays\n\n# Define a working day (Monday-Friday, 9 AM to 6 PM)\nworkday = businesstimedelta.WorkDayRule(\n    start_time=datetime.time(9),\n    end_time=datetime.time(18),\n    working_days=[0, 1, 2, 3, 4]\n)\n\n# Define a lunch break (12 PM to 1 PM, Monday-Friday)\nlunchbreak = businesstimedelta.LunchTimeRule(\n    start_time=datetime.time(12),\n    end_time=datetime.time(13),\n    working_days=[0, 1, 2, 3, 4]\n)\n\n# Define holidays (e.g., US California holidays)\nca_holidays = pyholidays.US(state='CA')\nholidays_rule = businesstimedelta.HolidayRule(ca_holidays)\n\n# Combine the rules\nbusiness_hours_rules = businesstimedelta.Rules([workday, lunchbreak, holidays_rule])\n\n# Calculate the business time between two datetimes (aware of UTC by default if naive)\nstart_datetime = pytz.utc.localize(datetime.datetime(2026, 4, 7, 9, 0, 0)) # Monday 9 AM UTC\nend_datetime = pytz.utc.localize(datetime.datetime(2026, 4, 11, 18, 0, 0)) # Friday 6 PM UTC\n\nbdiff = business_hours_rules.difference(start_datetime, end_datetime)\n\nprint(f\"Business time difference: {bdiff}\")\nprint(f\"{bdiff.hours} hours and {bdiff.seconds} seconds\")\n\n# Business time arithmetic\n# Adding 40 business hours to start_datetime should land us at end_datetime\nfuture_datetime = start_datetime + businesstimedelta.BusinessTimeDelta(business_hours_rules, hours=40)\nprint(f\"40 business hours after start: {future_datetime}\")","lang":"python","description":"This quickstart defines typical business hours, a lunch break, and holidays, then calculates the business time difference between two `datetime` objects. It also demonstrates business time arithmetic. Note the use of `pytz.utc.localize` to ensure timezone awareness, which is critical for accurate calculations."},"warnings":[{"fix":"Always provide timezone-aware `datetime` objects to `businesstimedelta` functions, for example, by using `pytz` or `zoneinfo` (Python 3.9+).","message":"If `datetime` objects are not timezone-aware, `businesstimedelta` will localize them to UTC by default. This can lead to unexpected results if your intentions are for a different timezone or naive `datetime` behavior.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Avoid row-wise iteration with Pandas DataFrames. Consider vectorized operations if possible, or refactor to apply the function more efficiently (e.g., using `df.apply()` with appropriate optimization, though this might still be slow for very large DFs, or pre-processing data for bulk calculations).","message":"When calculating business time differences between columns in a Pandas DataFrame, iterating row-by-row using `businesstimedelta.difference()` is 'abysmally slow.' This pattern is highly inefficient for large datasets.","severity":"gotcha","affected_versions":"All versions"}],"env_vars":null,"search_vec":"'1.0.1':31 '2018':47 'activ':39 'appear':33 'busi':1,6,50 'business-hour':49 'cadenc':41 'calcul':11,57 'current':28 'custom':20 'datetim':18,48 'delta':3 'exact':13 'help':10 'holiday':22,54 'hour':51 'last':44 'low':37 'modul':9 'releas':40 'schedul':21 'support':19 'time':2,7,15,24,56 'time-calcul':55 'timedelta':4,52 'timezon':53 'two':17 'updat':45 'version':30 'work':14 'zone':25","created_at":"2026-04-11T17:28:39.122235+00:00","updated_at":"2026-04-16T01:10:15.223411+00:00","problems":[{"fix":"To resolve this, iterate through the DataFrame rows and apply `businesstimedelta` functions to individual `datetime` objects (e.g., using `df.apply()` or a loop), ensuring each datetime object is timezone-aware before processing.","cause":"This error occurs when attempting to pass a Pandas Series (e.g., a DataFrame column of datetimes) directly to `businesstimedelta` methods, which expect single `datetime` objects. Pandas Series objects do not possess the `tzinfo` attribute in the same way individual `datetime` objects do, leading to an AttributeError during timezone awareness checks.","error":"AttributeError: 'Series' object has no attribute 'tzinfo'"},{"fix":"Install the library using pip: `pip install businesstimedelta`.","cause":"This standard Python error indicates that the `businesstimedelta` library has not been installed in your current Python environment or the environment where your code is being executed.","error":"ModuleNotFoundError: No module named 'businesstimedelta'"},{"fix":"Always provide timezone-aware `datetime` objects to `businesstimedelta` functions. Use libraries like `pytz` or Python's built-in `zoneinfo` (for Python 3.9+) to create or localize datetimes with explicit timezone information, for example: `pytz.utc.localize(datetime.datetime(2023, 1, 1, 9, 0, 0))`.","cause":"`businesstimedelta` automatically localizes naive (timezone-unaware) `datetime` objects to UTC by default. This can lead to unexpected and incorrect business time calculations if your intention was for a different timezone or if you expected naive datetimes to be treated as-is without localization.","error":"businesstimedelta naive datetime UTC conversion"}],"ecosystem":"pypi","meta_description":null,"install_score":null,"quickstart_score":null,"quickstart_tag":null,"pypi_latest":"1.0.1","cli_name":"","cli_version":null,"type":"library","homepage":null,"github":"http://github.com/seppemans/businesstimedelta","docs":null,"changelog":null,"pypi":"https://pypi.org/project/businesstimedelta/","npm":null,"openapi_spec":null,"status_page":null,"smithery":null,"categories":["database"],"base_url":null,"auth_type":null,"provenance":{"verified_status":"passing","verified_at":"2026-06-28","last_verified":"2026-08-29","next_check":"2026-07-28","install_tag":null}}