* Improve unit testing of cylc/flow/wallclock.py

* Modernise docstring.

Author: wxtim

cylc/flow/wallclock.py

@@ -17,6 +17,7 @@
 
 from calendar import timegm
 from datetime import datetime, timedelta, timezone
+from typing import Dict, Optional
 
 from metomi.isodatetime.timezone import (
     get_local_time_zone_format, get_local_time_zone, TimeZoneFormatMode)
@@ -108,31 +109,45 @@ def get_current_time_string(display_sub_seconds=False, override_use_utc=None,
                            use_basic_format=use_basic_format)
 
 
-def get_time_string(date_time, display_sub_seconds=False,
-                    override_use_utc=None, use_basic_format=False,
-                    date_time_is_local=False, custom_time_zone_info=None):
+def get_time_string(
+    date_time: datetime,
+    display_sub_seconds: bool = False,
+    override_use_utc: Optional[bool] = None,
+    use_basic_format: bool = False,
+    date_time_is_local: bool = False,
+    custom_time_zone_info: Optional[Dict] = None,
+):
     """Return a string representing the current system time.
 
-    Arguments:
-    date_time - a datetime.datetime object.
-
-    Keyword arguments:
-    display_sub_seconds (default False) - a boolean that, if True,
-    switches on microsecond reporting
-    override_use_utc (default None) - a boolean (or None) that, if
-    True, switches on utc time zone reporting. If False, it switches
-    off utc time zone reporting (even if _FLAGS['utc_mode'] is True). If None,
-    the _FLAGS['utc_mode'] boolean is used.
-    use_basic_format (default False) - a boolean that, if True,
-    represents the date/time without "-" or ":" delimiters. This is
-    most useful for filenames where ":" may cause problems.
-    date_time_is_local - a boolean that, if True, indicates that
-    the date_time argument object is in the local time zone, not UTC.
-    custom_time_zone_info (default None) - a dictionary that enforces
-    a particular time zone. It looks like {"hours": _hours,
-    "minutes": _minutes, "string": _string} where _hours and _minutes
-    are the hours and minutes offset from UTC and _string is the string
-    to use as the time zone designator.
+    Args:
+        date_time: Datetime to operate on.
+        display_sub_seconds:
+            Switch on microsecond reporting.
+        override_use_utc:
+            Switch on utc time zone reporting.
+            If False, it switches off utc time zone reporting even
+            if ``_FLAGS['utc_mode']`` is True).
+            If None, the ``_FLAGS['utc_mode']`` boolean is used.
+        use_basic_format:
+            Represent the date/time without "-" or ":"
+            delimiters. This is useful for filenames, where ":" may
+            cause problems.
+        date_time_is_local:
+            Indicates that the date_time argument
+            object is in the local time zone, not UTC.
+        custom_time_zone_info:
+            A dictionary that enforces a particular time zone:
+
+            .. code-block:: python
+                {
+                    "hours": _hours,           # offset from UTC
+                    "minutes": _minutes,       # offset from utc
+                    "string_basic": _string,    # timezone designators
+                    "string_extened": _string
+                }
+
+            Usage of ``string_basic`` or ``string_extended`` is
+            switched by ``use_basic_format``.
 
     """
     time_zone_string = None

tests/unit/test_wallclock.py

@@ -14,12 +14,15 @@
 # You should have received a copy of the GNU General Public License
 # along with this program.  If not, see <http://www.gnu.org/licenses/>.
 
+from datetime import datetime
 import pytest
+from pytest import param
 
 from metomi.isodatetime.data import CALENDAR
 from cylc.flow.wallclock import (
-    get_unix_time_from_time_string,
     get_current_time_string,
+    get_time_string,
+    get_unix_time_from_time_string,
 )
 
 
@@ -73,3 +76,65 @@ def test_get_current_time_string(set_timezone):
     set_timezone()
     res = get_current_time_string()
     assert res[-6:] == '+19:17'
+
+
+@pytest.mark.parametrize(
+    'arg, kwargs, expect',
+    (
+        param(
+            datetime(2000, 12, 13, 15, 30, 12, 123456),
+            {},
+            '2000-12-14T10:47:12+19:17',
+            id='good',
+        ),
+        param(
+            datetime(2000, 12, 13, 15, 30, 12, 123456),
+            {'date_time_is_local': True},
+            '2000-12-13T15:30:12+19:17',
+            id='dt_is_local',
+        ),
+        param(
+            datetime(2000, 12, 13, 15, 30, 12, 123456),
+            {
+                'custom_time_zone_info': {
+                    'hours': 0,
+                    'minutes': -20,
+                    'string_basic': 'XXX+00:20',
+                },
+                'use_basic_format': True
+            },
+            '20001213T151012XXX+00:20',
+            id='custom_time_zone_info_string_basic',
+        ),
+        param(
+            datetime(2000, 12, 13, 15, 30, 12, 123456),
+            {
+                'custom_time_zone_info': {
+                    'hours': 0,
+                    'minutes': -20,
+                    'string_extended': ':UK/Exeter',
+                },
+                'use_basic_format': False
+            },
+            '2000-12-13T15:10:12:UK/Exeter',
+            id='custom_time_zone_info_string_extended',
+        ),
+        param(
+            datetime(2000, 12, 13, 15, 30, 12, 123456),
+            {
+                'custom_time_zone_info': {
+                    'hours': 0,
+                    'minutes': -20,
+                    'string_extended': ':UK/Exeter',
+                },
+                'use_basic_format': False,
+                'date_time_is_local': True,
+            },
+            '2000-12-12T19:53:12:UK/Exeter',
+            id='date_time_is_local',
+        ),
+    ),
+)
+def test_get_time_string(set_timezone, arg, kwargs, expect):
+    set_timezone()
+    assert get_time_string(arg, **kwargs) == expect