Business Time Delta

1.0.1 · active · verified Sat Apr 11

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.

Warnings

gotcha 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.
Fix: Always provide timezone-aware `datetime` objects to `businesstimedelta` functions, for example, by using `pytz` or `zoneinfo` (Python 3.9+).
gotcha 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.
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).

Install

pip install businesstimedelta Install stable version

Imports

WorkDayRule

from businesstimedelta import WorkDayRule

LunchTimeRule

from businesstimedelta import LunchTimeRule

HolidayRule

from businesstimedelta import HolidayRule

Rules
```
from businesstimedelta import Rules
```

BusinessTimeDelta

from businesstimedelta import BusinessTimeDelta

Quickstart

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.

import datetime
import pytz
import businesstimedelta
import holidays as pyholidays

# Define a working day (Monday-Friday, 9 AM to 6 PM)
workday = businesstimedelta.WorkDayRule(
    start_time=datetime.time(9),
    end_time=datetime.time(18),
    working_days=[0, 1, 2, 3, 4]
)

# Define a lunch break (12 PM to 1 PM, Monday-Friday)
lunchbreak = businesstimedelta.LunchTimeRule(
    start_time=datetime.time(12),
    end_time=datetime.time(13),
    working_days=[0, 1, 2, 3, 4]
)

# Define holidays (e.g., US California holidays)
ca_holidays = pyholidays.US(state='CA')
holidays_rule = businesstimedelta.HolidayRule(ca_holidays)

# Combine the rules
business_hours_rules = businesstimedelta.Rules([workday, lunchbreak, holidays_rule])

# Calculate the business time between two datetimes (aware of UTC by default if naive)
start_datetime = pytz.utc.localize(datetime.datetime(2026, 4, 7, 9, 0, 0)) # Monday 9 AM UTC
end_datetime = pytz.utc.localize(datetime.datetime(2026, 4, 11, 18, 0, 0)) # Friday 6 PM UTC

bdiff = business_hours_rules.difference(start_datetime, end_datetime)

print(f"Business time difference: {bdiff}")
print(f"{bdiff.hours} hours and {bdiff.seconds} seconds")

# Business time arithmetic
# Adding 40 business hours to start_datetime should land us at end_datetime
future_datetime = start_datetime + businesstimedelta.BusinessTimeDelta(business_hours_rules, hours=40)
print(f"40 business hours after start: {future_datetime}")

view raw JSON →