#############################################
 timer2 - Schedule Python functions.
#############################################

:Version: 0.1.0

Introduction
------------

The ``timer2`` module lets you schedule Python functions at specific times,
or at an interval. It can be used as a replacement to ``threading.Timer``,
the difference is that ``timer2`` is always only using a single thread (unless
you manually start more of them)

You should never use this to apply expensive operations, as this would not
be effective when running in a single thread, rather you should make the
timer move the operations to a execution pool (like a thread/multiprocessing
pool, or maybe sending a message)::

    >>> pool = multiprocessing.Pool()
    >>> timer2.apply_after(10000, pool.apply_async, (expensive_fun, ))

Documentation
-------------

Timer is using Sphinx, and the latest documentation is available at GitHub:

    http://ask.github.com/timer2

Installation
============

You can install ``timer2`` either via the Python Package Index (PyPI)
or from source.

To install using ``pip``,::

    $ pip install timer2

To install using ``easy_install``,::

    $ easy_install timer2


If you have downloaded a source tarball you can install it
by doing the following,::

    $ python setup.py build
    # python setup.py install # as root


Examples
========

Apply function after ``n`` msecs::

    >>> import timer2
    >>> timer2.apply_after(msecs, fun, args, kwargs, priority=0)

Apply function every ``n`` msecs::

    >>> timer2.apply_interval(msecs, fun, args, kwargs, priority=0)

Apply function at a specific date (a ``datetime`` object)::

    >>> timer2.apply_at(datetime, fun, args, kwargs, priority=0)

Cancelling timers
-----------------

The ``apply_*`` functions returns a ``timer2.Entry`` instance,
you can use this to cancel the execution::

    >>> tref = timer2.apply_after(msecs, fun, args, kwargs)
    >>> tref.cancel()


Running custom ``Timer`` threads
--------------------------------

When using the module interface a default timer thread is started
as soon as you schedule something. If you want to keep track of the
thread manually, you can use the ``timer2.Timer`` class::

    >>> timer = timer2.Timer()
    >>> timer.apply_after(msecs, fun, args, kwargs)
    >>> timer.stop() # stops the thread and joins it.

Bug tracker
===========

If you have any suggestions, bug reports or annoyances please report them
to our issue tracker at http://github.com/ask/timer2/issues/

Contributing
============

Development of ``timer2`` happens at Github: http://github.com/ask/timer2

You are highly encouraged to participate in the development. If you don't
like Github (for some reason) you're welcome to send regular patches.

License
=======

This software is licensed under the ``New BSD License``. See the ``LICENSE``
file in the top distribution directory for the full license text.