---
id: timeout-sampler
version: "1.1.2"
license: Apache-2.0
license_treatment: permissive
maintenance: active
---

# timeout-sampler — Timeout utility class to wait for any function output and interact with it in given time

License: permissive · Maintenance: active · Downloads: 185.0K/mo

## 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 above — 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

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

- License: Apache-2.0 (permissive)
- Python support: supports_current
- Install friction: high
- Maintenance: active
- Downloads: 185.0K/month (top 15,000 on PyPI)
- Known vulnerabilities: none known

## Tags

retry with timeout, polling function results, wait for condition with timeout, exception handling retry loop, function polling utility, timeout-based function sampling, polling, retry-logic, timeout-handling

[View on SkillFed](https://skillfed.io/packages/timeout-sampler) · [View on PyPI](https://pypi.org/project/timeout-sampler/)