diff --git a/discord/utils.py b/discord/utils.py index 144706482..03478b3f5 100644 --- a/discord/utils.py +++ b/discord/utils.py @@ -401,6 +401,21 @@ async def sleep_until(when, result=None): delta = (when - now).total_seconds() return await asyncio.sleep(max(delta, 0), result) +def utcnow() -> datetime.datetime: + """A helper function to return an aware UTC datetime representing the current time. + + This should be preferred to :func:`datetime.datetime.utcnow` since it is an aware + datetime, compared to the naive datetime in the standard library. + + .. versionadded:: 2.0 + + Returns + -------- + :class:`datetime.datetime` + The current aware datetime in UTC. + """ + return datetime.datetime.now(datetime.timezone.utc) + def valid_icon_size(size): """Icons must be power of 2 within [16, 4096].""" return not size & (size - 1) and size in range(16, 4097) diff --git a/docs/api.rst b/docs/api.rst index 044f402ff..b328ab22a 100644 --- a/docs/api.rst +++ b/docs/api.rst @@ -922,6 +922,8 @@ Utility Functions .. autofunction:: discord.utils.sleep_until +.. autofunction:: discord.utils.utcnow + .. _discord-api-enums: Enumerations