polling2

library0.5.0pypypi✓ verified 25d ago

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.

testing

pip install polling2

github ↗package ↗

INSTALL

IMPORT

SIG · POLLING2

polling2

testingpythonv0.5.0

Install

1.5s avg

Import

19ms

Disk

16MB

Pass rate

10/ 10

Env Coverage10 / 10

glibc

3.9–3.13

musl

3.9–3.13

Install & Compatibility

Where this runs

tested against v0.5.0 · pip install

no network on importno background threads

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

py 3.10–3.95 runs

installs and imports cleanly · install 0.0s · import 0.018s · 17.8MB

glibc

py 3.10–3.95 runs

installs and imports cleanly · install 1.5s · import 0.020s · 18MB

16MB installed

● package 16MB

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

poll

✓ from polling2 import poll

poll_decorator

✓ from polling2 import poll_decorator

Introduced in v0.5.0 for decorator-based polling.

TimeoutException

✓ from polling2 import TimeoutException

Commonly used for handling polling failures.

MaxCallException

✓ from polling2 import MaxCallException

Commonly used for handling polling failures.

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`.

import time from polling2 import poll, TimeoutException # Simulate a resource that becomes available after some time data_ready = False def get_data(): global data_ready if not data_ready: print("Data not ready yet...") return None print("Data is ready!") return {"status": "success", "data": [1, 2, 3]} def check_data_status(result): return result is not None and result.get("status") == "success" # Simulate data becoming ready after 2 seconds in a separate thread import threading def make_data_ready_soon(): global data_ready time.sleep(2.5) data_ready = True print("Attempting to poll for data...") threading.Thread(target=make_data_ready_soon).start() try: # Poll for the data, checking every 0.5 seconds, with a 5-second timeout result = poll( target=get_data, step=0.5, timeout=5, check_success=check_data_status, # log_errors=True # Uncomment to log errors from target function ) print(f"Polling successful: {result}") except TimeoutException: print("Polling timed out: Data did not become ready within 5 seconds.") except Exception as e: print(f"An unexpected error occurred during polling: {e}")

Debug

Known issues

breakingThe 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.

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 ...`.

affects: >=0.4.0

gotchaThe `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.

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.

affects: >=0.4.7

gotchaThe `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.

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,)`.

affects: All versions

gotchaWhen `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.

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.

affects: All versions

Errors

Common errors & fixes

ModuleNotFoundError: No module named 'polling2'

The 'polling2' library is not installed in your Python environment.

fix

Install the library using pip: `pip install polling2`

polling2.TimeoutException

The polling operation exceeded the specified `timeout` or `max_tries` before the `check_success` condition was met.

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.

TypeError: poll() got an unexpected keyword argument 'some_invalid_argument'

An unrecognized or misspelled keyword argument was passed to the `polling2.poll()` function.

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.

Polling does not stop or runs forever without TimeoutException

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.

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.

Upgrade

Version history

0.5.0latest on PyPI · released Jul 19, 2021

Audit

Dependencies

No dependency data recorded yet.

Agent activity

9 hits · last 30 days

node

Resources

githubhttp://github.com/ddmee/polling2 ↗

packagehttps://pypi.org/project/polling2/ ↗