{"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":"en","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,"last_verified":"2026-04-11T00:00:00.000Z","next_check":"2026-07-10T00:00:00.000Z"}