Metadata-Version: 1.1
Name: interruptingcow
Version: 0.7
Summary: A watchdog that interrupts long running code.
Home-page: https://bitbucket.org/evzijst/interruptingcow
Author: Erik van Zijst
Author-email: erik.van.zijst@gmail.com
License: MIT
Description: Interrupting Cow
        ================
        
        Interruptingcow is a generic utility that can relatively gracefully interrupt
        your Python code when it doesn't execute within a specific number of seconds::
        
            from interruptingcow import timeout
        
            try:
                with timeout(5, exception=RuntimeError):
                    # perform a potentially very slow operation
                    pass
            except RuntimeError:
                print "didn't finish within 5 seconds"
        
        Timeouts are specified in seconds (as floats with theoretical microsecond
        precision).
        
        
        Installation
        ------------
        ::
        
            $ pip install interruptingcow
        
        
        Reentrant
        ---------
        
        Interruptingcow is fully reentrant, which means that you can have nested
        timeouts::
        
            from interruptingcow import timeout
        
            class Outer(RuntimeError): pass
        
            class Inner(RuntimeError): pass
        
            try:
                with timeout(20.0, Outer):
                    try:
                        with timeout(1.0, Inner):
                            # some expensive operation
                            try_the_expensive_thing()
                    except Inner:
                        do_the_cheap_thing_instead()
        
            except Outer:
                print 'Program as a whole failed to return in 20 secs'
        
        Nested timeouts allow a large outer timeout to contain smaller timeouts. If the
        inner timeout is larger than the outer timeout, it is treated as a no-op.
        
        
        Function Decorators
        -------------------
        
        Interruptingcow can be used both as inline with-statements, as shown in the
        above examples, as well as function decorator::
        
            from interruptingcow import timeout
        
            @timeout(.5)
            def foo():
                with timeout(.3):
                    # some expensive operation
                    pass
        
        
        Quotas
        ------
        
        You can allocate a quota of time and then share it across multiple invocations
        to ``timeout()``. This is especially useful if you need to use timeouts inside
        a loop::
        
            from interruptingcow import timeout, Quota
        
            quota = Quota(1.0)
            for i in something:
                try:
                    with timeout(quota, RuntimeError):
                        # perform a slow operation
                        pass
                except RuntimeError:
                    # do a cheaper thing instead
        
        Here the first iterations of the loop will be able to perform the expensive
        operation, until the shared quota of 1 second runs out and then the remaining
        iterations will perform the cheaper alternative.
        
        A single quota instance can also be shared across all calls to ``timeout()``
        your application makes (including nested calls), to give place an upper bound
        on the total runtime, regardless of how many calls to ``timeout()`` you have.
        
        Caveats
        -------
        
        Interruptingcow uses ``signal(SIGALRM)`` to let the operating system interrupt
        program execution. This has the following limitations:
        
        1. Python signal handlers only apply to the main thread, so you cannot use this
           from other threads
        2. You must not use this in a program that uses ``SIGALRM`` itself (this
           includes certain profilers)
        
Keywords: debug watchdog timer interrupt
Platform: UNKNOWN
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: System Administrators
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Natural Language :: English
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 2.7
Classifier: Programming Language :: Python :: 3.5
Classifier: Topic :: Software Development :: Debuggers
Classifier: Topic :: System :: Benchmark
Classifier: Topic :: System :: Monitoring
Classifier: Topic :: Utilities
