totaltimeout 3.0.2

Versioning

This library’s version numbers follow the SemVer 2.0.0 specification.

Installation

pip install totaltimeout

Usage

Import the Timeout class.

from totaltimeout import Timeout

Waiting in a “timed loop” for an API with retries (useful for unreliable APIs that may either hang or need retries):

for time_left in Timeout(SOME_NUMBER_OF_SECONDS):
     reply = requests.get(api_url, timeout=time_left)
     if reply.status == 200:
         break

Same as above, but with a wait between retries:

timeout = Timeout(SOME_NUMBER_OF_SECONDS)
for time_left in timeout:
     reply = requests.get(api_url, timeout=time_left)
     if reply.status == 200:
         break
     # If you need to get the remaining time again in the same
     # loop iteration, you have to use the .time_left() method:
     if timeout.time_left() <= RETRY_DELAY:
         break
     time.sleep(RETRY_DELAY)

Waiting for multiple tasks to finish:

timeout = Timeout(10.0)
thread_foo.join(timeout.time_left())
thread_bar.join(timeout.time_left())
thread_qux.join(timeout.time_left())
# Works out almost as if we waited 10
# seconds for each thread in parallel.

Waiting for multiple tasks within each iteration of a “timed loop”:

timeout = Timeout(SOME_NUMBER_OF_SECONDS)
for time_left in timeout:
     some_work(timeout=time_left)
     some_more_work(timeout=timeout.time_left())
     some_other_work(timeout=timeout.time_left())

Using a monotonic clock instead of the wall clock:

import time

timeout = Timeout(10.0, clock=time.monotonic)

You can also set the starting time of the timeout. This lets timeouts count down from a well-known point in time, which can be useful for testing, for synchronizing timeouts across networks, and so on:

start_of_this_minute = (time.now() // 60) * 60
timeout = Timeout(10.0, start=start_of_this_minute)

moment_in_time = time.now()
timeout = Timeout(10.0, start=moment_in_time)
time.sleep(1)
identical_timeout = Timeout(10.0, start=moment_in_time)
# both timeouts have exactly the same amount of time left

Finally, totaltimeout can be an ergonomic way to put a time limit on a loop even if the code in the loop does not support timeouts, so long as each iteration does not block for too long:

counter = 0
for _ in Timeout(30):
    counter += 1