Metadata-Version: 2.4
Name: calculate-time-window
Version: 0.2.1
Summary: Calcuate a dynamic time window.
Project-URL: Homepage, https://github.com/bonifield/calculate_time_window
Requires-Python: >=3.12
Description-Content-Type: text/markdown
License-File: LICENSE
Dynamic: license-file

# Calculate Time Window

Create a lookback window or calculate expiration from "now".

### *Is this just a wrapper around `datetime.timedelta()`?*

Yes and no. The goal is to simplify setting **start and end seconds** when creating a **dynamic range of timestamps for a lookback** without calling `datetime.timedelta()` and `datetime.replace()` multiple times in scripts. If this sounds good because you've had to do this before, great! If not, just use `datetime`.

This creates start and end timestamps in multiple formats. Provide start "minutes ago", ending "minutes ago" (0 for "now"), and seconds for each as part of the respective starting or ending minute. Providing "5 minutes ago, 5 seconds" will be 5 minutes ago, 5 seconds into that minute. You can also provide weeks, days, and hours for start and end. "Now" is calculated at instance creation, but can be passed at that time. **If you need explicit timestamps, not ones relative to "now", just use `datetime`.**

You then use the timestamp formats created as start and end arguments for your scripts and tools.

## Setup
```
uv add calculate_time_window
# or
python3 -m pip install calculate_time_window
```

## Usage
```
from calculate_time_window import CalculateTimeWindow as ctw
c = ctw(start_minutes_ago=5).calculate()
print(c)
# displays a dictionary of results
```

### Use Case 1
- you need to call an API for a range of data, but your scheduler doesn't run scripts perfectly on the minute, and you do "x minutes ago" queries
- you create `CalculateTimeWindow(start_minutes_ago=3, end_minutes_ago=1)`
- you receive a dictionary of
	- start timestamps set 3 minutes ago, 0 seconds and 0 milliseconds into that minute, in multiple formats
	- end timestamps set 1 minute ago, 59 seconds and 999 milliseconds into that minute, in multiple formats
```
"now_ms": "2026-04-02 02:06:30.244",
"start_ms": "2026-04-02 02:03:00.000",
"end_ms": "2026-04-02 02:05:59.999",
"start_tms": "2026-04-02T02:03:00.000",
--snip--
```

### Use Case 2
- same as use case #1, but for some reason you need 13 seconds of data, and want epoch timestamps
- you create `CalculateTimeWindow(start_minutes_ago=3, end_minutes_ago=1, start_seconds=7, end_seconds=13)`
- you receive a dictionary of
	- start timestamps set 3 minutes ago, 7 seconds and 0 milliseconds into that minute, in multiple formats
	- end timestamps set 1 minute ago, 13 seconds and 999 milliseconds into that minute, in multiple formats
```
--snip--
"now_tms": "2026-04-02T02:06:30.244",
"now_epoch": 1775095590.244,
--snip--
"start_tms": "2026-04-02T02:03:07.000",
"end_tms": "2026-04-02T02:05:13.999",
"start_epoch": 1775095387.0,
"end_epoch": 1775095513.999,
--snip--
```

### Use Case 3
- you receive a token response that includes a lifetime or expiration measures in seconds, and want to calculate timestamps upon reception
- you create `CalculateTimeWindow(expires_in=600, expires_only=True)`
	- note that "now" is defined at instance creation, or by providing a "now" argument using a `datetime` object
- you receive a dictionary of expiration timestamps, without `now_*`, `start_*`, and `end_*` due to setting `expires_only=True`
```
--snip--
"exp_ms": "2026-04-02 02:16:30.245",
"exp_us": "2026-04-02 02:16:30.245090",
"exp_tms": "2026-04-02T02:16:30.245",
"exp_tus": "2026-04-02T02:16:30.245090",
"exp_epoch": 1775096190.24509,
"exp_epochint": 1775096190,
"exp_epochms": 1775096190245
--snip--
```

