Feature: Add support for scheduling async coroutines

[srics96]

Feature Request

Add the ability to schedule async coroutines alongside regular functions. This is the most requested feature in the upstream project (29+ comments across multiple issues).

Desired API

import schedule
import asyncio

async def async_job():
    await some_async_operation()

# Schedule an async coroutine
schedule.every(10).seconds.do(async_job)

# Run with async support
async def main():
    while True:
        await schedule.async_run_pending()
        await asyncio.sleep(1)

asyncio.run(main())

Implementation Notes

1. Add an async_run_pending() method to Scheduler that awaits coroutine jobs
2. In Job.run(), detect if the job function is a coroutine (using asyncio.iscoroutinefunction()) and handle it appropriately
3. Keep backward compatibility — regular (sync) jobs must continue to work exactly as before
4. Add run_pending() support for mixed sync/async jobs (sync jobs run normally, async jobs are awaited)
5. Do NOT add any external dependencies — use only Python's built-in asyncio module
6. Add comprehensive tests covering:
   • Scheduling and running async jobs
   • Mixed sync and async jobs in the same scheduler
   • CancelJob return value from async jobs
   • Error handling in async jobs

References

• Upstream: AsyncScheduler: Ability to schedule сoroutines dbader/schedule#357 (29 comments, original request from 2020)
• Upstream: scheduler: add support for async jobs dbader/schedule#647 (unmerged PR with implementation)
• Upstream: Add support for async jobs dbader/schedule#438 (another async PR attempt)
• Upstream: new: apply schedule with asynchronous mode dbader/schedule#339 (yet another async attempt)

[ghost-ship-ai]

🗺️ Ghost Ship Plan

Implementation Plan: Add Async Coroutine Scheduling Support

What will change

• schedule/__init__.py - Add async detection, async_run_pending() method, and modify Job.run() to handle coroutines
• test_schedule.py - Add comprehensive async test cases covering scheduling, mixed sync/async jobs, cancellation, and error handling

Approach

1. Import asyncio at module level

   • Add import asyncio to the imports section in schedule/__init__.py

2. Modify Job.run() method

   • Before calling self.job_func(*self.args, **self.kwargs), check asyncio.iscoroutinefunction(self.job_func)
   • If it's a coroutine function, call it but don't await - return the coroutine object
   • If it's a regular function, execute normally and return the result
   • Update return type handling to accommodate both sync results and coroutine objects

3. Add async_run_pending() method to Scheduler class

   • Create new method that iterates through scheduled jobs like run_pending()
   • For each job that should_run(), call job.run()
   • If the result is a coroutine (check with asyncio.iscoroutine()), await it
   • If the result is not a coroutine, use it as-is
   • Handle CancelJob return values from both sync and async jobs
   • Maintain the same job removal logic as run_pending()

4. Update run_pending() method for mixed mode support

   • Modify existing run_pending() to detect when a job returns a coroutine
   • For coroutine results, create a temporary event loop if none exists, or use existing loop
   • Await the coroutine in the current context
   • Preserve existing behavior for sync jobs

5. Update module exports

   • Ensure async_run_pending is accessible via the default scheduler instance
   • Add it to __all__ if present, or ensure it's available on the module-level scheduler object

Testing

New test cases to add to test_schedule.py:

1. Basic async job scheduling

   • test_async_job_scheduling() - Schedule simple async function, verify it runs
   • test_async_job_with_arguments() - Test async jobs with args and kwargs

2. Mixed sync/async scenarios

   • test_mixed_sync_async_jobs() - Schedule both types, run with async_run_pending()
   • test_sync_jobs_still_work() - Verify backward compatibility with pure sync workflows

3. Cancellation support

   • test_async_job_cancel() - Async job returning CancelJob should be removed from schedule
   • test_mixed_cancel_behavior() - Mix of sync/async jobs with some returning CancelJob

4. Error handling

   • test_async_job_exception() - Async job raising exception should not crash scheduler
   • test_async_job_timeout_behavior() - Verify async jobs don't block other jobs indefinitely

5. Integration tests

   • test_async_run_pending_empty_schedule() - Call on empty scheduler
   • test_async_with_different_intervals() - Multiple async jobs with different schedules

Test utilities needed:

• Helper async functions for testing (simple delay, exception raising, cancellation)
• Async test methods using asyncio.run() or similar test framework support

Risk assessment

High Risk:

• Backward compatibility break - Changes to Job.run() must not alter return behavior for sync jobs
• Event loop conflicts - Multiple event loops or no event loop scenarios could cause runtime errors
• Performance regression - Adding asyncio overhead to sync-only workflows

Medium Risk:

• Coroutine detection edge cases - Partial functions, lambdas, or decorated functions might not be detected correctly
• CancelJob handling - Async jobs returning CancelJob need same removal behavior as sync jobs
• Exception propagation - Async exceptions must be handled consistently with sync exceptions

Low Risk:

• Import overhead - Adding import asyncio is minimal performance impact
• Test coverage gaps - Existing 81 tests provide good foundation, new tests should maintain coverage level

Mitigation strategies:

• Run full existing test suite to ensure no regressions
• Test with Python 3.7+ to verify asyncio compatibility across versions
• Add explicit checks for event loop availability
• Preserve exact existing behavior for run_pending() with sync jobs only

---

Reply to discuss this plan. Tag @ghost-ship-ai to request changes. A maintainer can comment approve to start implementation.