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/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]."""