timeout-sampler

library1.0.22pypypi✓ verified 86d ago

A utility class that repeatedly calls a function until it returns a truthy value or a timeout expires. Provides customizable retry logic with sleep intervals. Version 1.0.22, actively maintained, monthly releases.

testing devops

pip install timeout-sampler

github ↗package ↗

INSTALL

IMPORT

SIG · TIMEOUT-SAMPLER

timeout-sampler

testingpythonv1.0.22

Install

4.7s avg

Import

54ms

Disk

29MB

Pass rate

10/ 10

Env Coverage10 / 10

glibc

3.9–3.13

musl

3.9–3.13

Install & Compatibility

Where this runs

tested against v1.0.22 · 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.056s · 30.9MB

glibc

py 3.10–3.95 runs

installs and imports cleanly · install 4.7s · import 0.052s · 31MB

29MB installed

● package 29MB

Code

Verified usage

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

TimeoutSampler

✓ from timeout_sampler import TimeoutSampler

✗ from timeout_sampler import timeout_sampler

Class is CamelCase, not snake_case

TimeoutExpiredError

✓ from timeout_sampler import TimeoutExpiredError

✗ from timeout_sampler.exceptions import TimeoutExpiredError

Exception is exported from top-level package

Basic usage showing how to wait for a function to return a truthy value.

from timeout_sampler import TimeoutSampler import time def sample_func(): return None # simulate condition not ready # Wait up to 5 seconds, check every 0.5 seconds sampler = TimeoutSampler( timeout=5, sleep=0.5, func=sample_func, exceptions_dict={} ) try: for value in sampler: if value: print("Condition met") break except TimeoutExpiredError: print("Timeout reached")

Debug

Known issues

gotchaIteration does not stop on first truthy value automatically; you must break yourself or use a loop with break. The iterator yields all results until timeout unless you break early.

fix

Break out of the for loop once condition is met.

affects: all

gotchaThe 'exceptions_dict' parameter is required if you want to retry on exceptions; if omitted or empty, the sampler will not catch exceptions and they will propagate immediately.

fix

Pass a dictionary mapping exception types to booleans (True to retry, False to raise) or an empty dict {} to avoid retry on any exception.

affects: all

deprecatedImport from 'timeout_sampler' directly is the only supported path. Some older examples incorrectly import from submodules like 'timeout_sampler.timeout_sampler'.

fix

Use 'from timeout_sampler import TimeoutSampler'.

affects: >=1.0.0

Errors

Common errors & fixes

AttributeError: module 'timeout_sampler' has no attribute 'TimeoutSampler'

Installed incorrect package 'timeout-sampler-python' or similar name. The correct package is 'timeout-sampler'.

fix

pip uninstall timeout-sampler-python && pip install timeout-sampler

TypeError: __init__() missing 1 required positional argument: 'exceptions_dict'

The 'exceptions_dict' parameter is mandatory in constructor.

fix

Add exceptions_dict={} or a dict with exception->bool mapping.

StopIteration

The iterator raises StopIteration if timeout expires before any truthy value is returned. Usually handled by catching TimeoutExpiredError.

fix

Wrap iteration in try/except TimeoutExpiredError.

Upgrade

Version history

1.0.22latest on PyPI · released Nov 18, 2025

Audit

Dependencies

No dependency data recorded yet.

Agent activity

8 hits · last 30 days

node

Resources

githubhttps://github.com/RedHatQE/timeout-sampler ↗

packagehttps://pypi.org/project/timeout-sampler/ ↗