AsyncIO Task Runner (Coro Runner)

The AsyncIO Task Runner (Coro Runner) is a Python utility designed for managing concurrent asynchronous tasks using the built-in asyncio module. It provides an efficient way to execute multiple tasks in a single-threaded environment with customizable concurrency limits.

This project leverages asyncio (introduced in Python 3.4) to simplify handling of asynchronous workloads, making it ideal for lightweight, scalable applications.

Features

• Configurable Concurrency: Define the number of concurrent tasks when initializing the runner.
• Efficient Task Management: Run multiple tasks concurrently with streamlined execution control.
• Worker Queue: Multiple queue can be configued along with their priority.

Planned Enhancements

• Monitoring Tool Integration: Support for real-time task monitoring and analytics.
• Low-Level API: Features such as callbacks, acknowledgments, and error handling for advanced use cases.
• Robust Logging: Detailed logging to track task execution and debug issues.

Getting Started

Installation

To install coro-runner, use pip:

pip install coro-runner

Full documentation

Here is the full documentation

Quickstart

• Define and schedule tasks:

  from coro_runner import CoroRunner
  
  
  runner = CoroRunner(concurrency=25)
  # Add your tasks from anywhere b       
  runner.add_task(your_task()) # your_task must be a coroutine or future like object

• Task lifecycle management: (On app start and end you must run the runner. Don't worry it'll run under same process.)

  async def startup():
      await runner.run_until_exit()
  
  async def shutdown():
      await runner.cleanup()

Prerequisites

• Python 3.12 or later
• Poetry for dependency management

Installation and Setup

1. Clone the repository:

   git clone https://github.com/iashraful/async-coro-runner.git
   cd async-coro-runner

2. Activate the virtual environment:

   poetry shell

3. Install dependencies:

   poetry install

Running Tests

Run the test suite to verify the setup:

pytest -s

Sample Output:

Task started:  Task-1
Task ended:    Task-1
...

Example Usage

The project includes an example API implemented with FastAPI. It demonstrates how to use the task runner to manage asynchronous tasks.

Starting the API

1. Run the API server:

   uvicorn example:app --reload

2. Trigger tasks using the endpoint:

   GET /fire-task?count=25

How to Contribute

Contributions are welcome! Follow these steps to get started:

1. Fork the repository and create a new branch for your feature or bug fix.
2. Write tests for your changes.
3. Open a pull request with a clear description of your contribution.