hesitate 0.0.2
A stochastic Design by Contract utility
License: BSD

********
Hestiate
********

.. image:: https://travis-ci.org/mhallin/hesitate-py.svg?branch=master
   :target: https://travis-ci.org/mhallin/hesitate-py

Like ``assert``, but less... assertive.

----

Are you skipping on writing your ``assert`` statements because of performance reasons? Skip no more!
Hesitate will, through probabilistic means, make your Design by Contract-assertions faster!


How?
====

By not executing them.

...

Yeah.

Hesitate will measure the execution time on every assert statement you write, and execute the slow
ones less frequently than the fast ones. You decide on what you think is a reasonable amount of time
per assertion on average, and Hesitate will control how often your assertions run in order to match
that.

It looks like this:

.. code-block:: python

    # worker.py

    def do_work(data):
        assert data_is_valid(data)  # Super slow!

        return work_work(data)


    # main.py

    import hesitate
    hesitate.attach_hook(
        target_timing=0.002,  # 2 milliseconds per assert on average
    )

    import worker
    worker.do_work(invalid_data)  # Might not raise AssertionError! Who knows?

Hesitate works with an AST rewriter influenced to py.test_. It hooks on to Python's module loader
where it intercepts and rewrites code on the fly as it is loaded. Hesitate stores assertion timings
in a plain dictionary, so everything is forgotten when the application quits. This makes it most
useful for long-living processes, such as application servers.


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

.. code-block:: sh

    pip install hesitate

Call ``hesitate.attach_hook()`` as soon as possible when your application starts. It must be done
before any modules you want Hesitate to plug in to are loaded. ``attach_hook`` takes three optional arguments:

* ``initial_probability`` - the probability an assert is initially run, before its timing is known.
  The default is 1.0, which causes all asserts to trigger on their first run. Lower this value to
  avoid flooding the system with potentially slow assertions each time the application starts.
* ``target_timing`` - the expected duration each assert should converge on, in seconds. The default
  is 0.1.
* ``convergence_factor`` - the speed with which the measurements of an assert converges. The timing
  of an assert is low pass filtered, this controls how fast the filter follows. 1.0 means that it
  always uses the new value. 0.0 means that it will never change from its initial value. The default
  is 0.7.


Python Support
--------------

Hesitate is tested with Python 2.7, 3.2, 3.3, 3.4, and PyPy 2.4.


Django Integration
------------------

Hesitate comes pre-packaged with a Django application that integrates with your settings, and
supports Django 1.6 and 1.7.

.. code-block:: python

    INSTALLED_APPS = (
        # Hesitate should be loaded first of all apps!
        'hesitate.wrappers.django',

        # The rest of your apps here
    )

    HESITATE_ENABLED = True  # Optional, defaults to the inverse of DEBUG

    # These parameters reflect the attach_hook parameters and are all optional:
    HESITATE_INITIAL_PROBABILITY = 1.0
    HESITATE_TARGET_TIMING = 0.1
    HESITATE_CONVERGENCE_FACTOR = 0.7


.. _py.test: http://pytest.org