Add Discord timestamp converter and transformer

discord/ext/commands/converter.py

@@ -24,6 +24,7 @@ DEALINGS IN THE SOFTWARE.
 
 from __future__ import annotations
 
+import datetime
 import inspect
 import re
 from typing import (
@@ -86,6 +87,7 @@ __all__ = (
     'clean_content',
     'Greedy',
     'Range',
+    'Timestamp',
     'run_converters',
 )
 
@@ -893,6 +895,28 @@ class GuildStickerConverter(IDConverter[discord.GuildSticker]):
         return result
 
 
+if TYPE_CHECKING:
+    Timestamp = datetime.datetime
+else:
+
+    class Timestamp(Converter[str]):
+        """Converts to a :class:`datetime.datetime`.
+
+        Conversion is attempted based on the :ddocs:`Discord style timestamp <reference#message-formatting>` input format.
+
+        .. versionadded:: 2.7
+
+        .. warning::
+            Due to a Discord limitation, no timezone is provided with the input. The UTC timezone has been supplanted instead.
+        """
+
+        async def convert(self, ctx: Context[BotT], argument: str) -> datetime.datetime:
+            match = discord.utils.TIMESTAMP_PATTERN.match(argument)
+            if not match:
+                raise BadTimestampArgument(argument)
+            return datetime.datetime.fromtimestamp(int(match[1]), tz=datetime.timezone.utc)
+
+
 class ScheduledEventConverter(IDConverter[discord.ScheduledEvent]):
     """Converts to a :class:`~discord.ScheduledEvent`.
 

discord/ext/commands/errors.py

@@ -79,6 +79,7 @@ __all__ = (
     'SoundboardSoundNotFound',
     'PartialEmojiConversionFailure',
     'BadBoolArgument',
+    'BadTimestampArgument',
     'MissingRole',
     'BotMissingRole',
     'MissingAnyRole',
@@ -602,6 +603,24 @@ class BadBoolArgument(BadArgument):
         super().__init__(f'{argument} is not a recognised boolean option')
 
 
+class BadTimestampArgument(BadArgument):
+    """Exception raised when a timestamp argument was not convertable.
+
+    This inherits from :exc:`BadArgument`
+
+    .. versionadded:: 2.7
+
+    Attributes
+    -----------
+    argument: :class:`str`
+        The datetime/timestamp argument supplied by the caller that was not a valid timestamp format.
+    """
+
+    def __init__(self, argument: str) -> None:
+        self.argument: str = argument
+        super().__init__(f'{argument} is not a recognised datetime or timestamp option')
+
+
 class RangeError(BadArgument):
     """Exception raised when an argument is out of range.