{"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":"en","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,"last_verified":"2026-04-11T00:00:00.000Z","next_check":"2026-07-10T00:00:00.000Z"}