Metadata-Version: 2.1
Name: redis-work-queue
Version: 0.2.dev1
Summary: A work queue, on top of a redis database, with implementations in Python, Rust, Go, Node.js (TypeScript) and Dotnet (C#).
Author-email: Jacob O'Toole <jacob.otoole@mevitae.com>
License: Copyright 2023 Jacob O'Toole
        
        Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the “Software”), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
        
        The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
        
        THE SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
        
Classifier: Programming Language :: Python :: 3
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: redis
Requires-Dist: uuid

A work queue, on top of a redis database, with implementations in Python, Rust, Go, Node.js
(TypeScript) and Dotnet (C#).

This is the Python implementations. For an overview of how the work queue works, it's limitations,
and the general concepts and implementations in other languages, please read the [redis-work-queue
readme](https://github.com/MeVitae/redis-work-queue/blob/main/README.md).

## Setup

```python
from redis import Redis
from redis_work_queue import KeyPrefix, WorkQueue

db = Redis(host='your-redis-server')

work_queue = WorkQueue(KeyPrefix("example_work_queue"));
```

## Adding work

### Creating `Item`s

```python
from redis_work_queue import Item

# Create an item from bytes
bytes_item = Item(b"[1,2,3]")

# Create an item from a string
string_item = Item('[1,2,3]');

# Create an item by json serializing an object
json_item = Item.from_json_data([1, 2, 3])

# Retreive an item's data, as bytes:
assert bytes_item.data() == b"[1,2,3]"
assert bytes_item.data() == string_item.data()
assert bytes_item.data() == json_item.data()

# Parse an item's data as JSON:
assert bytes_item.data_json() == [1, 2, 3]
```

### Add an item to a work queue
```python
work_queue.add_item(db, item)
```

## Completing work

Please read [the documentation on leasing and completing
items](https://github.com/MeVitae/redis-work-queue/blob/main/README.md#leasing-an-item).

```python
from redis_work_queue import Item

while True:
    # Wait for a job with no timeout and a lease time of 5 seconds.
    # Use work_queue.lease(db, 5, timeout=10) to timeout and return `None` after 10 seconds.
    job: Item | None = work_queue.lease(db, 5)
    assert job is not None
    do_some_work(job)
    work_queue.complete(db, job)
```

### Handling errors

Please read [the documentation on handling
errors](https://github.com/MeVitae/redis-work-queue/blob/main/README.md#handling-errors).

```python
from redis_work_queue import Item

while True:
    # Wait for a job with no timeout and a lease time of 5 seconds.
    job: Item = work_queue.lease(db, 5)
    try:
        do_some_work(job)
    except Exception as err:
        if should_retry(err):
            # Drop a job that should be retried - it will be returned to the work queue after
            # the (5 second) lease expires.
            pass
        else:
            # Errors that shouldn't cause a retry should mark the job as complete so it isn't
            # tried again.
            log_error(err)
            work_queue.complete(db, &job)
        continue
    # Mark successful jobs as complete
    work_queue.complete(db, job)
```
