{"id":3744,"library":"polling2","title":"polling2: Enhanced Polling Utility","description":"polling2 is an updated Python polling utility that provides many configurable options for retrying operations. It allows users to repeatedly call a function until a desired condition is met, handling timeouts, delays, and error logging. The current version is 0.5.0, with new features and minor fixes released periodically.","status":"active","version":"0.5.0","language":"python","source_language":"en","source_url":"https://github.com/ddmee/polling2","tags":["polling","retry","utility","wait"],"install":[{"cmd":"pip install polling2","lang":"bash","label":"Install stable version"}],"dependencies":[],"imports":[{"symbol":"poll","correct":"from polling2 import poll"},{"note":"Introduced in v0.5.0 for decorator-based polling.","symbol":"poll_decorator","correct":"from polling2 import poll_decorator"},{"note":"Commonly used for handling polling failures.","symbol":"TimeoutException","correct":"from polling2 import TimeoutException"},{"note":"Commonly used for handling polling failures.","symbol":"MaxCallException","correct":"from polling2 import MaxCallException"}],"quickstart":{"code":"import time\nfrom polling2 import poll, TimeoutException\n\n# Simulate a resource that becomes available after some time\ndata_ready = False\ndef get_data():\n    global data_ready\n    if not data_ready:\n        print(\"Data not ready yet...\")\n        return None\n    print(\"Data is ready!\")\n    return {\"status\": \"success\", \"data\": [1, 2, 3]}\n\ndef check_data_status(result):\n    return result is not None and result.get(\"status\") == \"success\"\n\n# Simulate data becoming ready after 2 seconds in a separate thread\nimport threading\ndef make_data_ready_soon():\n    global data_ready\n    time.sleep(2.5)\n    data_ready = True\n\nprint(\"Attempting to poll for data...\")\nthreading.Thread(target=make_data_ready_soon).start()\n\ntry:\n    # Poll for the data, checking every 0.5 seconds, with a 5-second timeout\n    result = poll(\n        target=get_data,\n        step=0.5,\n        timeout=5,\n        check_success=check_data_status,\n        # log_errors=True # Uncomment to log errors from target function\n    )\n    print(f\"Polling successful: {result}\")\nexcept TimeoutException:\n    print(\"Polling timed out: Data did not become ready within 5 seconds.\")\nexcept Exception as e:\n    print(f\"An unexpected error occurred during polling: {e}\")","lang":"python","description":"This quickstart demonstrates how to use `polling2.poll` to wait for a simulated resource to become available. It sets a target function, a polling interval (`step`), a maximum wait time (`timeout`), and a `check_success` function to define when polling should stop. It also includes error handling for `TimeoutException`."},"warnings":[{"fix":"Update `pip install` commands to `polling2` and change all import statements from `import polling` or `from polling import ...` to `import polling2` or `from polling2 import ...`.","message":"The library package name changed from `polling` to `polling2` in version 0.4.0. Projects using the original `polling` library must update their imports and dependencies.","severity":"breaking","affected_versions":">=0.4.0"},{"fix":"For infinite polling, explicitly set `poll_forever=True`. For finite polling, always provide a positive integer for `timeout`. Avoid using `timeout=0` or `timeout=None` unless infinite polling is desired.","message":"The `timeout` parameter's behavior was clarified in v0.4.7: `timeout=0` or `timeout=None` is equivalent to setting `poll_forever=True`. Misunderstanding this can lead to infinite loops if not intended.","severity":"gotcha","affected_versions":">=0.4.7"},{"fix":"Ensure your `check_success` logic reliably returns `True` or `False`. If the `target` function might raise exceptions that should not immediately stop polling, use the `ignore_exceptions` parameter, e.g., `ignore_exceptions=(ConnectionError,)`.","message":"The `check_success` function (or equivalent lambda) must return a boolean. If it raises an exception, `polling2` will stop unless `ignore_exceptions` is configured to handle specific exceptions.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Always wrap `poll()` calls in `try-except` blocks to gracefully handle `polling2.TimeoutException` and `polling2.MaxCallException`. This allows for proper error reporting or fallback logic.","message":"When `poll()` fails to meet the `check_success` condition within the specified `timeout` or `max_tries`, it raises `polling2.TimeoutException` or `polling2.MaxCallException` respectively. Failing to catch these can lead to unhandled errors.","severity":"gotcha","affected_versions":"All versions"}],"env_vars":null,"search_vec":"'0.5.0':44 'allow':21 'call':25 'condit':31 'configur':15 'current':41 'delay':36 'desir':30 'enhanc':2 'error':38 'featur':47 'fix':50 'function':27 'handl':34 'log':39 'mani':14 'met':33 'minor':49 'new':46 'oper':19 'option':16 'period':52 'poll':3,10,53 'polling2':1,5 'provid':13 'python':9 'releas':51 'repeat':24 'retri':18,54 'timeout':35 'updat':8 'user':22 'util':4,11,55 'version':42 'wait':56","created_at":"2026-04-11T17:42:51.838271+00:00","updated_at":"2026-04-16T18:06:07.410250+00:00","problems":[{"fix":"Install the library using pip: `pip install polling2`","cause":"The 'polling2' library is not installed in your Python environment.","error":"ModuleNotFoundError: No module named 'polling2'"},{"fix":"Catch the `polling2.TimeoutException` to handle the failure. You might need to increase the `timeout` or `max_tries` values, or refine your `target` or `check_success` logic.","cause":"The polling operation exceeded the specified `timeout` or `max_tries` before the `check_success` condition was met.","error":"polling2.TimeoutException"},{"fix":"Review the `polling2.poll()` documentation and ensure all keyword arguments (e.g., `target`, `step`, `timeout`, `check_success`, `ignore_exceptions`) are spelled correctly and are valid parameters for the function.","cause":"An unrecognized or misspelled keyword argument was passed to the `polling2.poll()` function.","error":"TypeError: poll() got an unexpected keyword argument 'some_invalid_argument'"},{"fix":"Ensure your `target` function eventually returns a value that satisfies your `check_success` condition (or is truthy by default). If `poll_forever` is not intended, set a `timeout` or `max_tries`. If using a lambda, ensure it calls the function, e.g., `lambda: my_function()` instead of `lambda: my_function` or `lambda: my_function == True` if `my_function` is meant to be executed.","cause":"The `check_success` function or the `target` function (when `check_success` is default) never returns a truthy value, or the polling parameters (`timeout`, `poll_forever`, `max_tries`) are incorrectly configured, leading to an infinite loop or unexpected behavior.","error":"Polling does not stop or runs forever without TimeoutException"}],"ecosystem":"pypi","meta_description":null,"install_score":null,"quickstart_score":null,"quickstart_tag":null,"pypi_latest":"0.5.0","cli_name":"","cli_version":null,"type":"library","homepage":null,"github":"http://github.com/ddmee/polling2","docs":null,"changelog":null,"pypi":"https://pypi.org/project/polling2/","npm":null,"openapi_spec":null,"status_page":null,"smithery":null,"categories":["testing"],"base_url":null,"auth_type":null,"provenance":{"verified_status":"passing","verified_at":"2026-06-28","last_verified":"2026-08-29","next_check":"2026-07-28","install_tag":null}}