calculate-time-window 0.2.0

Calcuate a dynamic time window.

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
pytho3 -m pip install calculate_time_window

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=3, end_minutes=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=3, end_minutes=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: Optional[int] = 0,
end_weeks: Optional[int] = 0,
start_days: Optional[int] = 0,
end_days: Optional[int] = 0,
start_hours: Optional[int] = 0,
end_hours: Optional[int] = 0,
start_minutes: Optional[int] = 300,
end_minutes: 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=3, end_minutes=1, start_seconds=7, end_seconds=13)
CalculateTimeWindow(expires_in=600)
#
past_time = datetime.now() - timedelta(days=1)
calc6 = CalculateTimeWindow(start_minutes=3, now=past_time)

Sample Output

produced with json.dumps(x, indent=4)

CalculateTimeWindow(start_weeks=2, start_days=1, start_hours=2, start_minutes=3, end_weeks=1, end_days=2, end_hours=3, end_minutes=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
}