Doctests!

Signed-off-by: Flynn <emissary@flynn.kodachi.com>

kubernetes/utils/duration.py

@@ -35,10 +35,39 @@ def parse_duration(duration) -> datetime.timedelta:
     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
     """
 
     if not reDuration.match(duration):
@@ -62,6 +91,34 @@ def format_duration(delta: datetime.timedelta) -> str:
 
     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
     """
 
     # Short-circuit if we have a zero delta.