``terminable_thread``
=====================
``terminable_thread`` provides a subclass of ``threading.Thread``,
adding the facility to raise exceptions
in the context of the given thread.
This facility is incorporated in the ``terminable_thread.Thread`` methods
``raise_exc``, which raises an arbitrary exception,
and ``terminate``, which raises SystemExit.
This is not done in an entirely robust manner,
and there may be unreported issues with it.
It uses the unexposed ``PyThreadState_SetAsyncExc`` function (via ``ctypes``)
to raise an exception for the given thread.
Usage
-----
Check the module doctest for a simple usage example.
History
-------
The code used in this module is taken most directly from Tomer Filiba's
`thread2 recipe`_.
Similar code has been floating around the net
for some time now in various incarnations;
however, the code on Tomer's page seems to be the most complete.
His page references a post by Antoon Pardon, previously available at
`<http://mail.python.org/pipermail/python-list/2005-December/316143.html>`_,
as an inspiration.
Tomer has indicated that the code on his page is in the public domain.
.. _thread2 recipe: http://sebulba.wikispaces.com/recipe+thread2
Issues
------
The following issues are mentioned on `the recipe page`_:
- The exception will be raised only when executing python bytecode.
If your thread calls a native/built-in blocking function,
the exception will be raised only when execution returns to the python code.
- There is also an issue
if the built-in function internally calls PyErr\_Clear(),
which would effectively cancel your pending exception.
You can try to raise it again.
- Only exception **types** can be raised safely.
Exception instances are likely to cause unexpected behavior,
and are thus restricted.
- For example:
t1.raise\_exc(TypeError) and not t1.raise\_exc(TypeError("blah")).
- IMHO it's a bug, and I reported it as one. For more info,
`<http://mail.python.org/pipermail/python-dev/2006-August/068158.html>`_
- I asked to expose this function in the built-in thread module,
but since ctypes has become a standard library (as of 2.5),
and this feature is not likely to be implementation-agnostic,
it may be kept unexposed.
In addition to these issues,
or rather as an elaboration of the first one,
I've noticed that catching of exceptions does not function as expected.
Specifically:
- If the thread wraps some functions with a try/except clause,
the except may not catch an interrupt exception.
This will happen, for instance, with a ``time.sleep`` call.
For an example of this,
see the method ``FetcherTester.test_incorrect_fission``
in the test suite for the `pqueue\_fetcher`_ module.
I guess I'll port that test into this module at some point.
.. _the recipe page: http://sebulba.wikispaces.com/recipe+thread2
.. _pqueue\_fetcher: http://github.com/intuited/pqueue_fetcher
Distribution
------------
``terminable_thread`` is available from the `github repo`_ or from `PyPI`_.
.. _github repo: http://github.com/intuited/terminable_thread
.. _PyPI: http://pypi.python.org/pypi/terminable_thread
License
-------
As mentioned above,
Tomer has indicated that the code on `his site`_ is public domain.
I'm not entirely sure what that means legally, since
- the term "public domain" is often used informally,
to just mean that no license has been applied.
- the definition of "public domain", when used formally,
is dependent on the laws of a particular region.
So it's a bit complicated and vague,
but he did say that I could do whatever I wanted with it,
so I've chosen to prevent such ambiguities in the future
by licensing this derivation under the `WTFPL`_.
The license terms are given in the file ``COPYING``.
.. _his site: `the recipe page`_
.. _WTFPL: http://sam.zoy.org/wtfpl/
(Lack of) Warranty
------------------
As mentioned at the top,
I myself am not entirely convinced of the reliability of this code.
I might get around to writing a more thorough test suite at some point.
Please bear that, as well as the following Official Disclaimer,
in mind when (considering) using it:
::
This program is free software.
It comes without any warranty, to the extent permitted by applicable law.
You can redistribute it and/or modify it under the terms of the
Do What The Fuck You Want To Public License, Version 2,
as published by Sam Hocevar.
See http://sam.zoy.org/wtfpl/COPYING for more details.
Raw data
{
"_id": null,
"home_page": "http://github.com/intuited/terminable_thread",
"name": "terminable_thread",
"maintainer": null,
"docs_url": null,
"requires_python": null,
"maintainer_email": null,
"keywords": "threading,multithreading",
"author": "Ted Tibbetts",
"author_email": "intuited@gmail.com",
"download_url": "https://files.pythonhosted.org/packages/10/b4/9530368ac75a9023836514a305e08853b57f859c01b5fcf1aa9f7971d460/terminable_thread-0.7.1.tar.gz",
"platform": "UNKNOWN",
"description": "``terminable_thread``\n=====================\n\n``terminable_thread`` provides a subclass of ``threading.Thread``,\nadding the facility to raise exceptions\nin the context of the given thread.\n\nThis facility is incorporated in the ``terminable_thread.Thread`` methods\n``raise_exc``, which raises an arbitrary exception,\nand ``terminate``, which raises SystemExit.\n\nThis is not done in an entirely robust manner,\nand there may be unreported issues with it.\n\nIt uses the unexposed ``PyThreadState_SetAsyncExc`` function (via ``ctypes``)\nto raise an exception for the given thread.\n\n\nUsage\n-----\n\nCheck the module doctest for a simple usage example.\n\n\nHistory\n-------\n\nThe code used in this module is taken most directly from Tomer Filiba's\n`thread2 recipe`_.\n\nSimilar code has been floating around the net\nfor some time now in various incarnations;\nhowever, the code on Tomer's page seems to be the most complete.\n\nHis page references a post by Antoon Pardon, previously available at\n`<http://mail.python.org/pipermail/python-list/2005-December/316143.html>`_,\nas an inspiration.\n\nTomer has indicated that the code on his page is in the public domain.\n\n.. _thread2 recipe: http://sebulba.wikispaces.com/recipe+thread2\n\n\nIssues\n------\n\nThe following issues are mentioned on `the recipe page`_:\n\n - The exception will be raised only when executing python bytecode.\n If your thread calls a native/built-in blocking function,\n the exception will be raised only when execution returns to the python code.\n \n - There is also an issue \n if the built-in function internally calls\u00a0PyErr\\_Clear(),\n which would effectively cancel your pending exception.\n You can try to raise it again.\n\n - Only exception\u00a0**types**\u00a0can be raised safely.\n Exception instances are likely to cause unexpected behavior,\n and are thus restricted.\n \n - For example:\n t1.raise\\_exc(TypeError)\u00a0and not\u00a0t1.raise\\_exc(TypeError(\"blah\")).\n - IMHO it's a bug, and I reported it as one. For more info,\n `<http://mail.python.org/pipermail/python-dev/2006-August/068158.html>`_\n\n - I asked to expose this function in the built-in\u00a0thread\u00a0module,\n but since\u00a0ctypes\u00a0has become a standard library (as of 2.5),\n and this feature is not likely to be implementation-agnostic,\n it may be kept unexposed.\n\nIn addition to these issues,\nor rather as an elaboration of the first one,\nI've noticed that catching of exceptions does not function as expected.\n\nSpecifically:\n\n- If the thread wraps some functions with a try/except clause,\n the except may not catch an interrupt exception.\n This will happen, for instance, with a ``time.sleep`` call.\n\n For an example of this,\n see the method ``FetcherTester.test_incorrect_fission``\n in the test suite for the `pqueue\\_fetcher`_ module.\n\n I guess I'll port that test into this module at some point.\n\n.. _the recipe page: http://sebulba.wikispaces.com/recipe+thread2\n.. _pqueue\\_fetcher: http://github.com/intuited/pqueue_fetcher\n\nDistribution\n------------\n\n``terminable_thread`` is available from the `github repo`_ or from `PyPI`_.\n\n.. _github repo: http://github.com/intuited/terminable_thread\n.. _PyPI: http://pypi.python.org/pypi/terminable_thread\n\n\nLicense\n-------\n\nAs mentioned above,\nTomer has indicated that the code on `his site`_ is public domain.\n\nI'm not entirely sure what that means legally, since\n\n- the term \"public domain\" is often used informally,\n to just mean that no license has been applied.\n- the definition of \"public domain\", when used formally,\n is dependent on the laws of a particular region.\n\nSo it's a bit complicated and vague,\nbut he did say that I could do whatever I wanted with it,\nso I've chosen to prevent such ambiguities in the future\nby licensing this derivation under the `WTFPL`_.\n\nThe license terms are given in the file ``COPYING``.\n\n.. _his site: `the recipe page`_\n.. _WTFPL: http://sam.zoy.org/wtfpl/\n\n\n(Lack of) Warranty\n------------------\n\nAs mentioned at the top,\nI myself am not entirely convinced of the reliability of this code.\n\nI might get around to writing a more thorough test suite at some point.\n\nPlease bear that, as well as the following Official Disclaimer,\nin mind when (considering) using it:\n\n::\n\n This program is free software.\n It comes without any warranty, to the extent permitted by applicable law.\n You can redistribute it and/or modify it under the terms of the\n Do What The Fuck You Want To Public License, Version 2,\n as published by Sam Hocevar.\n See http://sam.zoy.org/wtfpl/COPYING for more details.",
"bugtrack_url": null,
"license": "http://sam.zoy.org/wtfpl/",
"summary": "Provides a subclass of Thread with facilities to raise an exception in the thread or terminate the thread from another thread.",
"version": "0.7.1",
"project_urls": {
"Download": "UNKNOWN",
"Homepage": "http://github.com/intuited/terminable_thread"
},
"split_keywords": [
"threading",
"multithreading"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "10b49530368ac75a9023836514a305e08853b57f859c01b5fcf1aa9f7971d460",
"md5": "f4f052ea5c1efa98889f0fd10335ae5d",
"sha256": "c07d98a8230568757cffd13c6315409db45f6f479c4e3640df84b2225db10b27"
},
"downloads": -1,
"filename": "terminable_thread-0.7.1.tar.gz",
"has_sig": false,
"md5_digest": "f4f052ea5c1efa98889f0fd10335ae5d",
"packagetype": "sdist",
"python_version": "source",
"requires_python": null,
"size": 5247,
"upload_time": "2010-09-22T00:22:42",
"upload_time_iso_8601": "2010-09-22T00:22:42.986534Z",
"url": "https://files.pythonhosted.org/packages/10/b4/9530368ac75a9023836514a305e08853b57f859c01b5fcf1aa9f7971d460/terminable_thread-0.7.1.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2010-09-22 00:22:42",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "intuited",
"github_project": "terminable_thread",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"lcname": "terminable_thread"
}
JSON
