philiprehberger-datetime-kit 0.3.0

Common datetime operations missing from the standard library.

philiprehberger-datetime-kit

Common datetime operations missing from the standard library.

Installation

pip install philiprehberger-datetime-kit

Usage

from philiprehberger_datetime_kit import business_days, date_range, is_weekend, relative

# Count business days between two dates
count = business_days("2026-03-16", "2026-03-20")  # 4

Business Days with Holidays

from philiprehberger_datetime_kit import business_days

count = business_days("2026-03-16", "2026-03-20", holidays=["2026-03-18"])  # 3

Date Range

from philiprehberger_datetime_kit import date_range

for d in date_range("2026-03-01", "2026-03-05"):
    print(d)

Relative Time

from philiprehberger_datetime_kit import relative

tomorrow = relative(days=1)
one_hour_ago = relative(hours=-1)

Weekend Check

from philiprehberger_datetime_kit import is_weekend

is_weekend(date(2026, 4, 4))  # True (Saturday)
is_weekend(date(2026, 4, 6))  # False (Monday)

Next Business Day

from philiprehberger_datetime_kit import next_business_day
from datetime import date

next_business_day(date(2026, 4, 3))  # date(2026, 4, 6) — skips weekend
next_business_day(date(2026, 4, 3), holidays=[date(2026, 4, 6)])  # date(2026, 4, 7)

Start and End of Period

from philiprehberger_datetime_kit import start_of, end_of

start = start_of("month")   # first moment of current month
end = end_of("day")         # last moment of today

Add Business Days

from philiprehberger_datetime_kit import add_business_days

result = add_business_days("2026-04-06", 5)  # skips weekends
result = add_business_days("2026-04-06", 3, holidays=["2026-04-07"])

Human-Readable Time Ago

from philiprehberger_datetime_kit import time_ago
from datetime import datetime, timezone

past = datetime(2026, 4, 6, 10, 0, 0, tzinfo=timezone.utc)
time_ago(past)  # "3 hours ago" (depends on current time)

Format Duration

from philiprehberger_datetime_kit import format_duration

format_duration(3661)   # "1h 1m 1s"
format_duration(45)     # "45s"
format_duration(0.5)    # "500ms"

API

Function / Class	Description
business_days(start, end, holidays?)	Count business days (Mon-Fri) between two dates
date_range(start, end, step?)	Yield dates from start to end inclusive
is_weekend(dt?)	Check if a date falls on a weekend
next_business_day(dt?, holidays?)	Return the next business day (Mon-Fri, excluding holidays)
relative(days?, hours?, minutes?, seconds?)	Return UTC now offset by the given delta
start_of(unit, dt?)	Start of day/week/month/year
end_of(unit, dt?)	End of day/week/month/year
add_business_days(start, days, holidays?)	Add N business days to a date, skipping weekends and holidays
time_ago(dt?, now?)	Human-readable relative time string ("3 hours ago", "just now")
format_duration(seconds)	Format seconds as compact string ("2h 30m", "45s")

Development

pip install -e .
python -m pytest tests/ -v

Support

If you find this project useful:

⭐ Star the repo

🐛 Report issues

💡 Suggest features

❤️ Sponsor development

🌐 All Open Source Projects

💻 GitHub Profile

🔗 LinkedIn Profile

License

MIT