Merge pull request #473 from python-discord/ISODate-converter

Add converter for ISO-formatted datetime strings

2 files changed, 122 insertions, 0 deletions

diff --git a/bot/converters.py b/bot/converters.py
index 6d6453486..cf0496541 100644
--- a/bot/converters.py
+++ b/bot/converters.py
@@ -4,6 +4,8 @@ from datetime import datetime
 from ssl import CertificateError
 from typing import Union
 
+import dateutil.parser
+import dateutil.tz
 import discord
 from aiohttp import ClientConnectorError
 from dateutil.relativedelta import relativedelta
@@ -215,3 +217,45 @@ class Duration(Converter):
         now = datetime.utcnow()
 
         return now + delta
+
+
+class ISODateTime(Converter):
+    """Converts an ISO-8601 datetime string into a datetime.datetime."""
+
+    async def convert(self, ctx: Context, datetime_string: str) -> datetime:
+        """
+        Converts a ISO-8601 `datetime_string` into a `datetime.datetime` object.
+
+        The converter is flexible in the formats it accepts, as it uses the `isoparse` method of
+        `dateutil.parser`. In general, it accepts datetime strings that start with a date,
+        optionally followed by a time. Specifying a timezone offset in the datetime string is
+        supported, but the `datetime` object will be converted to UTC and will be returned without
+        `tzinfo` as a timezone-unaware `datetime` object.
+
+        See: https://dateutil.readthedocs.io/en/stable/parser.html#dateutil.parser.isoparse
+
+        Formats that are guaranteed to be valid by our tests are:
+
+        - `YYYY-mm-ddTHH:MM:SSZ` | `YYYY-mm-dd HH:MM:SSZ`
+        - `YYYY-mm-ddTHH:MM:SS±HH:MM` | `YYYY-mm-dd HH:MM:SS±HH:MM`
+        - `YYYY-mm-ddTHH:MM:SS±HHMM` | `YYYY-mm-dd HH:MM:SS±HHMM`
+        - `YYYY-mm-ddTHH:MM:SS±HH` | `YYYY-mm-dd HH:MM:SS±HH`
+        - `YYYY-mm-ddTHH:MM:SS` | `YYYY-mm-dd HH:MM:SS`
+        - `YYYY-mm-ddTHH:MM` | `YYYY-mm-dd HH:MM`
+        - `YYYY-mm-dd`
+        - `YYYY-mm`
+        - `YYYY`
+
+        Note: ISO-8601 specifies a `T` as the separator between the date and the time part of the
+        datetime string. The converter accepts both a `T` and a single space character.
+        """
+        try:
+            dt = dateutil.parser.isoparse(datetime_string)
+        except ValueError:
+            raise BadArgument(f"`{datetime_string}` is not a valid ISO-8601 datetime string")
+
+        if dt.tzinfo:
+            dt = dt.astimezone(dateutil.tz.UTC)
+            dt = dt.replace(tzinfo=None)
+
+        return dt
diff --git a/tests/test_converters.py b/tests/test_converters.py
index 35fc5d88e..f69995ec6 100644
--- a/tests/test_converters.py
+++ b/tests/test_converters.py
@@ -8,6 +8,7 @@ from discord.ext.commands import BadArgument
 
 from bot.converters import (
     Duration,
+    ISODateTime,
     TagContentConverter,
     TagNameConverter,
     ValidPythonIdentifier,
@@ -184,3 +185,80 @@ def test_duration_converter_for_invalid(duration: str):
     converter = Duration()
     with pytest.raises(BadArgument, match=f'`{duration}` is not a valid duration string.'):
         asyncio.run(converter.convert(None, duration))
+
+
[email protected](
+    ("datetime_string", "expected_dt"),
+    (
+
+        # `YYYY-mm-ddTHH:MM:SSZ` | `YYYY-mm-dd HH:MM:SSZ`
+        ('2019-09-02T02:03:05Z', datetime.datetime(2019, 9, 2, 2, 3, 5)),
+        ('2019-09-02 02:03:05Z', datetime.datetime(2019, 9, 2, 2, 3, 5)),
+
+        # `YYYY-mm-ddTHH:MM:SS±HH:MM` | `YYYY-mm-dd HH:MM:SS±HH:MM`
+        ('2019-09-02T03:18:05+01:15', datetime.datetime(2019, 9, 2, 2, 3, 5)),
+        ('2019-09-02 03:18:05+01:15', datetime.datetime(2019, 9, 2, 2, 3, 5)),
+        ('2019-09-02T00:48:05-01:15', datetime.datetime(2019, 9, 2, 2, 3, 5)),
+        ('2019-09-02 00:48:05-01:15', datetime.datetime(2019, 9, 2, 2, 3, 5)),
+
+        # `YYYY-mm-ddTHH:MM:SS±HHMM` | `YYYY-mm-dd HH:MM:SS±HHMM`
+        ('2019-09-02T03:18:05+0115', datetime.datetime(2019, 9, 2, 2, 3, 5)),
+        ('2019-09-02 03:18:05+0115', datetime.datetime(2019, 9, 2, 2, 3, 5)),
+        ('2019-09-02T00:48:05-0115', datetime.datetime(2019, 9, 2, 2, 3, 5)),
+        ('2019-09-02 00:48:05-0115', datetime.datetime(2019, 9, 2, 2, 3, 5)),
+
+        # `YYYY-mm-ddTHH:MM:SS±HH` | `YYYY-mm-dd HH:MM:SS±HH`
+        ('2019-09-02 03:03:05+01', datetime.datetime(2019, 9, 2, 2, 3, 5)),
+        ('2019-09-02T01:03:05-01', datetime.datetime(2019, 9, 2, 2, 3, 5)),
+
+        # `YYYY-mm-ddTHH:MM:SS` | `YYYY-mm-dd HH:MM:SS`
+        ('2019-09-02T02:03:05', datetime.datetime(2019, 9, 2, 2, 3, 5)),
+        ('2019-09-02 02:03:05', datetime.datetime(2019, 9, 2, 2, 3, 5)),
+
+        # `YYYY-mm-ddTHH:MM` | `YYYY-mm-dd HH:MM`
+        ('2019-11-12T09:15', datetime.datetime(2019, 11, 12, 9, 15)),
+        ('2019-11-12 09:15', datetime.datetime(2019, 11, 12, 9, 15)),
+
+        # `YYYY-mm-dd`
+        ('2019-04-01', datetime.datetime(2019, 4, 1)),
+
+        # `YYYY-mm`
+        ('2019-02-01', datetime.datetime(2019, 2, 1)),
+
+        # `YYYY`
+        ('2025', datetime.datetime(2025, 1, 1)),
+    ),
+)
+def test_isodatetime_converter_for_valid(datetime_string: str, expected_dt: datetime.datetime):
+    converter = ISODateTime()
+    converted_dt = asyncio.run(converter.convert(None, datetime_string))
+    assert converted_dt.tzinfo is None
+    assert converted_dt == expected_dt
+
+
[email protected](
+    ("datetime_string"),
+    (
+        # Make sure it doesn't interfere with the Duration converter
+        ('1Y'),
+        ('1d'),
+        ('1H'),
+
+        # Check if it fails when only providing the optional time part
+        ('10:10:10'),
+        ('10:00'),
+
+        # Invalid date format
+        ('19-01-01'),
+
+        # Other non-valid strings
+        ('fisk the tag master'),
+    ),
+)
+def test_isodatetime_converter_for_invalid(datetime_string: str):
+    converter = ISODateTime()
+    with pytest.raises(
+        BadArgument,
+        match=f"`{datetime_string}` is not a valid ISO-8601 datetime string",
+    ):
+        asyncio.run(converter.convert(None, datetime_string))