Metadata-Version: 2.1
Name: coro-runner
Version: 0.0.2
Summary: It's a python based asyncio task schedular/queue mechanism
License: MIT
Author: Ashraful
Author-email: ashrafulrobin3@gmail.com
Requires-Python: >=3.12,<4.0
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Requires-Dist: fastapi[standard] (>=0.115.2,<0.116.0)
Description-Content-Type: text/markdown

# 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.

### 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

### Prerequisites

- Python 3.12 or later
- [Poetry](https://python-poetry.org/) for dependency management

### Installation and Setup

1. Clone the repository:
   ```bash
   git clone https://github.com/iashraful/async-coro-runner.git
   cd async-coro-runner
   ```

2. Activate the virtual environment:
   ```bash
   poetry shell
   ```

3. Install dependencies:
   ```bash
   poetry install
   ```

### Running Tests

Run the test suite to verify the setup:
```bash
pytest -s
```

**Sample Output:**
```text
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:
   ```bash
   uvicorn main:app --reload
   ```

2. Trigger tasks using the endpoint:
   ```bash
   GET /fire-task?count=25
   ```

### Code Highlights

- Define and schedule tasks:
  ```python
  runner = CoroRunner(concurrency=25)
  runner.add_task(rand_delay())
  ```
- Task lifecycle management:
  ```python
  async def startup():
      await runner.run_until_exit()
  
  async def shutdown():
      await runner.cleanup()
  ```

## 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.

