timeout-sampler

What it is and what it does

TimeoutSampler is a polling utility that repeatedly calls a function at fixed intervals until it returns a truthy value or a timeout expires. It wraps the function call in a loop, sleeping between attempts, and can be configured to ignore or retry on specific exception types—either all instances of an exception class or only those matching string patterns or callable filters. The package includes a decorator form (@retry) for wrapping functions directly.

The primary use case is waiting for external conditions (SSH connectivity, service availability, async task completion) with fine-grained control over which exceptions should trigger retries versus immediate failure. It logs outcomes (success, failure, timeout) with elapsed time and optional custom labels, and automatically redacts sensitive kwargs like Authorization headers from logs.

Use it for:

• Wait for a service to become available before proceeding with integration tests or deployment scripts
• Retry API calls with selective exception handling (e.g., retry on 5xx errors but fail immediately on 4xx)
• Poll for completion of long-running background tasks with a timeout and custom logging
• Decorate functions to add automatic retry logic with timeout and exception filtering
• Wait for SSH or network connectivity with detailed logging of connection attempts

Worth the install?

AI-flagged interpretation of the facts on this page — verify before relying

Polls a function repeatedly within a timeout window, collecting results and handling exceptions selectively, until success or timeout.

Yes, if you need polling with selective exception handling and timeout-based retry logic. The active maintenance and permissive license are favorable. However, verify whether pytest is a true runtime dependency—if it is, the high install friction may be a concern for lightweight deployments. The minimal community visibility (0 stars) suggests limited real-world validation, so evaluate it in a test environment first.

Install

timeout-sampler on PyPI

pip install timeout-sampler

uv add timeout-sampler

poetry add timeout-sampler

Installing timeout-sampler

Before you install

High install friction due to two runtime dependencies (pytest and python-simple-logger). Active maintenance with a recent release (24 days ago), though the project has minimal community visibility (0 stars).

License in practice

Apache-2.0 permissive license allows commercial and private use with minimal restrictions; suitable for most projects.

Quickstart

from timeout_sampler import TimeoutSampler

for sample in TimeoutSampler(
    wait_timeout=60,
    sleep=1,
    func=my_function,
    arg1=value1,
):
    if sample:
        break

Requires Python >=3.10

Verify before relying

• Whether pytest is truly required at runtime or only for testing (listed as runtime dependency but typically test-only)
• Performance characteristics when polling high-frequency or long-running functions
• Behavior and overhead of sensitive-key redaction in logging

Package facts

Evidence: timeout_sampler-1.1.2.tar.gz

Tags

More Testing packages