{ "info": { "author": "Gilles Lenfant", "author_email": "gilles.lenfant@gmail.com", "bugtrack_url": null, "classifiers": [ "Development Status :: 5 - Production/Stable", "Intended Audience :: Developers", "License :: OSI Approved :: MIT License", "Operating System :: OS Independent", "Programming Language :: Python", "Programming Language :: Python :: 2.6", "Programming Language :: Python :: 2.7", "Programming Language :: Python :: 3.3", "Programming Language :: Python :: 3.4", "Programming Language :: Python :: 3.5", "Programming Language :: Python :: 3.6", "Programming Language :: Python :: Implementation :: CPython", "Topic :: Utilities" ], "description": "======\nstopit\n======\n\nRaise asynchronous exceptions in other threads, control the timeout of\nblocks or callables with two context managers and two decorators.\n\n.. attention:: API Changes\n\n Users of 1.0.0 should upgrade their source code:\n\n - ``stopit.Timeout`` is renamed ``stopit.ThreadingTimeout``\n - ``stopit.timeoutable`` is renamed ``stopit.threading_timeoutable``\n\n Explications follow below...\n\n.. contents::\n\nOverview\n========\n\nThis module provides:\n\n- a function that raises an exception in another thread, including the main\n thread.\n\n- two context managers that may stop its inner block activity on timeout.\n\n- two decorators that may stop its decorated callables on timeout.\n\nDeveloped and tested with CPython 2.6, 2.7, 3.3 and 3.4 on MacOSX. Should work\non any OS (xBSD, Linux, Windows) except when explicitly mentioned.\n\n.. note::\n\n Signal based timeout controls, namely ``SignalTimeout`` context manager and\n ``signal_timeoutable`` decorator won't work in Windows that has no support\n for ``signal.SIGALRM``. Any help to work around this is welcome.\n\nInstallation\n============\n\nUsing ``stopit`` in your application\n------------------------------------\n\nBoth work identically:\n\n.. code:: bash\n\n easy_install stopit\n pip install stopit\n\nDeveloping ``stopit``\n---------------------\n\n.. code:: bash\n\n # You should prefer forking if you have a Github account\n git clone https://github.com/glenfant/stopit.git\n cd stopit\n python setup.py develop\n\n # Does it work for you ?\n python setup.py test\n\nPublic API\n==========\n\nException\n---------\n\n``stopit.TimeoutException``\n...........................\n\nA ``stopit.TimeoutException`` may be raised in a timeout context manager\ncontrolled block.\n\nThis exception may be propagated in your application at the end of execution\nof the context manager controlled block, see the ``swallow_ex`` parameter of\nthe context managers.\n\nNote that the ``stopit.TimeoutException`` is always swallowed after the\nexecution of functions decorated with ``xxx_timeoutable(...)``. Anyway, you\nmay catch this exception **within** the decorated function.\n\nThreading based resources\n-------------------------\n\n.. warning::\n\n Threading based resources will only work with CPython implementations\n since we use CPython specific low level API. This excludes Iron Python,\n Jython, Pypy, ...\n\n Will not stop the execution of blocking Python atomic instructions that\n acquire the GIL. In example, if the destination thread is actually\n executing a ``time.sleep(20)``, the asynchronous exception is effective\n **after** its execution.\n\n``stopit.async_raise``\n......................\n\nA function that raises an arbitrary exception in another thread\n\n``async_raise(tid, exception)``\n\n- ``tid`` is the thread identifier as provided by the ``ident`` attribute of a\n thread object. See the documentation of the ``threading`` module for further\n information.\n\n- ``exception`` is the exception class or object to raise in the thread.\n\n``stopit.ThreadingTimeout``\n...........................\n\nA context manager that \"kills\" its inner block execution that exceeds the\nprovided time.\n\n``ThreadingTimeout(seconds, swallow_exc=True)``\n\n- ``seconds`` is the number of seconds allowed to the execution of the context\n managed block.\n\n- ``swallow_exc`` : if ``False``, the possible ``stopit.TimeoutException`` will\n be re-raised when quitting the context managed block. **Attention**: a\n ``True`` value does not swallow other potential exceptions.\n\n**Methods and attributes**\n\nof a ``stopit.ThreadingTimeout`` context manager.\n\n.. list-table::\n :header-rows: 1\n\n * - Method / Attribute\n - Description\n\n * - ``.cancel()``\n - Cancels the timeout control. This method is intended for use within the\n block that's under timeout control, specifically to cancel the timeout\n control. Means that all code executed after this call may be executed\n till the end.\n\n * - ``.state``\n - This attribute indicated the actual status of the timeout control. It\n may take the value of the ``EXECUTED``, ``EXECUTING``, ``TIMED_OUT``,\n ``INTERRUPTED`` or ``CANCELED`` attributes. See below.\n\n * - ``.EXECUTING``\n - The timeout control is under execution. We are typically executing\n within the code under control of the context manager.\n\n * - ``.EXECUTED``\n - Good news: the code under timeout control completed normally within the\n assigned time frame.\n\n * - ``.TIMED_OUT``\n - Bad news: the code under timeout control has been sleeping too long.\n The objects supposed to be created or changed within the timeout\n controlled block should be considered as non existing or corrupted.\n Don't play with them otherwise informed.\n\n * - ``.INTERRUPTED``\n - The code under timeout control may itself raise explicit\n ``stopit.TimeoutException`` for any application logic reason that may\n occur. This intentional exit can be spotted from outside the timeout\n controlled block with this state value.\n\n * - ``.CANCELED``\n - The timeout control has been intentionally canceled and the code\n running under timeout control did complete normally. But perhaps after\n the assigned time frame.\n\n\nA typical usage:\n\n.. code:: python\n\n import stopit\n # ...\n with stopit.ThreadingTimeout(10) as to_ctx_mgr:\n assert to_ctx_mgr.state == to_ctx_mgr.EXECUTING\n # Something potentially very long but which\n # ...\n\n # OK, let's check what happened\n if to_ctx_mgr.state == to_ctx_mgr.EXECUTED:\n # All's fine, everything was executed within 10 seconds\n elif to_ctx_mgr.state == to_ctx_mgr.EXECUTING:\n # Hmm, that's not possible outside the block\n elif to_ctx_mgr.state == to_ctx_mgr.TIMED_OUT:\n # Eeek the 10 seconds timeout occurred while executing the block\n elif to_ctx_mgr.state == to_ctx_mgr.INTERRUPTED:\n # Oh you raised specifically the TimeoutException in the block\n elif to_ctx_mgr.state == to_ctx_mgr.CANCELED:\n # Oh you called to_ctx_mgr.cancel() method within the block but it\n # executed till the end\n else:\n # That's not possible\n\nNotice that the context manager object may be considered as a boolean\nindicating (if ``True``) that the block executed normally:\n\n.. code:: python\n\n if to_ctx_mgr:\n # Yes, the code under timeout control completed\n # Objects it created or changed may be considered consistent\n\n``stopit.threading_timeoutable``\n................................\n\nA decorator that kills the function or method it decorates, if it does not\nreturn within a given time frame.\n\n``stopit.threading_timeoutable([default [, timeout_param]])``\n\n- ``default`` is the value to be returned by the decorated function or method of\n when its execution timed out, to notify the caller code that the function\n did not complete within the assigned time frame.\n\n If this parameter is not provided, the decorated function or method will\n return a ``None`` value when its execution times out.\n\n .. code:: python\n\n @stopit.threading_timeoutable(default='not finished')\n def infinite_loop():\n # As its name says...\n\n result = infinite_loop(timeout=5)\n assert result == 'not finished'\n\n- ``timeout_param``: The function or method you have decorated may require a\n ``timeout`` named parameter for whatever reason. This empowers you to change\n the name of the ``timeout`` parameter in the decorated function signature to\n whatever suits, and prevent a potential naming conflict.\n\n .. code:: python\n\n @stopit.threading_timeoutable(timeout_param='my_timeout')\n def some_slow_function(a, b, timeout='whatever'):\n # As its name says...\n\n result = some_slow_function(1, 2, timeout=\"something\", my_timeout=2)\n\n\nAbout the decorated function\n............................\n\nor method...\n\nAs you noticed above, you just need to add the ``timeout`` parameter when\ncalling the function or method. Or whatever other name for this you chose with\nthe ``timeout_param`` of the decorator. When calling the real inner function\nor method, this parameter is removed.\n\n\nSignaling based resources\n-------------------------\n\n.. warning::\n\n Using signaling based resources will **not** work under Windows or any OS\n that's not based on Unix.\n\n``stopit.SignalTimeout`` and ``stopit.signal_timeoutable`` have exactly the\nsame API as their respective threading based resources, namely\n`stopit.ThreadingTimeout`_ and `stopit.threading_timeoutable`_.\n\nSee the `comparison chart`_ that warns on the more or less subtle differences\nbetween the `Threading based resources`_ and the `Signaling based resources`_.\n\nLogging\n-------\n\nThe ``stopit`` named logger emits a warning each time a block of code\nexecution exceeds the associated timeout. To turn logging off, just:\n\n.. code:: python\n\n import logging\n stopit_logger = logging.getLogger('stopit')\n stopit_logger.seLevel(logging.ERROR)\n\n.. _comparison chart:\n\nComparing thread based and signal based timeout control\n-------------------------------------------------------\n\n.. list-table::\n :header-rows: 1\n\n * - Feature\n - Threading based resources\n - Signaling based resources\n\n * - GIL\n - Can't interrupt a long Python atomic instruction. e.g. if\n ``time.sleep(20.0)`` is actually executing, the timeout will take\n effect at the end of the execution of this line.\n - Don't care of it\n\n * - Thread safety\n - **Yes** : Thread safe as long as each thread uses its own ``ThreadingTimeout``\n context manager or ``threading_timeoutable`` decorator.\n - **Not** thread safe. Could yield unpredictable results in a\n multithreads application.\n\n * - Nestable context managers\n - **Yes** : you can nest threading based context managers\n - **No** : never nest a signaling based context manager in another one.\n The innermost context manager will automatically cancel the timeout\n control of outer ones.\n\n * - Accuracy\n - Any positive floating value is accepted as timeout value. The accuracy\n depends on the GIL interval checking of your platform. See the doc on\n ``sys.getcheckinterval`` and ``sys.setcheckinterval`` for your Python\n version.\n - Due to the use of ``signal.SIGALRM``, we need provide an integer number\n of seconds. So a timeout of ``0.6`` seconds will ve automatically\n converted into a timeout of zero second!\n\n * - Supported platforms\n - Any CPython 2.6, 2.7 or 3.3 on any OS with threading support.\n - Any Python 2.6, 2.7 or 3.3 with ``signal.SIGALRM`` support. This\n excludes Windows boxes\n\nKnown issues\n============\n\nTimeout accuracy\n----------------\n\n**Important**: the way CPython supports threading and asynchronous features has\nimpacts on the accuracy of the timeout. In other words, if you assign a 2.0\nseconds timeout to a context managed block or a decorated callable, the\neffective code block / callable execution interruption may occur some\nfractions of seconds after this assigned timeout.\n\nFor more background about this issue - that cannot be fixed - please read\nPython gurus thoughts about Python threading, the GIL and context switching\nlike these ones:\n\n- http://pymotw.com/2/threading/\n- https://wiki.python.org/moin/GlobalInterpreterLock\n\nThis is the reason why I am more \"tolerant\" on timeout accuracy in the tests\nyou can read thereafter than I should be for a critical real-time application\n(that's not in the scope of Python).\n\nIt is anyway possible to improve this accuracy at the expense of the global\nperformances decreasing the check interval which defaults to 100. See:\n\n- https://docs.python.org/2.7/library/sys.html#sys.getcheckinterval\n- https://docs.python.org/2.7/library/sys.html#sys.getcheckinterval\n\nIf this is a real issue for users (want a precise timeout and not an\napproximative one), a future release will add the optional ``check_interval``\nparameter to the context managers and decorators. This parameter will enable\nto lower temporarily the threads switching check interval, having a more\naccurate timeout at the expense of the overall performances while the context\nmanaged block or decorated functions are executing.\n\n``gevent`` support\n------------------\n\nThreading timeout control as mentioned in `Threading based resources`_ does not work as expected\nwhen used in the context of a gevent worker.\n\nSee the discussion in `Issue 13 `_ for more details.\n\nTests and demos\n===============\n\n.. code:: pycon\n\n >>> import threading\n >>> from stopit import async_raise, TimeoutException\n\nIn a real application, you should either use threading based timeout resources:\n\n.. code:: pycon\n\n >>> from stopit import ThreadingTimeout as Timeout, threading_timeoutable as timeoutable #doctest: +SKIP\n\nOr the POSIX signal based resources:\n\n.. code:: pycon\n\n >>> from stopit import SignalTimeout as Timeout, signal_timeoutable as timeoutable #doctest: +SKIP\n\nLet's define some utilities:\n\n.. code:: pycon\n\n >>> import time\n >>> def fast_func():\n ... return 0\n >>> def variable_duration_func(duration):\n ... t0 = time.time()\n ... while True:\n ... dummy = 0\n ... if time.time() - t0 > duration:\n ... break\n >>> exc_traces = []\n >>> def variable_duration_func_handling_exc(duration, exc_traces):\n ... try:\n ... t0 = time.time()\n ... while True:\n ... dummy = 0\n ... if time.time() - t0 > duration:\n ... break\n ... except Exception as exc:\n ... exc_traces.append(exc)\n >>> def func_with_exception():\n ... raise LookupError()\n\n``async_raise`` function raises an exception in another thread\n--------------------------------------------------------------\n\nTesting ``async_raise()`` with a thread of 5 seconds:\n\n.. code:: pycon\n\n >>> five_seconds_threads = threading.Thread(\n ... target=variable_duration_func_handling_exc, args=(5.0, exc_traces))\n >>> start_time = time.time()\n >>> five_seconds_threads.start()\n >>> thread_ident = five_seconds_threads.ident\n >>> five_seconds_threads.is_alive()\n True\n\nWe raise a LookupError in that thread:\n\n.. code:: pycon\n\n >>> async_raise(thread_ident, LookupError)\n\nOkay but we must wait few milliseconds the thread death since the exception is\nasynchronous:\n\n.. code:: pycon\n\n >>> while five_seconds_threads.is_alive():\n ... pass\n\nAnd we can notice that we stopped the thread before it stopped by itself:\n\n.. code:: pycon\n\n >>> time.time() - start_time < 0.5\n True\n >>> len(exc_traces)\n 1\n >>> exc_traces[-1].__class__.__name__\n 'LookupError'\n\n``Timeout`` context manager\n---------------------------\n\nThe context manager stops the execution of its inner block after a given time.\nYou may manage the way the timeout occurs using a ``try: ... except: ...``\nconstruct or by inspecting the context manager ``state`` attribute after the\nblock.\n\nSwallowing Timeout exceptions\n.............................\n\nWe check that the fast functions return as outside our context manager:\n\n.. code:: pycon\n\n >>> with Timeout(5.0) as timeout_ctx:\n ... result = fast_func()\n >>> result\n 0\n >>> timeout_ctx.state == timeout_ctx.EXECUTED\n True\n\nAnd the context manager is considered as ``True`` (the block executed its last\nline):\n\n.. code:: pycon\n\n >>> bool(timeout_ctx)\n True\n\nWe check that slow functions are interrupted:\n\n.. code:: pycon\n\n >>> start_time = time.time()\n >>> with Timeout(2.0) as timeout_ctx:\n ... variable_duration_func(5.0)\n >>> time.time() - start_time < 2.2\n True\n >>> timeout_ctx.state == timeout_ctx.TIMED_OUT\n True\n\nAnd the context manager is considered as ``False`` since the block did timeout.\n\n.. code:: pycon\n\n >>> bool(timeout_ctx)\n False\n\nOther exceptions are propagated and must be treated as usual:\n\n.. code:: pycon\n\n >>> try:\n ... with Timeout(5.0) as timeout_ctx:\n ... result = func_with_exception()\n ... except LookupError:\n ... result = 'exception_seen'\n >>> timeout_ctx.state == timeout_ctx.EXECUTING\n True\n >>> result\n 'exception_seen'\n\nPropagating ``TimeoutException``\n................................\n\nWe can choose to propagate the ``TimeoutException`` too. Potential exceptions\nhave to be handled:\n\n.. code:: pycon\n\n >>> result = None\n >>> start_time = time.time()\n >>> try:\n ... with Timeout(2.0, swallow_exc=False) as timeout_ctx:\n ... variable_duration_func(5.0)\n ... except TimeoutException:\n ... result = 'exception_seen'\n >>> time.time() - start_time < 2.2\n True\n >>> result\n 'exception_seen'\n >>> timeout_ctx.state == timeout_ctx.TIMED_OUT\n True\n\nOther exceptions must be handled too:\n\n.. code:: pycon\n\n >>> result = None\n >>> start_time = time.time()\n >>> try:\n ... with Timeout(2.0, swallow_exc=False) as timeout_ctx:\n ... func_with_exception()\n ... except Exception:\n ... result = 'exception_seen'\n >>> time.time() - start_time < 0.1\n True\n >>> result\n 'exception_seen'\n >>> timeout_ctx.state == timeout_ctx.EXECUTING\n True\n\n``timeoutable`` callable decorator\n----------------------------------\n\nThis decorator stops the execution of any callable that should not last a\ncertain amount of time.\n\nYou may use a decorated callable without timeout control if you don't provide\nthe ``timeout`` optional argument:\n\n.. code:: pycon\n\n >>> @timeoutable()\n ... def fast_double(value):\n ... return value * 2\n >>> fast_double(3)\n 6\n\nYou may specify that timeout with the ``timeout`` optional argument.\nInterrupted callables return None:\n\n.. code:: pycon\n\n >>> @timeoutable()\n ... def infinite():\n ... while True:\n ... pass\n ... return 'whatever'\n >>> infinite(timeout=1) is None\n True\n\nOr any other value provided to the ``timeoutable`` decorator parameter:\n\n.. code:: pycon\n\n >>> @timeoutable('unexpected')\n ... def infinite():\n ... while True:\n ... pass\n ... return 'whatever'\n >>> infinite(timeout=1)\n 'unexpected'\n\nIf the ``timeout`` parameter name may clash with your callable signature, you\nmay change it using ``timeout_param``:\n\n.. code:: pycon\n\n >>> @timeoutable('unexpected', timeout_param='my_timeout')\n ... def infinite():\n ... while True:\n ... pass\n ... return 'whatever'\n >>> infinite(my_timeout=1)\n 'unexpected'\n\nIt works on instance methods too:\n\n.. code:: pycon\n\n >>> class Anything(object):\n ... @timeoutable('unexpected')\n ... def infinite(self, value):\n ... assert type(value) is int\n ... while True:\n ... pass\n >>> obj = Anything()\n >>> obj.infinite(2, timeout=1)\n 'unexpected'\n\nLinks\n=====\n\nSource code (clone, fork, ...)\n https://github.com/glenfant/stopit\n\nIssues tracker\n https://github.com/glenfant/stopit/issues\n\nPyPI\n https://pypi.python.org/pypi/stopit\n\nCredits\n=======\n\n- This is a NIH package which is mainly a theft of `Gabriel Ahtune's recipe\n `_ with\n tests, minor improvements and refactorings, documentation and setuptools\n awareness I made since I'm somehow tired to copy/paste this recipe among\n projects that need timeout control.\n\n- `Gilles Lenfant `_: package creator and\n maintainer.\n\nLicense\n=======\n\nThis software is open source delivered under the terms of the MIT license. See the ``LICENSE`` file of this repository.\n\nChanges log\n===========\n\n1.1.2 - 2018-02-09\n------------------\n\n* Changed license to MIT\n* Tested with Python 3.5 and 3.6\n\n1.1.1 - 2015-03-22\n------------------\n\n* Fixed bug of timeout context manager as bool under Python 2.x\n* Tested with Python 3.4\n\n1.1.0 - 2014-05-02\n------------------\n\n* Added support for TIMER signal based timeout control (Posix OS only)\n* API changes due to new timeout controls\n* An exhaustive documentation.\n\n1.0.0 - 2014-02-09\n------------------\n\nInitial version", "description_content_type": null, "docs_url": null, "download_url": "", "downloads": { "last_day": -1, "last_month": -1, "last_week": -1 }, "home_page": "http://pypi.python.org/pypi/stopit", "keywords": "threads timeout", "license": "GPLv3", "maintainer": "", "maintainer_email": "", "name": "stopit", "package_url": "https://pypi.org/project/stopit/", "platform": "", "project_url": "https://pypi.org/project/stopit/", "project_urls": { "Homepage": "http://pypi.python.org/pypi/stopit" }, "release_url": "https://pypi.org/project/stopit/1.1.2/", "requires_dist": null, "requires_python": "", "summary": "Timeout control decorator and context managers, raise any exception in another thread", "version": "1.1.2" }, "last_serial": 3565736, "releases": { "1.0.0": [ { "comment_text": "", "digests": { "md5": "59af991271b3a4db91bb01999a33d3f9", "sha256": "d2fa5ca2b484b6265a5e2609cb37f137f6dea927902bdef64e9332982ce79918" }, "downloads": -1, "filename": "stopit-1.0.0.tar.gz", "has_sig": false, "md5_digest": "59af991271b3a4db91bb01999a33d3f9", "packagetype": "sdist", "python_version": "source", "requires_python": null, "size": 6322, "upload_time": "2014-02-09T16:51:38", "url": "https://files.pythonhosted.org/packages/8d/b4/2f41c1988f658f531bb012714deaec67a07edf968e3b03b0d16b4a07f8b4/stopit-1.0.0.tar.gz" } ], "1.1.0": [ { "comment_text": "", "digests": { "md5": "77bec39a670abd6f889ad736d21520d3", "sha256": "8e6252c1e10942d45130f1d08d0e41fb758b4b570d680856abda9cf5c5e7ee38" }, "downloads": -1, "filename": "stopit-1.1.0.tar.gz", "has_sig": false, "md5_digest": "77bec39a670abd6f889ad736d21520d3", "packagetype": "sdist", "python_version": "source", "requires_python": null, "size": 17712, "upload_time": "2014-05-02T15:01:38", "url": "https://files.pythonhosted.org/packages/15/cb/63c50d54a9a027ff769dea5211e237b7be093283ed51cf1874fdedd56c25/stopit-1.1.0.tar.gz" } ], "1.1.1": [ { "comment_text": "", "digests": { "md5": "dec60dae41bec73233e83db003390bdc", "sha256": "d879a892e6c0d524763b8bf20831a78311d86ea59ec199ec551abf3f494b0708" }, "downloads": -1, "filename": "stopit-1.1.1.tar.gz", "has_sig": false, "md5_digest": "dec60dae41bec73233e83db003390bdc", "packagetype": "sdist", "python_version": "source", "requires_python": null, "size": 18009, "upload_time": "2015-03-22T17:45:54", "url": "https://files.pythonhosted.org/packages/8e/88/888710b87a625789ee152ab6d9de0bd954c282b3a2f1c3ca0a7e4367d1c4/stopit-1.1.1.tar.gz" } ], "1.1.2": [ { "comment_text": "", "digests": { "md5": "0f6ef75399a9420fad7b7970d7be6d58", "sha256": "f7f39c583fd92027bd9d06127b259aee7a5b7945c1f1fa56263811e1e766996d" }, "downloads": -1, "filename": "stopit-1.1.2.tar.gz", "has_sig": false, "md5_digest": "0f6ef75399a9420fad7b7970d7be6d58", "packagetype": "sdist", "python_version": "source", "requires_python": null, "size": 18281, "upload_time": "2018-02-09T00:32:14", "url": "https://files.pythonhosted.org/packages/35/58/e8bb0b0fb05baf07bbac1450c447d753da65f9701f551dca79823ce15d50/stopit-1.1.2.tar.gz" } ] }, "urls": [ { "comment_text": "", "digests": { "md5": "0f6ef75399a9420fad7b7970d7be6d58", "sha256": "f7f39c583fd92027bd9d06127b259aee7a5b7945c1f1fa56263811e1e766996d" }, "downloads": -1, "filename": "stopit-1.1.2.tar.gz", "has_sig": false, "md5_digest": "0f6ef75399a9420fad7b7970d7be6d58", "packagetype": "sdist", "python_version": "source", "requires_python": null, "size": 18281, "upload_time": "2018-02-09T00:32:14", "url": "https://files.pythonhosted.org/packages/35/58/e8bb0b0fb05baf07bbac1450c447d753da65f9701f551dca79823ce15d50/stopit-1.1.2.tar.gz" } ] }