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`_.
.. _WSGI container: https://twistedmatrix.com/documents/current/web/howto/web-in-60/wsgi.html
Crochet is maintained by Itamar Turner-Trauring.
**Note:** Crochet development is pretty slow these days because mostly it **Just Works**. PyPI shows about 30,000 downloads a month, so existing users seem happy: https://pypistats.org/packages/crochet
You can install Crochet by running::
$ pip install crochet
Downloads are available on `PyPI`_.
Documentation can be found on `Read The Docs`_.
Bugs and feature requests should be filed at the project `Github page`_.
.. _Read the Docs: https://crochet.readthedocs.org/
.. _Github page: https://github.com/itamarst/crochet/
.. _PyPI: https://pypi.python.org/pypi/crochet
API and features
================
Crochet supports Python 3.8, 3.9, 3.10, and 3.11 as well as PyPy3.
Crochet provides the following basic APIs:
* 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 the ability to repeatedly
check if it's done.
Crochet will do the following on your behalf in order to enable these APIs:
* Transparently start Twisted's reactor in a thread it manages.
* Shut down the reactor automatically when the process' main thread finishes.
* Hook 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
==========
2.1.0
^^^^^
* Various internal modernizations and maintenance.
* Dropped Python 3.6 and 3.7 support.
2.0.0
^^^^^
New features:
* It's possible to decorate ``async/await`` Twisted functions with ``@wait_for`` and ``@run_in_reactor``, thanks to Árni Már Jónsson.
* Added type hints, thanks to Merlin Davis.
* Added formal support for Python 3.9.
Removed features:
* Dropped the deprecated APIs ``@wait_for_reactor``, ``@in_reactor``, ``DeferredResult``, the ``wrapped_function`` attribute, and unlimited timeouts on ``EventualResult.wait()``.
* Dropped support for Python 2.7 and 3.5.
1.12.0
^^^^^^
Bug fixes:
* Fix a timeout overflow bug in 32-bit machines.
1.11.0
^^^^^^
New features:
* Added support for Python 3.8 and PyPy 3.
Backwards incompatibility:
* Dropped support for Python 3.4, since latest Twisted doesn't support it.
1.10.0
^^^^^^
New features:
* Added support for Python 3.7. Thanks to Jeremy Cline for the patch.
1.9.0
^^^^^
New features:
* The underlying callable wrapped ``@run_in_reactor`` and ``@wait_for`` is now available via the more standard ``__wrapped__`` attribute.
Backwards incompatibility (in tests):
* This was actually introduced in 1.8.0: ``wrapped_function`` may not always be available on decorated callables.
You should use ``__wrapped__`` instead.
Bug fixes:
* Fixed regression in 1.8.0 where bound method couldn't be wrapped.
Thanks to 2mf for the bug report.
1.8.0
^^^^^
New features:
* Signatures on decorated functions now match the original functions.
Thanks to Mikhail Terekhov for the original patch.
* Documentation improvements, including an API reference.
Bug fixes:
* Switched to EPoll reactor for logging thread.
Anecdotal evidence suggests this fixes some issues on AWS Lambda, but it's not clear why.
Thanks to Rolando Espinoza for the patch.
* It's now possible to call ``@run_in_reactor`` and ``@wait_for`` above a ``@classmethod``.
Thanks to vak for the bug report.
1.7.0
^^^^^
Bug fixes:
* If the Python ``logging.Handler`` throws an exception Crochet no longer goes into a death spiral.
Thanks to Michael Schlenker for the bug report.
Removed features:
* Versions of Twisted < 16.0 are no longer supported (i.e. no longer tested in CI.)
1.6.0
^^^^^
New features:
* Added support for Python 3.6.
1.5.0
^^^^^
New features:
* Added support for Python 3.5.
Removed features:
* Python 2.6, Python 3.3, and versions of Twisted < 15.0 are no longer supported.
1.4.0
^^^^^
New features:
* Added support for Python 3.4.
Documentation:
* Added a section on known issues and workarounds.
Bug fixes:
* Main thread detection (used to determine when Crochet should shutdown) is now less fragile.
This means Crochet now supports more environments, e.g. uWSGI.
Thanks to Ben Picolo for the patch.
1.3.0
^^^^^
Bug fixes:
* It is now possible to call ``EventualResult.wait()`` (or functions
wrapped in ``wait_for``) at import time if another thread holds the
import lock. Thanks to Ken Struys for the patch.
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.
.. _Twisted ticket 6378: http://tm.tl/6738
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.
Raw data
{
"_id": null,
"home_page": "https://github.com/itamarst/crochet",
"name": "crochet",
"maintainer": "Itamar Turner-Trauring",
"docs_url": null,
"requires_python": ">=3.8.0",
"maintainer_email": "itamar@itamarst.org",
"keywords": "twisted threading",
"author": "",
"author_email": "",
"download_url": "https://files.pythonhosted.org/packages/be/38/80218110ea772b52a217fe423786b2a91771466ce3f2284b080950fd72a6/crochet-2.1.1.tar.gz",
"platform": null,
"description": "Crochet: Use Twisted anywhere!\n==============================\n\nCrochet is an MIT-licensed library that makes it easier to use Twisted from\nregular blocking code. Some use cases include:\n\n* Easily use Twisted from a blocking framework like Django or Flask.\n* Write a library that provides a blocking API, but uses Twisted for its\n implementation.\n* Port blocking code to Twisted more easily, by keeping a backwards\n compatibility layer.\n* Allow normal Twisted programs that use threads to interact with Twisted more\n cleanly from their threaded parts. For example, this can be useful when using\n Twisted as a `WSGI container`_.\n\n.. _WSGI container: https://twistedmatrix.com/documents/current/web/howto/web-in-60/wsgi.html\n\nCrochet is maintained by Itamar Turner-Trauring.\n\n **Note:** Crochet development is pretty slow these days because mostly it **Just Works**. PyPI shows about 30,000 downloads a month, so existing users seem happy: https://pypistats.org/packages/crochet\n\nYou can install Crochet by running::\n\n $ pip install crochet\n\nDownloads are available on `PyPI`_.\n\nDocumentation can be found on `Read The Docs`_.\n\nBugs and feature requests should be filed at the project `Github page`_.\n\n.. _Read the Docs: https://crochet.readthedocs.org/\n.. _Github page: https://github.com/itamarst/crochet/\n.. _PyPI: https://pypi.python.org/pypi/crochet\n\n\nAPI and features\n================\n\nCrochet supports Python 3.8, 3.9, 3.10, and 3.11 as well as PyPy3.\n\nCrochet provides the following basic APIs:\n\n* Allow blocking code to call into Twisted and block until results are available\n or a timeout is hit, using the ``crochet.wait_for`` decorator.\n* A lower-level API (``crochet.run_in_reactor``) allows blocking code to run\n code \"in the background\" in the Twisted thread, with the ability to repeatedly\n check if it's done.\n\nCrochet will do the following on your behalf in order to enable these APIs:\n\n* Transparently start Twisted's reactor in a thread it manages.\n* Shut down the reactor automatically when the process' main thread finishes.\n* Hook up Twisted's log system to the Python standard library ``logging``\n framework. Unlike Twisted's built-in ``logging`` bridge, this includes\n support for blocking `Handler` instances.\n\nWhat's New\n==========\n\n2.1.0\n^^^^^\n\n* Various internal modernizations and maintenance.\n* Dropped Python 3.6 and 3.7 support.\n\n2.0.0\n^^^^^\n\nNew features:\n\n* It's possible to decorate ``async/await`` Twisted functions with ``@wait_for`` and ``@run_in_reactor``, thanks to \u00c1rni M\u00e1r J\u00f3nsson.\n* Added type hints, thanks to Merlin Davis.\n* Added formal support for Python 3.9.\n\n\nRemoved features:\n\n* Dropped the deprecated APIs ``@wait_for_reactor``, ``@in_reactor``, ``DeferredResult``, the ``wrapped_function`` attribute, and unlimited timeouts on ``EventualResult.wait()``.\n* Dropped support for Python 2.7 and 3.5.\n\n1.12.0\n^^^^^^\n\nBug fixes:\n\n* Fix a timeout overflow bug in 32-bit machines.\n\n\n1.11.0\n^^^^^^\n\nNew features:\n\n* Added support for Python 3.8 and PyPy 3.\n\nBackwards incompatibility:\n\n* Dropped support for Python 3.4, since latest Twisted doesn't support it.\n\n1.10.0\n^^^^^^\n\nNew features:\n\n* Added support for Python 3.7. Thanks to Jeremy Cline for the patch.\n\n1.9.0\n^^^^^\n\nNew features:\n\n* The underlying callable wrapped ``@run_in_reactor`` and ``@wait_for`` is now available via the more standard ``__wrapped__`` attribute.\n\nBackwards incompatibility (in tests):\n\n* This was actually introduced in 1.8.0: ``wrapped_function`` may not always be available on decorated callables.\n You should use ``__wrapped__`` instead.\n\nBug fixes:\n\n* Fixed regression in 1.8.0 where bound method couldn't be wrapped.\n Thanks to 2mf for the bug report.\n\n1.8.0\n^^^^^\n\nNew features:\n\n* Signatures on decorated functions now match the original functions.\n Thanks to Mikhail Terekhov for the original patch.\n* Documentation improvements, including an API reference.\n\nBug fixes:\n\n* Switched to EPoll reactor for logging thread.\n Anecdotal evidence suggests this fixes some issues on AWS Lambda, but it's not clear why.\n Thanks to Rolando Espinoza for the patch.\n* It's now possible to call ``@run_in_reactor`` and ``@wait_for`` above a ``@classmethod``.\n Thanks to vak for the bug report.\n\n1.7.0\n^^^^^\n\nBug fixes:\n\n* If the Python ``logging.Handler`` throws an exception Crochet no longer goes into a death spiral.\n Thanks to Michael Schlenker for the bug report.\n\nRemoved features:\n\n* Versions of Twisted < 16.0 are no longer supported (i.e. no longer tested in CI.)\n\n1.6.0\n^^^^^\n\nNew features:\n\n* Added support for Python 3.6.\n\n1.5.0\n^^^^^\n\nNew features:\n\n* Added support for Python 3.5.\n\nRemoved features:\n\n* Python 2.6, Python 3.3, and versions of Twisted < 15.0 are no longer supported.\n\n1.4.0\n^^^^^\n\nNew features:\n\n* Added support for Python 3.4.\n\nDocumentation:\n\n* Added a section on known issues and workarounds.\n\nBug fixes:\n\n* Main thread detection (used to determine when Crochet should shutdown) is now less fragile.\n This means Crochet now supports more environments, e.g. uWSGI.\n Thanks to Ben Picolo for the patch.\n\n1.3.0\n^^^^^\n\nBug fixes:\n\n* It is now possible to call ``EventualResult.wait()`` (or functions\n wrapped in ``wait_for``) at import time if another thread holds the\n import lock. Thanks to Ken Struys for the patch.\n\n1.2.0\n^^^^^\nNew features:\n\n* ``crochet.wait_for`` implements the timeout/cancellation pattern documented\n in previous versions of Crochet. ``crochet.wait_for_reactor`` and\n ``EventualResult.wait(timeout=None)`` are now deprecated, since lacking\n timeouts they could potentially block forever.\n* Functions wrapped with ``wait_for`` and ``run_in_reactor`` can now be accessed\n via the ``wrapped_function`` attribute, to ease unit testing of the underlying\n Twisted code.\n\nAPI changes:\n\n* It is no longer possible to call ``EventualResult.wait()`` (or functions\n wrapped with ``wait_for``) at import time, since this can lead to deadlocks\n or prevent other threads from importing. Thanks to Tom Prince for the bug\n report.\n\nBug fixes:\n\n* ``warnings`` are no longer erroneously turned into Twisted log messages.\n* The reactor is now only imported when ``crochet.setup()`` or\n ``crochet.no_setup()`` are called, allowing daemonization if only ``crochet``\n is imported (http://tm.tl/7105). Thanks to Daniel Nephin for the bug report.\n\nDocumentation:\n\n* Improved motivation, added contact info and news to the documentation.\n* Better example of using Crochet from a normal Twisted application.\n\n1.1.0\n^^^^^\nBug fixes:\n\n* ``EventualResult.wait()`` can now be used safely from multiple threads,\n thanks to Gavin Panella for reporting the bug.\n* Fixed reentrancy deadlock in the logging code caused by\n http://bugs.python.org/issue14976, thanks to Rod Morehead for reporting the\n bug.\n* Crochet now installs on Python 3.3 again, thanks to Ben Cordero.\n* Crochet should now work on Windows, thanks to Konstantinos Koukopoulos.\n* Crochet tests can now run without adding its absolute path to PYTHONPATH or\n installing it first.\n\nDocumentation:\n\n* ``EventualResult.original_failure`` is now documented.\n\n1.0.0\n^^^^^\nDocumentation:\n\n* Added section on use cases and alternatives. Thanks to Tobias Oberstein for\n the suggestion.\n\nBug fixes:\n\n* Twisted does not have to be pre-installed to run ``setup.py``, thanks to\n Paul Weaver for bug report and Chris Scutcher for patch.\n* Importing Crochet does not have side-effects (installing reactor event)\n any more.\n* Blocking calls are interrupted earlier in the shutdown process, to reduce\n scope for deadlocks. Thanks to rmorehead for bug report.\n\n0.9.0\n^^^^^\nNew features:\n\n* Expanded and much improved documentation, including a new section with\n design suggestions.\n* New decorator ``@wait_for_reactor`` added, a simpler alternative to\n ``@run_in_reactor``.\n* Refactored ``@run_in_reactor``, making it a bit more responsive.\n* Blocking operations which would otherwise never finish due to reactor having\n stopped (``EventualResult.wait()`` or ``@wait_for_reactor`` decorated call)\n will be interrupted with a ``ReactorStopped`` exception. Thanks to rmorehead\n for the bug report.\n\nBug fixes:\n\n* ``@run_in_reactor`` decorated functions (or rather, their generated wrapper)\n are interrupted by Ctrl-C.\n* On POSIX platforms, a workaround is installed to ensure processes started by\n `reactor.spawnProcess` have their exit noticed. See `Twisted ticket 6378`_\n for more details about the underlying issue.\n\n.. _Twisted ticket 6378: http://tm.tl/6738\n\n0.8.1\n^^^^^\n* ``EventualResult.wait()`` now raises error if called in the reactor thread,\n thanks to David Buchmann.\n* Unittests are now included in the release tarball.\n* Allow Ctrl-C to interrupt ``EventualResult.wait(timeout=None)``.\n\n0.7.0\n^^^^^\n* Improved documentation.\n\n0.6.0\n^^^^^\n* Renamed ``DeferredResult`` to ``EventualResult``, to reduce confusion with\n Twisted's ``Deferred`` class. The old name still works, but is deprecated.\n* Deprecated ``@in_reactor``, replaced with ``@run_in_reactor`` which doesn't\n change the arguments to the wrapped function. The deprecated API still works,\n however.\n* Unhandled exceptions in ``EventualResult`` objects are logged.\n* Added more examples.\n* ``setup.py sdist`` should work now.\n\n0.5.0\n^^^^^\n* Initial release.\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "Use Twisted anywhere!",
"version": "2.1.1",
"project_urls": {
"Homepage": "https://github.com/itamarst/crochet"
},
"split_keywords": [
"twisted",
"threading"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "5c18b3543d7ad6333bdcd1a9397525e85415bbcd1ce055c3917a713373e99a21",
"md5": "4140af7abad09cbdd37fd3531c994684",
"sha256": "87970cbd1b384a8d3b10152565283d76843d56ea7e087ea3239092a64ffaea0e"
},
"downloads": -1,
"filename": "crochet-2.1.1-py3-none-any.whl",
"has_sig": false,
"md5_digest": "4140af7abad09cbdd37fd3531c994684",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.8.0",
"size": 31307,
"upload_time": "2023-07-01T20:55:52",
"upload_time_iso_8601": "2023-07-01T20:55:52.823616Z",
"url": "https://files.pythonhosted.org/packages/5c/18/b3543d7ad6333bdcd1a9397525e85415bbcd1ce055c3917a713373e99a21/crochet-2.1.1-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "be3880218110ea772b52a217fe423786b2a91771466ce3f2284b080950fd72a6",
"md5": "ebd10a867ef3ab576af5b1edd856d9dd",
"sha256": "7ece69de1ce8e63ffc0af8e2331ec4eb898d91ed4271aafa4ccc398523b81cf9"
},
"downloads": -1,
"filename": "crochet-2.1.1.tar.gz",
"has_sig": false,
"md5_digest": "ebd10a867ef3ab576af5b1edd856d9dd",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.8.0",
"size": 63777,
"upload_time": "2023-07-01T20:55:54",
"upload_time_iso_8601": "2023-07-01T20:55:54.260255Z",
"url": "https://files.pythonhosted.org/packages/be/38/80218110ea772b52a217fe423786b2a91771466ce3f2284b080950fd72a6/crochet-2.1.1.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2023-07-01 20:55:54",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "itamarst",
"github_project": "crochet",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"tox": true,
"lcname": "crochet"
}
JSON
