API Reference

crochet.setup()

Initialize the crochet library.

This starts the reactor in a thread, and connect’s Twisted’s logs to Python’s standard library logging module.

This must be called at least once before the library can be used, and can be called multiple times.

crochet.no_setup()

Initialize the crochet library with no side effects.

No reactor will be started, logging is uneffected, etc.. Future calls to setup() will have no effect. This is useful for applications that intend to run Twisted’s reactor themselves, and so do not want libraries using crochet to attempt to start it on their own.

If no_setup() is called after setup(), a RuntimeError is raised.

crochet.run_in_reactor(function)

A decorator that ensures the wrapped function runs in the reactor thread.

When the wrapped function is called, an EventualResult is returned.

crochet.wait_for(timeout)

A decorator factory that ensures the wrapped function runs in the reactor thread.

When the wrapped function is called, its result is returned or its exception raised. Deferreds are handled transparently. Calls will timeout after the given number of seconds (a float), raising a crochet.TimeoutError, and cancelling the Deferred being waited on.

class crochet.EventualResult(deferred, _reactor)

A blocking interface to Deferred results.

This allows you to access results from Twisted operations that may not be available immediately, using the wait() method.

In general you should not create these directly; instead use functions decorated with @run_in_reactor.

cancel()

Try to cancel the operation by cancelling the underlying Deferred.

Cancellation of the operation may or may not happen depending on underlying cancellation support and whether the operation has already finished. In any case, however, the underlying Deferred will be fired.

Multiple calls will have no additional effect.

original_failure()

Return the underlying Failure object, if the result is an error.

If no result is yet available, or the result was not an error, None is returned.

This method is useful if you want to get the original traceback for an error result.

stash()

Store the EventualResult in memory for later retrieval.

Returns a integer uid which can be passed to crochet.retrieve_result() to retrieve the instance later on.

wait(timeout=None)

Return the result, or throw the exception if result is a failure.

It may take an unknown amount of time to return the result, so a timeout option is provided. If the given number of seconds pass with no result, a TimeoutError will be thrown.

If a previous call timed out, additional calls to this function will still wait for a result and return it if available. If a result was returned or raised on one call, additional calls will return/raise the same result.

crochet.retrieve_result(result_id)

Return the given EventualResult, and remove it from the store.

exception crochet.TimeoutError

A timeout has been hit.

exception crochet.ReactorStopped

The reactor has stopped, and therefore no result will ever become available from this EventualResult.