durationpy

library0.10pypypi✓ verified 49d ago

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.

serialization data

pip install durationpy

github ↗package ↗

Install & Compatibility

Where this runs

tested against v0.10 · pip install

no network on importno background threads

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

py 3.10–3.925 runs

installs and imports cleanly · install 0.0s · import 0.004s · 17.8MB

glibc

py 3.10–3.925 runs

installs and imports cleanly · install 1.5s · import 0.002s · 18MB

16MB installed

● package 16MB

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

from_str

✓ from durationpy import from_str

to_str

✓ from durationpy import to_str

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

Debug

Known issues

gotchaNanosecond 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.

affects: All versions

gotchaThe `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`.

affects: All versions

Errors

Common errors & fixes

ModuleNotFoundError: No module named 'durationpy'

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`

ValueError: Invalid duration string format: 'PT10S'

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.

TypeError: argument must be datetime.timedelta, not str

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))`.

Upgrade

Version history

0.10latest on PyPI

Audit

Dependencies

No dependency data recorded yet.

Agent activity

14 hits · last 30 days

node

seranking-bot

ahrefsbot