### Response Value Meanings
- `_iso`: ISO8601 timestamp as created using `datetime.isoformat()` without further modification
- `_ms` and `_tms`: timestamp (with and without "T" separator) rounded to milliseconds (3 decimal places)
- `_us` and `_tus`: timestamp (with and without "T" separator) rounded to microseconds (6 decimal places)
- `_epoch`: epoch timestamp with microseconds (float)
- `_epochint`: epoch timestamp rounded to nearest second (int)
- `_epochms`: epoch in milliseconds (epoch * 1000)

### Instance Defaults
```
start_weeks_ago: Optional[int] = 0,
end_weeks_ago: Optional[int] = 0,
start_days_ago: Optional[int] = 0,
end_days_ago: Optional[int] = 0,
start_hours_ago: Optional[int] = 0,
end_hours_ago: Optional[int] = 0,
start_minutes_ago: Optional[int] = 0,
end_minutes_ago: Optional[int] = 0,
start_seconds: Optional[int] = 0,
end_seconds: Optional[int] = 59,
start_milliseconds: Optional[int] = 0,
end_milliseconds: Optional[int] = 999,
start_microseconds: Optional[int] = 0,
end_microseconds: Optional[int] = 999999,
expires_in: Optional[int] = 0,
expires_only: Optional[bool] = False,
now: Optional[datetime] = None
```

### Usage Examples
```
CalculateTimeWindow()
CalculateTimeWindow(start_minutes_ago=3, end_minutes_ago=1, start_seconds=7, end_seconds=13)
CalculateTimeWindow(expires_in=600)
#
past_time = datetime.now() - timedelta(days=1)
calc6 = CalculateTimeWindow(start_minutes_ago=3, now=past_time)
```
		
### Sample Output
produced with `json.dumps(x, indent=4)`

`CalculateTimeWindow(start_weeks_ago=2, start_days_ago=1, start_hours_ago=2, start_minutes_ago=3, end_weeks_ago=1, end_days_ago=2, end_hours_ago=3, end_minutes_ago=1, start_seconds=7, end_seconds=13).calculate()`
```
{
    "now_iso": "2026-04-02T02:06:30.244957+00:00",
    "now_ms": "2026-04-02 02:06:30.244",
    "now_us": "2026-04-02 02:06:30.244957",
    "now_tms": "2026-04-02T02:06:30.244",
    "now_tus": "2026-04-02T02:06:30.244957",
    "now_epoch": 1775095590.244957,
    "now_epochint": 1775095590,
    "now_epochms": 1775095590244,
    "start_iso": "2026-03-18T00:03:07+00:00",
    "end_iso": "2026-03-23T23:05:13.999999+00:00",
    "start_ms": "2026-03-18 00:03:07.000",
    "end_ms": "2026-03-23 23:05:13.999",
    "start_us": "2026-03-18 00:03:07.000000",
    "end_us": "2026-03-23 23:05:13.999999",
    "start_tms": "2026-03-18T00:03:07.000",
    "end_tms": "2026-03-23T23:05:13.999",
    "start_tus": "2026-03-18T00:03:07.000000",
    "end_tus": "2026-03-23T23:05:13.999999",
    "start_epoch": 1773792187.0,
    "end_epoch": 1774307113.999999,
    "start_epochint": 1773792187,
    "end_epochint": 1774307113,
    "start_epochms": 1773792187000,
    "end_epochms": 1774307113999
}
```

`CalculateTimeWindow(expires_in=600, expires_only=True).calculate()`
```
{
    "exp_iso": "2026-04-02T02:16:30.245262+00:00",
    "exp_ms": "2026-04-02 02:16:30.245",
    "exp_us": "2026-04-02 02:16:30.245262",
    "exp_tms": "2026-04-02T02:16:30.245",
    "exp_tus": "2026-04-02T02:16:30.245262",
    "exp_epoch": 1775096190.245262,
    "exp_epochint": 1775096190,
    "exp_epochms": 1775096190245
}
```
