durationpy

0.10 verified Tue May 12 auth: no python install: verified quickstart: verified

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.

pip install durationpy

Common errors

error ModuleNotFoundError: No module named 'durationpy' ↓

cause The 'durationpy' library is not installed in your Python environment or is not accessible via the Python path.

fix

Install the library using pip: pip install durationpy

error ValueError: Invalid duration string format: 'PT10S' ↓

cause The input string provided to `durationpy.from_str()` does not conform to Go's standard `time.Duration` string format, which `durationpy` expects. For example, it does not support ISO 8601 duration strings like 'PT10S'.

fix

Provide a correctly formatted Go-style duration string (e.g., '10s', '1h30m', '5m2s'). Refer to the durationpy documentation for supported units and formats.

error TypeError: argument must be datetime.timedelta, not str ↓

cause An object that is not a `datetime.timedelta` instance (e.g., a string or integer) was passed to a `durationpy` function that expects a `timedelta` object, such as `durationpy.to_str()`.

fix

Ensure the input argument is a datetime.timedelta object. For example, from datetime import timedelta; durationpy.to_str(timedelta(seconds=10)).

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 compatibility verified last tested: 2026-05-12

python os / libc status wheel install import disk

3.10 alpine (musl) - - 0.01s 17.8M

3.10 slim (glibc) - - 0.00s 18M

3.11 alpine (musl) - - 0.01s 19.6M

3.11 slim (glibc) - - 0.01s 20M

3.12 alpine (musl) - - 0.00s 11.5M

3.12 slim (glibc) - - 0.00s 12M

3.13 alpine (musl) - - 0.00s 11.1M

3.13 slim (glibc) - - 0.00s 12M

3.9 alpine (musl) - - 0.01s 17.3M

3.9 slim (glibc) - - 0.00s 18M

Imports

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

Quickstart verified last tested: 2026-04-23

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}")