Improve usability of utils.sleep_until

Fix issue where sleeping for an extended period on python 3.5
would cause an exception

Add sleep_until to API docs

Add result argument to sleep_until

discord/ext/tasks/__init__.py

@@ -8,8 +8,6 @@ import logging
 
 from discord.backoff import ExponentialBackoff
 
-MAX_ASYNCIO_SECONDS = 3456000
-
 log = logging.getLogger(__name__)
 
 class Loop:
@@ -360,10 +358,6 @@ class Loop:
         """
 
         sleep = seconds + (minutes * 60.0) + (hours * 3600.0)
-        if sleep >= MAX_ASYNCIO_SECONDS:
-            fmt = 'Total number of seconds exceeds asyncio imposed limit of {0} seconds.'
-            raise ValueError(fmt.format(MAX_ASYNCIO_SECONDS))
-
         if sleep < 0:
             raise ValueError('Total number of seconds cannot be less than zero.')
 

discord/utils.py

@@ -43,6 +43,7 @@ from .errors import InvalidArgument
 from .object import Object
 
 DISCORD_EPOCH = 1420070400000
+MAX_ASYNCIO_SECONDS = 3456000
 
 class cached_property:
     def __init__(self, function):
@@ -338,7 +339,7 @@ async def sane_wait_for(futures, *, timeout):
 
     return done
 
-async def sleep_until(when):
+async def sleep_until(when, result=None):
     """Sleep until a specified time.
 
     If the time supplied is in the past this function will yield instantly.
@@ -347,6 +348,8 @@ async def sleep_until(when):
     -----------
     when: :class:`datetime.datetime`
         The timestamp in which to sleep until.
+    result: Any
+        If provided is returned to the caller when the coroutine completes.
 
     .. versionadded:: 1.3
     """
@@ -354,7 +357,10 @@ async def sleep_until(when):
         when = when.replace(tzinfo=datetime.timezone.utc)
     now = datetime.datetime.now(datetime.timezone.utc)
     delta = (when - now).total_seconds()
-    await asyncio.sleep(max(delta, 0))
+    while delta > MAX_ASYNCIO_SECONDS:
+        await asyncio.sleep(MAX_ASYNCIO_SECONDS)
+        delta -= MAX_ASYNCIO_SECONDS
+    return await asyncio.sleep(max(delta, 0), result)
 
 def valid_icon_size(size):
     """Icons must be power of 2 within [16, 4096]."""

docs/api.rst

@@ -725,6 +725,7 @@ Utility Functions
 
 .. autofunction:: discord.utils.resolve_invite
 
+.. autofunction:: discord.utils.sleep_until
 
 Profile
 ---------