@@ -35,10 +35,39 @@ def parse_duration(duration) -> datetime.timedelta:
3535 See https://gateway-api.sigs.k8s.io/geps/gep-2257/ for more details.
3636
3737 Input: duration: string
38-
3938 Returns: datetime.timedelta
4039
4140 Raises: ValueError on invalid or unknown input
41+
42+ Examples:
43+ >>> parse_duration("1h")
44+ datetime.timedelta(seconds=3600)
45+ >>> parse_duration("1m")
46+ datetime.timedelta(seconds=60)
47+ >>> parse_duration("1s")
48+ datetime.timedelta(seconds=1)
49+ >>> parse_duration("1ms")
50+ datetime.timedelta(microseconds=1000)
51+ >>> parse_duration("1h1m1s")
52+ datetime.timedelta(seconds=3661)
53+ >>> parse_duration("10s30m1h")
54+ datetime.timedelta(seconds=5410)
55+
56+ Units are always required.
57+ >>> parse_duration("1")
58+ Traceback (most recent call last):
59+ ...
60+ ValueError: Invalid duration format: 1
61+
62+ Floating-point and negative durations are not valid.
63+ >>> parse_duration("1.5m")
64+ Traceback (most recent call last):
65+ ...
66+ ValueError: Invalid duration format: 1.5m
67+ >>> parse_duration("-1m")
68+ Traceback (most recent call last):
69+ ...
70+ ValueError: Invalid duration format: -1m
4271 """
4372
4473 if not reDuration .match (duration ):
@@ -62,6 +91,34 @@ def format_duration(delta: datetime.timedelta) -> str:
6291
6392 Raises: ValueError if the timedelta given cannot be expressed as a
6493 GEP-2257 Duration.
94+
95+ Examples:
96+ >>> format_duration(datetime.timedelta(seconds=3600))
97+ '1h'
98+ >>> format_duration(datetime.timedelta(seconds=60))
99+ '1m'
100+ >>> format_duration(datetime.timedelta(seconds=1))
101+ '1s'
102+ >>> format_duration(datetime.timedelta(microseconds=1000))
103+ '1ms'
104+ >>> format_duration(datetime.timedelta(seconds=5410))
105+ '1h30m10s'
106+
107+ The zero duration is always "0s".
108+ >>> format_duration(datetime.timedelta(0))
109+ '0s'
110+
111+ Sub-millisecond precision is not allowed.
112+ >>> format_duration(datetime.timedelta(microseconds=100))
113+ Traceback (most recent call last):
114+ ...
115+ ValueError: Cannot express sub-millisecond precision in GEP-2257: 0:00:00.000100
116+
117+ Negative durations are not allowed.
118+ >>> format_duration(datetime.timedelta(seconds=-1))
119+ Traceback (most recent call last):
120+ ...
121+ ValueError: Cannot express negative durations in GEP-2257: -1 day, 23:59:59
65122 """
66123
67124 # Short-circuit if we have a zero delta.
0 commit comments