Metadata-Version: 2.4
Name: qtasks
Version: 1.7.1
Summary: Queue Tasks Framework
Author-email: txello <txello7@proton.me>
License: Apache-2.0
Project-URL: Documentation, https://txello.github.io/qtasks
Project-URL: Homepage, https://github.com/txello/qtasks
Project-URL: Issues, https://github.com/txello/qtasks/issues
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Software Development :: Libraries
Classifier: Topic :: System :: Distributed Computing
Classifier: Topic :: System :: Networking
Classifier: Topic :: Utilities
Classifier: Framework :: AsyncIO
Classifier: Operating System :: OS Independent
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: typing-extensions>=4.12.2
Requires-Dist: redis>=5.2.1
Requires-Dist: anyio<4.9.0,>=4.5.0; python_version < "3.11"
Requires-Dist: anyio>=4.9.0; python_version >= "3.11"
Requires-Dist: asyncio_atexit>=1.0.1
Requires-Dist: apscheduler>=3.11.0
Requires-Dist: pydantic<2.11.7,>=2.10.6; python_version < "3.11"
Requires-Dist: pydantic>=2.11.7; python_version >= "3.11"
Provides-Extra: redis
Requires-Dist: redis>=5.2.1; extra == "redis"
Provides-Extra: rabbitmq
Requires-Dist: aio-pika>=9.5.5; extra == "rabbitmq"
Requires-Dist: pika>=1.3.2; extra == "rabbitmq"
Provides-Extra: kafka
Requires-Dist: kafka>=2.2.10; extra == "kafka"
Requires-Dist: aiokafka>=0.12.0; extra == "kafka"
Provides-Extra: test
Requires-Dist: pytest<8.4.1,>=8.3.5; python_version < "3.11" and extra == "test"
Requires-Dist: pytest>=8.4.1; python_version >= "3.11" and extra == "test"
Requires-Dist: pytest-asyncio<1.1.0,>=0.24.0; python_version < "3.11" and extra == "test"
Requires-Dist: pytest-asyncio>=1.1.0; python_version >= "3.11" and extra == "test"
Dynamic: license-file

# QTasks

![CI](https://github.com/txello/qtasks/actions/workflows/ci.yml/badge.svg)
![Docs](https://github.com/txello/qtasks/actions/workflows/docs.yml/badge.svg)
[![PyPI Downloads](https://static.pepy.tech/personalized-badge/qtasks?period=total\&units=INTERNATIONAL_SYSTEM\&left_color=BLACK\&right_color=GREEN\&left_text=downloads)](https://pepy.tech/projects/qtasks)
![Python](https://img.shields.io/pypi/pyversions/qtasks)
![License](https://img.shields.io/github/license/txello/qtasks)

**QTasks** is a modern task queue framework for Python with a component-based
architecture and a focus on extensibility, transparency, and control over task execution.
The project is aimed at both small services and complex distributed systems
where standard solutions are redundant or inflexible.

---

## Key features

* **Component-based architecture**
  Broker, Worker, Storage, GlobalConfig, Starter — each component is isolated and
  fully replaceable.

* **Async and Sync tasks**
  Support for `asyncio`, synchronous functions, and generators.

* **Plugins instead of rigid logic**
  Retry, concurrency, logging, and execution strategies are implemented
  through plugins.

* **Typed data flow**
  Data transfer between components via schemas (`dataclasses`).

* **Transparent testing**
  In-memory brokers and storages, component isolation, tests without running workers.

* **CLI-first approach**
  Manage startup and environment through CLI without hidden magic.

---

## When to choose QTasks

* You need full control over the queue architecture.
* You need to write your own brokers, workers, and plugins.
* Predictable behavior and minimalism of the core are important.
* The project is growing and requires scalability without rewriting the logic.

---

## Installation

### Basic installation (Redis by default)

```bash
pip install qtasks
```

### Additional brokers

#### RabbitMQ

```bash
pip install qtasks[rabbitmq]
```

#### Kafka

```bash
pip install qtasks[kafka]
```

---

## Quick start

```python
from qtasks import QueueTasks

app = QueueTasks()

@app.task(name="echo")
def echo(text: str) -> str:
    return text

@app.task(name="divide")
def divide(a: int, b: int):
    return a / b

if __name__ == "__main__":
    app.run_forever()
```

Calling tasks:

```python
# echo.add_task("Hello", timeout=50).returning -> "Hello"
# divide.add_task(1, 0, timeout=50).status -> "ERROR"
```

---

## Generators and streaming tasks

QTasks supports generator tasks without additional wrappers:

```python
async def gen_handler(value: int) -> int:
    return value + 1

@app.task(generate_handler=gen_handler)
async def counter(n: int):
    for _ in range(n):
        n += 1
        yield n
```

Result of execution:

```python
# await (counter.add_task(5, timeout=50)).returning -> [7, 8, 9, 10, 11]
```

---

## CLI

Starting the worker:

```bash
qtasks -A qtasks_app:app run
```

Or directly:

```bash
python -m qtasks -A qtasks_app:app run
```

In the future, the CLI will be expanded (inspect, stats, monitoring).

---

## Architecture (briefly)

```md
┌──────────┐          ┌──────────┐
│  Broker  │ ───────▶ │          │
│          │          │          │
└────┬─────┘          │          │
     │                │ Storage  │
     ▼                │          │
┌──────────┐ ───────▶ │          │
│  Worker  │          │          │
│          │          └──────────┘
└──────────┘
```

Additionally:

* plugins;
* routers;
* background components;
* WebView (optional).

---

## Documentation

👉 [https://docs.qtasks.tech](https://docs.qtasks.tech)

---

## Project status

* Active development
* Stable versions
* Python 3.8–3.12
* Open to contributions

---

## License

MIT License
