kubernetes.utils.duration module

kubernetes.utils.duration.format_duration(delta: timedelta) → str

Format a datetime.timedelta object to GEP-2257 Duration format.

The GEP-2257 Duration format is a restricted form of the input to the Go time.ParseDuration function; specifically, it must match the regex “^([0-9]{1,5}(h|m|s|ms)){1,4}$”.

See https://gateway-api.sigs.k8s.io/geps/gep-2257/ for more details.

Input: duration: datetime.timedelta

Returns: string

Raises: ValueError if the timedelta given cannot be expressed as a GEP-2257 Duration.

Examples: >>> format_duration(datetime.timedelta(seconds=3600)) ‘1h’ >>> format_duration(datetime.timedelta(seconds=60)) ‘1m’ >>> format_duration(datetime.timedelta(seconds=1)) ‘1s’ >>> format_duration(datetime.timedelta(microseconds=1000)) ‘1ms’ >>> format_duration(datetime.timedelta(seconds=5410)) ‘1h30m10s’

The zero duration is always “0s”. >>> format_duration(datetime.timedelta(0)) ‘0s’

Sub-millisecond precision is not allowed. >>> format_duration(datetime.timedelta(microseconds=100)) Traceback (most recent call last):

…

ValueError: Cannot express sub-millisecond precision in GEP-2257: 0:00:00.000100

Negative durations are not allowed. >>> format_duration(datetime.timedelta(seconds=-1)) Traceback (most recent call last):

…

ValueError: Cannot express negative durations in GEP-2257: -1 day, 23:59:59

kubernetes.utils.duration.parse_duration(duration) → timedelta

Parse GEP-2257 Duration format to a datetime.timedelta object.

The GEP-2257 Duration format is a restricted form of the input to the Go time.ParseDuration function; specifically, it must match the regex “^([0-9]{1,5}(h|m|s|ms)){1,4}$”.

See https://gateway-api.sigs.k8s.io/geps/gep-2257/ for more details.

Input: duration: string Returns: datetime.timedelta

Raises: ValueError on invalid or unknown input

Examples: >>> parse_duration(“1h”) datetime.timedelta(seconds=3600) >>> parse_duration(“1m”) datetime.timedelta(seconds=60) >>> parse_duration(“1s”) datetime.timedelta(seconds=1) >>> parse_duration(“1ms”) datetime.timedelta(microseconds=1000) >>> parse_duration(“1h1m1s”) datetime.timedelta(seconds=3661) >>> parse_duration(“10s30m1h”) datetime.timedelta(seconds=5410)

Units are always required. >>> parse_duration(“1”) Traceback (most recent call last):

…

ValueError: Invalid duration format: 1

Floating-point and negative durations are not valid. >>> parse_duration(“1.5m”) Traceback (most recent call last):

…

ValueError: Invalid duration format: 1.5m >>> parse_duration(“-1m”) Traceback (most recent call last):

…

ValueError: Invalid duration format: -1m