Metadata-Version: 2.4
Name: minimindslab-datetime-window-truncate
Version: 0.1.0
Summary: Truncate datetimes to a fixed window size in seconds, minutes, hours, or days with optional timezone-aware handling.
Author: MiniMindsLab
License: MIT
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
Dynamic: license-file

# MiniMindsLab Datetime Window Truncate

`minimindslab-datetime-window-truncate` provides deterministic datetime bucketing with zero runtime dependencies.

## Features

- Pure Python (standard library only)
- Python 3.11+
- Truncate naive or timezone-aware `datetime` values
- Supports units: `seconds`, `minutes`, `hours`, `days`
- Deterministic validation errors for invalid input

## Installation

```bash
pip install minimindslab-datetime-window-truncate
```

## Usage

```python
from datetime import datetime, timezone
from minimindslab_datetime_window_truncate import truncate_datetime

# Naive datetime
value = datetime(2024, 1, 2, 3, 4, 5)
print(truncate_datetime(value, 15, "minutes"))
# 2024-01-02 03:00:00

# Timezone-aware datetime
aware = datetime(2024, 1, 2, 3, 4, 5, tzinfo=timezone.utc)
print(truncate_datetime(aware, 1, "hours"))
# 2024-01-02 03:00:00+00:00
```

## API

- `truncate_datetime(dt, window_size, unit)`

### Parameters

- `dt`: `datetime.datetime`
- `window_size`: positive integer
- `unit`: one of `"seconds"`, `"minutes"`, `"hours"`, `"days"`

### Returns

A new `datetime.datetime` truncated (floored) to the requested fixed window in the datetime's own timezone context.

## License

MIT
