diff --git a/AUTHORS.rst b/AUTHORS.rst index 0d0620fd..d85032f5 100644 --- a/AUTHORS.rst +++ b/AUTHORS.rst @@ -32,4 +32,5 @@ Thanks to all the wonderful folks who have contributed to schedule over the year - ebllg - fredthomsen - biggerfisch -- sosolidkk \ No newline at end of file +- sosolidkk +- 07pepa diff --git a/docs/asyncio.rst b/docs/asyncio.rst new file mode 100644 index 00000000..560397ed --- /dev/null +++ b/docs/asyncio.rst @@ -0,0 +1,52 @@ +Asyncio & Coroutines +==================== + +This example shows how to schedule an async job on the asyncio event loop. + +.. code-block:: python + + import schedule + import asyncio + + async def job_async(): + print("I am an async job") + await asyncio.sleep(1) + + schedule.every(5).seconds.do(lambda: asyncio.create_task(job_async())) + + async def scheduler(): + while True: + await asyncio.sleep(1) + schedule.run_pending() + + asyncio.run(scheduler()) + +The call to ``asyncio.create_task()`` submits the ``job_async`` coroutine to the asyncio event loop. +It may or may not run immediately, depending on the how busy the event loop is. + +Sleeping the right amount of time +--------------------------------- + +The ``scheduler()`` can be optimized by sleeping *exactly* [1]_ the amount of time until the next job is scheduled to run: + +.. code-block:: python + + async def scheduler(): + seconds = schedule.idle_seconds() + while seconds is not None: + if seconds > 0: + # sleep exactly the right amount of time + await asyncio.sleep(seconds) + schedule.run_pending() + seconds = schedule.idle_seconds() + + asyncio.run(scheduler()) + +Keep in mind that if a new job is scheduled while sleeping, the new job's earliest run is whenever the sleep finishes. + +More examples +------------- +More advanced usage examples of schedule and asyncio can be found in `this thread `_. + +.. rubric:: Footnotes +.. [1] `asyncio.sleep` may sleep little more then expected, depending on loop implementation of loop and system load. \ No newline at end of file diff --git a/docs/examples.rst b/docs/examples.rst index 397fc913..daf17b98 100644 --- a/docs/examples.rst +++ b/docs/examples.rst @@ -260,15 +260,13 @@ Returns ``None`` if no jobs are scheduled. schedule.every(5).seconds.do(job) - while 1: - n = schedule.idle_seconds() - if n is None: - # no more jobs - break - elif n > 0: + seconds = schedule.idle_seconds() + while seconds is not None: #None= no more jobs + if n > 0: # sleep exactly the right amount of time time.sleep(n) schedule.run_pending() + seconds = schedule.idle_seconds() Run all jobs now, regardless of their scheduling diff --git a/docs/faq.rst b/docs/faq.rst index 81519cff..961c34c4 100644 --- a/docs/faq.rst +++ b/docs/faq.rst @@ -68,6 +68,17 @@ How to continuously run the scheduler without blocking the main thread? ----------------------------------------------------------------------- :doc:`Background Execution`. +Does schedule support asyncio coroutines? +----------------------------------------- +Schedule does not accept coroutines as jobs directly yet. +However, using using ``asyncio.create_task`` you able to schedule async jobs. +See :doc:`this page ` for an example. + +What happens when my computer hibernates during time.sleep/wait +---------------------------------------------------------------- +Depending on python version it may behave erratically in undocumented ways `see `_ +in future this may be resolved by asyncio + Another question? ----------------- If you are left with an unanswered question, `browse the issue tracker `_ to see if your question has been asked before. diff --git a/docs/index.rst b/docs/index.rst index b2327ea6..f1195df4 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -16,11 +16,12 @@ Python job scheduling for humans. Run Python functions (or any other callable) p - A simple to use API for scheduling jobs, made for humans. - In-process scheduler for periodic jobs. No extra processes needed! - Very lightweight and no external dependencies. +- Works with :doc:`asyncio coroutines` - Excellent test coverage. - Tested on Python 3.6, 3.7, 3.8 and 3.9 -:doc:`Example ` +:doc:`Example` ------------------------- .. code-block:: bash @@ -75,6 +76,7 @@ Read More examples background-execution parallel-execution + asyncio exception-handling logging multiple-schedulers