Skip to main content
This is a pre-production deployment of Warehouse. Changes made here affect the production instance of PyPI (
Help us improve Python packaging - Donate today!

A watchdog that interrupts long running code.

Project Description

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

    with timeout(5, exception=RuntimeError):
        # perform a potentially very slow operation
except RuntimeError:
    print "didn't finish within 5 seconds"

Timeouts are specified in seconds (as floats with theoretical microsecond precision).


$ pip install interruptingcow


Interruptingcow is fully reentrant, which means that you can have nested timeouts:

from interruptingcow import timeout

class Outer(RuntimeError): pass

class Inner(RuntimeError): pass

    with timeout(20.0, Outer):
            with timeout(1.0, Inner):
                # some expensive operation
        except Inner:

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

def foo():
    with timeout(.3):
        # some expensive operation


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:
        with timeout(quota, RuntimeError):
            # perform a slow operation
    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.


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)

Release History

This version
History Node


History Node


History Node


History Node


History Node


History Node


History Node


History Node


Download Files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

File Name & Hash SHA256 Hash Help Version File Type Upload Date
(4.9 kB) Copy SHA256 Hash SHA256
Source Jul 29, 2017

Supported By

WebFaction WebFaction Technical Writing Elastic Elastic Search Pingdom Pingdom Monitoring Dyn Dyn DNS Sentry Sentry Error Logging CloudAMQP CloudAMQP RabbitMQ Heroku Heroku PaaS Kabu Creative Kabu Creative UX & Design Fastly Fastly CDN DigiCert DigiCert EV Certificate Rackspace Rackspace Cloud Servers DreamHost DreamHost Log Hosting