durationpy

0.10 · active · verified Sat Mar 28

durationpy is a Python module designed for converting between Python's `datetime.timedelta` objects and Go's standard `time.Duration` string format. The current version, 0.10, was released on May 17, 2025, and the project demonstrates an active release cadence with several updates in recent years, indicating ongoing maintenance.

Warnings

gotcha Nanosecond precision is lost when parsing Go duration strings that include nanoseconds (e.g., '1ns') because Python's `datetime.timedelta` object natively supports only microsecond resolution.
Fix: Be aware of this inherent limitation. If nanosecond precision is critical, consider handling time durations as raw integer nanoseconds or using a different time library if available that supports higher precision.
gotcha The `durationpy` library is specifically designed to parse Go's `time.Duration` string format (e.g., '1h30m15s'). It will not correctly parse arbitrary human-readable duration strings (e.g., '1 hour and 30 minutes', '2 days, 4 hours'). Incorrect formats will likely raise `ValueError` or return unexpected results.
Fix: Ensure all input duration strings strictly adhere to Go's specified `time.Duration` format. Pre-validate or sanitize user-provided duration strings before passing them to `durationpy.from_str`.

Install

pip install durationpy Install with pip

Imports

from_str
```
from durationpy import from_str
```
to_str
```
from durationpy import to_str
```

Quickstart

This quickstart demonstrates how to use `durationpy.from_str` to parse a Go duration string into a `datetime.timedelta` object and `durationpy.to_str` to convert a `datetime.timedelta` back into a Go duration string. It also highlights the inherent precision limitation due to `datetime.timedelta`'s microsecond resolution.

import durationpy
import datetime

# Parse a Go duration string into a datetime.timedelta object
td = durationpy.from_str("4h3m2s1ms")
print(f"Parsed timedelta: {td}")
print(f"Total seconds: {td.total_seconds()}")

# Convert a datetime.timedelta object back to a Go duration string
duration_str = durationpy.to_str(datetime.timedelta(hours=1, minutes=30, seconds=15))
print(f"Formatted duration string: {duration_str}")

# Example demonstrating nanosecond precision loss
td_nano_input = "1h1m1s1ns"
td_nano_parsed = durationpy.from_str(td_nano_input)
print(f"Original Go duration: {td_nano_input}")
print(f"Parsed (nanosecond precision is lost): {td_nano_parsed}")

view raw JSON →