date-difference-calculator

A lightweight Python library that calculates the absolute difference in days between two Python date objects.

Overview

date-difference-calculator is a zero-dependency Python library designed to calculate the absolute integer difference in calendar days between two standard library datetime.date instances. It guarantees non-negative output regardless of the argument order.

Requirements

• Python >= 3.12

Installation

Install using pip:

pip install date-difference-calculator

Or using uv:

uv add date-difference-calculator

Usage Example

from datetime import date
from date_difference_calculator import calculate_date_difference

start_date = date(2026, 8, 11)
end_date = date(2026, 8, 20)

# Forward-date calculation
diff = calculate_date_difference(start_date, end_date)
print(diff)  # Output: 9

# Reversed-date calculation (order does not affect output; result is non-negative)
diff_reverse = calculate_date_difference(end_date, start_date)
print(diff_reverse)  # Output: 9

# Same-date calculation
diff_same = calculate_date_difference(start_date, start_date)
print(diff_same)  # Output: 0

API Reference

calculate_date_difference(start_date, end_date)

Calculates the absolute difference in days between two datetime.date objects.

Parameters:

• start_date (datetime.date): The first date.
• end_date (datetime.date): The second date.

Returns:

• int: The non-negative number of calendar days between start_date and end_date.

Current Scope & Limitations

This initial release (v0.1.0) strictly supports calendar-day calculation for date objects:

• Type Requirement: Operates exclusively on Python datetime.date objects.
• Unit of Measurement: Calculates absolute difference in full calendar days (accounting for leap years and month/year boundaries).
• No Time or Timezone Support: Does not accept datetime.datetime objects, time components, or timezones.
• No Calendar Customization: Does not calculate business days, workdays, or holiday-adjusted schedules.

Development & Testing

To run the project test suite during development:

# Run tests using pytest
pytest

# Or run tests via uv
uv run pytest

License

Distributed under the terms of the MIT License.