Metadata-Version: 2.1
Name: kerground
Version: 0.0.4
Summary: Background worker based on pickle and sqlite
Home-page: https://github.com/ClimenteA/kerground
Author: Climente Alin
Author-email: climente.alin@gmail.com
License: MIT
Platform: UNKNOWN
Description-Content-Type: text/markdown

# kerground 
[![Downloads](https://pepy.tech/badge/kerground)](https://pepy.tech/project/kerground) [![PyPI](https://img.shields.io/pypi/v/kerground?color=blue)](https://pypi.org/project/kerground/)

Background worker based on pickle, sqlite and multiprocessing.


## Quickstart

Install

```py
pip install kerground
```

Mark your file workers by naming them with `_worker.py` prefix

```py
my_worker.py
```

Kerground will look in `*_worker.py` and will consider each function an event. 
**Functions from `*_worker.py` files must be unique**

Import `Kerground`, instantiate it and start sending events

```py
from kerground import Kerground

ker = Kerground()

@app.route('/some-task')
def long_wait():
    id = ker.send('long_task') 
    # 'long_task' is a function name from *_worker.py files
    return {'id': id}

```

**Your api's and workers must be in the same package/directory**

```bash
root
├── api
│   ├── __init__.py
│   └── my_api.py
└── worker
    ├── __init__.py
    └── my_worker.py
```
You are free to use any folder structure. 


Open 2 cmd/terminal windows in the example directory:
- in one start your api `python3 api/my_api.py`
- in the other one type `kerground`

![kerground_example.gif](pics/kerground_example.gif)



## API

### `ker.send('func_name', *func_args)` 

Send event to kerground worker. `send` function will return the id of the task sent to the worker. 
You have **hot reload** on your workers by default! (as long you don't change function names)


### `ker.status(id)` 

Check status of a task with `status`. Kerground has the folowing statuses:
- pending  - event is added to kerground queue
- running  - event is running
- finished - event was executed succesfully
- failed   - event failed to be executed

Also you can check at any time the statuses of your tasks without specifing the id's:
```py
ker.pending() 
ker.running()
ker.finished()
ker.failed()
```
Or check all statuses with:
```py
ker.stats()
```


### `ker.get_response(id)`

Get the response from event (will be `None` if event didn't ran yet).

You can see functions collected from `*_worker.py` files with:
```py
ker.events
```

## Why

Under the hood kerground uses pickle for serialization of input/output data, a combination of `inspect` methods and built-in `getattr` function for dynamically calling the `"events"`(functions) from `*_worker.py` files. 
It's **resource frendly** (it doesn't use RAM to hold queue), **easy to use** (import kerground, mark your worker files with `_worker.py` prefix and you are set), **has hot reload for workers** (no need to restart workers each time you make a change) **works on multiple cores** (uses multiprocessing).


**Submit any questions/issues you have! Fell free to fork it and improve it!**

