crochet 1.2.0

Use Twisted anywhere!

Crochet: Use Twisted Anywhere!

Crochet is an MIT-licensed library that makes it easier to use Twisted from regular blocking code. Some use cases include:

• Easily use Twisted from a blocking framework like Django or Flask.

• Write a library that provides a blocking API, but uses Twisted for its implementation.

• Port blocking code to Twisted more easily, by keeping a backwards compatibility layer.

• Allow normal Twisted programs that use threads to interact with Twisted more cleanly from their threaded parts. For example this can be useful when using Twisted as a WSGI container.

Crochet is maintained by Itamar Turner-Trauring.

Documentation can be found on Read The Docs.

Bugs and feature requests should be filed at the project Github page.

Features

Crochet aims for 100% unit test coverage, and supports Python 2.6, 2.7 and 3.3.

Crochet provides the following general features:

• Allow blocking code to call into Twisted and block until results are available or a timeout is hit, using the crochet.wait_for decorator.

• A lower-level API (crochet.run_in_reactor) allows blocking code to run code “in the background” in the Twisted thread, with ability to repeatedly check if it’s done.

Additionally Crochet can:

• Transparently start Twisted’s reactor in a thread it manages.

• The reactor shuts down automatically when the process’ main thread finishes.

• Hooks up Twisted’s log system to the Python standard library logging framework. Unlike Twisted’s built-in logging bridge, this includes support for blocking Handler instances.

What’s New

1.2.0

New features:

• crochet.wait_for implements the timeout/cancellation pattern documented in previous versions of Crochet. crochet.wait_for_reactor and EventualResult.wait(timeout=None) are now deprecated, since lacking timeouts they could potentially block forever.

• Functions wrapped with wait_for and run_in_reactor can now be accessed via the wrapped_function attribute, to ease unit testing of the underlying Twisted code.

API changes:

• It is no longer possible to call EventualResult.wait() (or functions wrapped with wait_for) at import time, since this can lead to deadlocks or prevent other threads from importing. Thanks to Tom Prince for the bug report.

Bug fixes:

• warnings are no longer erroneously turned into Twisted log messages.

• The reactor is now only imported when crochet.setup() or crochet.no_setup() are called, allowing daemonization if only crochet is imported (http://tm.tl/7105). Thanks to Daniel Nephin for the bug report.

Documentation:

• Improved motivation, added contact info and news to the documentation.

• Better example of using Crochet from a normal Twisted application.

1.1.0

Bug fixes:

• EventualResult.wait() can now be used safely from multiple threads, thanks to Gavin Panella for reporting the bug.

• Fixed reentrancy deadlock in the logging code caused by http://bugs.python.org/issue14976, thanks to Rod Morehead for reporting the bug.

• Crochet now installs on Python 3.3 again, thanks to Ben Cordero.

• Crochet should now work on Windows, thanks to Konstantinos Koukopoulos.

• Crochet tests can now run without adding its absolute path to PYTHONPATH or installing it first.

Documentation:

• EventualResult.original_failure is now documented.

1.0.0

Documentation:

• Added section on use cases and alternatives. Thanks to Tobias Oberstein for the suggestion.

Bug fixes:

• Twisted does not have to be pre-installed to run setup.py, thanks to Paul Weaver for bug report and Chris Scutcher for patch.

• Importing Crochet does not have side-effects (installing reactor event) any more.

• Blocking calls are interrupted earlier in the shutdown process, to reduce scope for deadlocks. Thanks to rmorehead for bug report.

0.9.0

New features:

• Expanded and much improved documentation, including a new section with design suggestions.

• New decorator @wait_for_reactor added, a simpler alternative to @run_in_reactor.

• Refactored @run_in_reactor, making it a bit more responsive.

• Blocking operations which would otherwise never finish due to reactor having stopped (EventualResult.wait() or @wait_for_reactor decorated call) will be interrupted with a ReactorStopped exception. Thanks to rmorehead for the bug report.

Bug fixes:

• @run_in_reactor decorated functions (or rather, their generated wrapper) are interrupted by Ctrl-C.

• On POSIX platforms, a workaround is installed to ensure processes started by reactor.spawnProcess have their exit noticed. See Twisted ticket 6378 for more details about the underlying issue.

0.8.1

• EventualResult.wait() now raises error if called in the reactor thread, thanks to David Buchmann.

• Unittests are now included in the release tarball.

• Allow Ctrl-C to interrupt EventualResult.wait(timeout=None).

0.7.0

• Improved documentation.

0.6.0

• Renamed DeferredResult to EventualResult, to reduce confusion with Twisted’s Deferred class. The old name still works, but is deprecated.

• Deprecated @in_reactor, replaced with @run_in_reactor which doesn’t change the arguments to the wrapped function. The deprecated API still works, however.

• Unhandled exceptions in EventualResult objects are logged.

• Added more examples.

• setup.py sdist should work now.

0.5.0

• Initial release.