Metadata-Version: 2.3
Name: date-difference-calculator
Version: 0.1.0
Summary: A lightweight Python library for calculating the difference between two dates.
Author: ssharma-03
Author-email: ssharma-03 <sharmasomyamhs@gmail.com>
Requires-Dist: pytest>=9.1.1
Requires-Python: >=3.12
Description-Content-Type: text/markdown

# 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`:

```bash
pip install date-difference-calculator
```

Or using `uv`:

```bash
uv add date-difference-calculator
```

## Usage Example

```python
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:

```bash
# Run tests using pytest
pytest

# Or run tests via uv
uv run pytest
```

## License

Distributed under the terms of the [MIT License](LICENSE).
