stopit 1.1.0

stopit.async_raise

A function that raises an arbitrary exception in another thread

async_raise(tid, exception)

• tid is the thread identifier as provided by the ident attribute of a thread object. See the documentation of the threading module for further information.

• exception is the exception class or object to raise in the thread.

stopit.ThreadingTimeout

A context manager that “kills” its inner block execution that exceeds the provided time.

ThreadingTimeout(seconds, swallow_exc=True)

• seconds is the number of seconds allowed to the execution of the context managed block.

• swallow_exc : if False, the possible stopit.TimeoutException will be re-raised when quitting the context managed block. Attention: a True value does not swallow other potential exceptions.

Methods and attributes

of a stopit.ThreadingTimeout context manager.

A typical usage:

import stopit
# ...
with stopit.ThreadingTimeout(10) as to_ctx_mgr:
    assert to_ctx_mgr.state == to_ctx_mgr.EXECUTING
    # Something potentially very long but which
    # ...

# OK, let's check what happened
if to_ctx_mrg.state == to_ctx_mrg.EXECUTED:
    # All's fine, everything was executed within 10 seconds
elif to_ctx_mrg.state == to_ctx_mrg.EXECUTING:
    # Hmm, that's not possible outside the block
elif to_ctx_mrg.state == to_ctx_mrg.TIMED_OUT:
    # Eeek the 10 seconds timeout occurred while executing the block
elif to_ctx_mrg.state == to_ctx_mrg.INTERRUPTED:
    # Oh you raised specifically the TimeoutException in the block
elif to_ctx_mrg.state == to_ctx_mrg.CANCELED:
    # Oh you called to_ctx_mgr.cancel() method within the block but it
    # executed till the end
else:
    # That's not possible

Notice that the context manager object may be considered as a boolean indicating (if True) that the block executed normally:

if to_ctx_mgr:
    # Yes, the code under timeout control completed
    # Objects it created or changed may be considered consistent

stopit.threading_timeoutable

A decorator that kills the function or method it decorates, if it does not return within a given time frame.

stopit.threading_timeoutable([default [, timeout_param]])

• default is the value to be returned by the decorated function or method of when its execution timed out, to notify the caller code that the function did not complete within the assigned time frame.

  If this parameter is not provided, the decorated function or method will return a None value when its execution times out.

  @stopit.threading_timeoutable(default='not finished')
  def infinite_loop():
      # As its name says...
  
  result = infinite_loop(timeout=5)
  assert result == 'not finished'

• timeout_param: The function or method you have decorated may require a timeout named parameter for whatever reason. This empowers you to change the name of the timeout parameter in the decorated function signature to whatever suits, and prevent a potential naming conflict.

  @stopit.threading_timeoutable(timeout_param='my_timeout')
  def some_slow_function(a, b, timeout='whatever'):
      # As its name says...
  
  result = some_slow_function(1, 2, timeout="something", my_timeout=2)

About the decorated function

or method…

As you noticed above, you just need to add the timeout parameter when calling the function or method. Or whatever other name for this you chose with the timeout_param of the decorator. When calling the real inner function or method, this parameter is removed.

Swallowing Timeout exceptions

We check that the fast functions return as outside our context manager:

>>> with Timeout(5.0) as timeout_ctx:
...     result = fast_func()
>>> result
0
>>> timeout_ctx.state == timeout_ctx.EXECUTED
True

We check that slow functions are interrupted:

>>> start_time = time.time()
>>> with Timeout(2.0) as timeout_ctx:
...     variable_duration_func(5.0)
>>> time.time() - start_time < 2.2
True
>>> timeout_ctx.state == timeout_ctx.TIMED_OUT
True

Other exceptions are propagated and must be treated as usual:

>>> try:
...     with Timeout(5.0) as timeout_ctx:
...         result = func_with_exception()
... except LookupError:
...     result = 'exception_seen'
>>> timeout_ctx.state == timeout_ctx.EXECUTING
True
>>> result
'exception_seen'

Propagating TimeoutException

We can choose to propagate the TimeoutException too. Potential exceptions have to be handled:

>>> result = None
>>> start_time = time.time()
>>> try:
...     with Timeout(2.0, swallow_exc=False) as timeout_ctx:
...         variable_duration_func(5.0)
... except TimeoutException:
...     result = 'exception_seen'
>>> time.time() - start_time < 2.2
True
>>> result
'exception_seen'
>>> timeout_ctx.state == timeout_ctx.TIMED_OUT
True

Other exceptions must be handled too:

>>> result = None
>>> start_time = time.time()
>>> try:
...     with Timeout(2.0, swallow_exc=False) as timeout_ctx:
...         func_with_exception()
... except Exception:
...     result = 'exception_seen'
>>> time.time() - start_time < 0.1
True
>>> result
'exception_seen'
>>> timeout_ctx.state == timeout_ctx.EXECUTING
True