Metadata-Version: 2.1
Name: PyBackground
Version: 0.1.2
Summary: A lightweight scheduler that runs tasks in the background
Home-page: https://github.com/yzhang-dev/PyBackground
Author: Yi Zhang
Author-email: yizhang.dev@gmail.com
License: MIT
Download-URL: https://github.com/yzhang-dev/PyBackground
Keywords: background-jobs,background-thread,tasks,background
Platform: UNKNOWN
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.7
Requires-Python: >=3.7
Description-Content-Type: text/markdown

# PyBackground

PyBackground is

* a lightweight scheduler that runs tasks in the background
* written in [Python (3.7+) Standard Library](https://docs.python.org/3.7/library/)



PyBackground supports to

* execute tasks using thread pool
* run in the background (or foreground)
* use `@task` decorator to define task



## Quickstart

Define your functions:

```python
import time

def now(cost=1):
    time.sleep(cost)
    print( time.strftime('%Y-%m-%d %H:%M:%S %Z', time.localtime()) )

def utcnow(cost=1):
    time.sleep(cost)
    print( time.strftime('%Y-%m-%d %H:%M:%S %Z', time.gmtime()) )
```

Create a PyBackground scheduler and start executing your functions:

```python
import pybackground

sched = pybackground.BackgroundScheduler()
sched.start(now, args=(1,))
sched.start(utcnow, args=(1,))
```

Shutdown the scheduler:

```python
sched.shutdown(wait=True)
```



### Handle with the infinite loops

Let's work based on `now(cost)` as an example:

```python
import pybackground

sched = pybackground.BackgroundScheduler()
print(sched.stopped)

def timer(interval=3):
    while not sched.stopped:
        now()

sched.start(timer, args=(3,))
```

`timer(interval)` then runs forever in a seperate thread. When you'd like to terminate it, shutdown the scheduler as usual:

```python
sched.shutdown(wait=True)
```



### Play with the `@task` decorator

Use `@task` decorator to define your functions and start executing them, scheduling `now(cost)` and `utcnow(cost)` as an example:

```python
import pybackground

sched = pybackground.BackgroundScheduler()

import time

@pybackground.task(sched)
def now(cost=1):
    time.sleep(cost)
    print( time.strftime('%Y-%m-%d %H:%M:%S %Z', time.localtime()) )

now.start(cost=1)

@pybackground.task(sched)
def utcnow(cost=1):
    time.sleep(cost)
    print( time.strftime('%Y-%m-%d %H:%M:%S %Z', time.gmtime()) )

utcnow.start(cost=1)
```

Shutdown the scheduler in normal way:

```python
sched.shutdown(wait=True)
```



### Install PyBackground

```bash
$ pip install pybackground
```



## Documentation

### `BackgroundScheduler`/`BlockingScheduler`

```python
class pybackground.BackgroundScheduler/BlockingScheduler(max_worker=<num_cpu_cores>)
```

`max_worker` is set for `ThreadPoolExecutor`, default value is the number of CPU cores.

* `stopped`

  The scheduler is stopped or not, `True` (default) or `False`.

* `latest_id`

  The latest task id, which may be useful for `pybackground.BlockingScheduler`. 

* `task`

  The task id, `Task` object (`collections.namedtuple('Task', 'fn, args, kwargs')`) dictionary, `{}` as default.

* `future`

  The task id, [`Future`](https://docs.python.org/3/library/concurrent.futures.html#concurrent.futures.Future) object dictionary, `{}` as default.

* `start(fn, args=(), kwargs={})`

  Let scheduler start executing your function using thread pool in the background (or foreground). It returns corresponding task id.

* `shutdown(wait=True)`

  Shutdown the scheduler.



### `task`

```python
class pybackground.task(scheduler)
```

* Use `@task` decorator to define your functions and start executing them:

  ```python
  @task(scheduler)
  def fn(args, kwargs):
      pass

  fn.start(*args, **kwargs)
  ```

  `fn.start(*args, **kwargs)` is equivaluent to `sheduler.start(fn, args, kwargs)` using normal function definition.



## Related Projects

* [APScheduler](https://github.com/agronholm/apscheduler) ([apscheduler.readthedocs.org](http://apscheduler.readthedocs.org))



