Install & Compatibility
Where this runs
tested against v1.0.1 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
muslpy 3.10–3.95 runs
installs and imports cleanly · install 0.0s · import 0.012s · 32.5MB
glibcpy 3.10–3.95 runs
installs and imports cleanly · install 2.4s · import 0.010s · 33MB
31MB installed
● package 31MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
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
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}")
Errors
Common errors & fixes
AttributeError: 'Series' object has no attribute 'tzinfo'
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.
fixTo 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.
ModuleNotFoundError: No module named 'businesstimedelta'
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.
fixInstall the library using pip: `pip install businesstimedelta`.
businesstimedelta naive datetime UTC conversion
`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.
fixAlways 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))`.
Upgrade
Version history
1.0.1latest on PyPI · released Sep 7, 2019
Audit
Dependencies
pytzoptionalUsed for timezone-aware calculations, as demonstrated in quickstart examples.
holidaysoptionalUsed for defining holiday rules, as demonstrated in quickstart examples.