{"id":4855,"library":"wrapt-timeout-decorator","title":"Wrapt Timeout Decorator","description":"wrapt-timeout-decorator is a Python library providing a robust timeout decorator. It emphasizes correctness when used with various types of methods (e.g., class, static) and preserves traceback information for debugging. It supports dynamic timeout adjustment and offers two strategies: 'Signals' (for POSIX systems and main thread) and 'Subprocess' (the default, compatible with Windows and multithreaded environments, utilizing `multiprocess` and `dill` for extended pickling capabilities). The library is actively maintained, with version 1.5.1 released in February 2024.","status":"active","version":"1.5.1","language":"en","source_language":"en","source_url":"https://github.com/bitranox/wrapt_timeout_decorator.git","tags":["timeout","decorator","concurrency","multiprocessing","signals","wrapt"],"install":[{"cmd":"pip install wrapt-timeout-decorator","lang":"bash","label":"Install stable version"}],"dependencies":[{"reason":"Core library for robust function wrapping and decorator implementation.","package":"wrapt"},{"reason":"Enhanced serialization (pickling) for broader object type support in the 'Subprocess' timeout strategy, especially critical for Windows compatibility and handling objects in __main__.","package":"dill"},{"reason":"Used instead of Python's standard 'multiprocessing' for the 'Subprocess' strategy, offering better compatibility and functionality across various system configurations.","package":"multiprocess"},{"reason":"Used for process management, particularly for monitoring and terminating child processes in the 'Subprocess' strategy.","package":"psutil"}],"imports":[{"symbol":"timeout","correct":"from wrapt_timeout_decorator import timeout"}],"quickstart":{"code":"import time\nfrom wrapt_timeout_decorator import timeout, TimeoutError\n\n@timeout(5)\ndef long_running_function():\n    print(\"Starting long_running_function...\")\n    for i in range(1, 10):\n        time.sleep(1)\n        print(f'{i} seconds passed inside function.')\n    print(\"long_running_function finished.\")\n\nif __name__ == '__main__':\n    try:\n        long_running_function()\n        print(\"Function completed without timeout.\")\n    except TimeoutError:\n        print(\"Function timed out after 5 seconds.\")\n    except Exception as e:\n        print(f\"An unexpected error occurred: {e}\")","lang":"python","description":"This example demonstrates applying the `@timeout` decorator to a function. The function `long_running_function` is designed to run for 9 seconds. However, with a timeout set to 5 seconds, a `TimeoutError` will be raised, and the `except` block will catch it, indicating the function timed out."},"warnings":[{"fix":"Move decorated functions into a separate Python module (e.g., `my_module.py`) and import them into your main script. This ensures they are properly picklable for subprocess execution.","message":"When using the default 'Subprocess' strategy (especially on Windows), functions decorated in the `__main__` context (i.e., directly in the script being run) might encounter pickling errors. To avoid this, it's highly recommended to define decorated functions within a separate module and import them.","severity":"gotcha","affected_versions":"All versions"},{"fix":"For cross-platform compatibility or use in subthreads, rely on the default 'Subprocess' strategy (`use_signals=False` or omit the parameter). Explicitly set `use_signals=True` only when targeting POSIX main threads.","message":"The 'Signals' timeout strategy (`use_signals=True`) is only available on POSIX systems (Linux, macOS) and exclusively works in the main thread. It will be automatically disabled if used in a subthread or on Windows.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Avoid setting `allow_eval=True` unless strictly necessary and ensure that any string passed for evaluation (`dec_timeout`) originates from a trusted, controlled source.","message":"Enabling the `allow_eval=True` parameter can introduce severe security vulnerabilities if the timeout string is derived from untrusted input, as it allows arbitrary code execution within the decorator's context.","severity":"breaking","affected_versions":"All versions"},{"fix":"When `dec_hard_timeout=True` is used, ensure the timeout value is sufficiently long to account for process spawning overhead. For very short timeouts, consider if `dec_hard_timeout` is truly necessary or if a slightly more flexible timeout is acceptable.","message":"Using `dec_hard_timeout=True` to enforce a strict timeout can lead to immediate timeouts if the specified duration is too short for the subprocess to even spawn and initialize, particularly on Windows where process spawning can take significant time (e.g., 0.5 seconds).","severity":"gotcha","affected_versions":"All versions"},{"fix":"For nested timeouts, ensure that `use_signals=True` is applied only to the outermost `@timeout` decorator. All inner decorators must explicitly or implicitly use `use_signals=False`.","message":"Nested `@timeout` decorators are problematic if more than one attempts to use `use_signals=True`, as there is only one ALARM signal per process on Unix. Only the outermost decorator should use signals, while inner ones must use `use_signals=False` (the default).","severity":"gotcha","affected_versions":"All versions"}],"env_vars":null,"last_verified":"2026-04-12T00:00:00.000Z","next_check":"2026-07-11T00:00:00.000Z"}