Metadata-Version: 2.1
Name: recurring
Version: 2.0.0
Summary: Run a function or other callable every N seconds
Home-page: https://github.com/jdodds/recurring
Author: Jeremiah Dodds
Author-email: jeremiah.dodds@gmail.com
License: UNKNOWN
Project-URL: Issue Tracker, https://github.com/jdodds/recurring/issues
Project-URL: Source, https://github.com/jdodds/recurring
Project-URL: Docs, https://recurring.readthedocs.io
Keywords: scheduling repeating cron sched threads
Platform: UNKNOWN
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Natural Language :: English
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Programming Language :: Python :: 3.6
Classifier: Programming Language :: Python :: Implementation :: CPython
Requires-Python: >=3.6
Description-Content-Type: text/markdown
Provides-Extra: docs
Provides-Extra: docs
Requires-Dist: m2r; extra == 'docs'

# Recurring
[![Build Status](https://travis-ci.org/jdodds/recurring.svg?branch=master)](https://travis-ci.org/jdodds/recurring) [![Coverage Status](https://coveralls.io/repos/github/jdodds/recurring/badge.svg?branch=master)](https://coveralls.io/github/jdodds/recurring?branch=master) [![Documentation Status](https://readthedocs.org/projects/recurring/badge/?version=latest)](https://recurring.readthedocs.io/en/latest/?badge=latest)


This is a simple library for running a function or callable every N seconds. It's meant for applications that need to schedule small, self-contined callable(s) on a relatively long, potentially changing period . alive-checks, state snapshots, that sort of thing.

## Use this if:
+ You want to call something periodically over the lifetime of your application.
+ You want to be able to change the time between calls.
+ You want or need to avoid the overhead of `join`ing and `start`ing a thread every time. (up to 1/5 of a second according to my sample-size of one machine under no other load)
+ The stuff you're going to call isn't going to destroy machines if it's killed abruptly at the end of the application's life.

## This is probably not appropriate for your project if:
+ You're already using or likely will be using a fleshed-out concurrency framework.
+ You have many things you'd like to repeatedly schedule and run.
+ Your callables absolutely **must** execute some cleanup code to avoid disaster on kill.


This is not a library intended for top-level program composition.

## Installation:

    pip install recurring

## Usage:


    import recurring

    def stuff():
        # do stuff ...

    seconds_between_stuff = 30

    job = recurring.job(stuff, seconds_between_stuff)
    job.start()

    # ...

    seconds_between_stuff = 300000000 # this will be *from when rate is set*, not *from the next scheduled call*
    job.rate = seconds_between_stuff

    # ...

    # stop making calls until start() is called again
    job.stop()

    # some time later ....
    job.start()

    # stop making calls permanently
    job.terminate()
    job.start() # raises RuntimeError
    job.rate = 3000 # raises RuntimeError


