Reference

resume_back module

resumeback.__version__

The version of the module as a string, following the semver 2.0.0 spec.

@send_self decorator

@resumeback.send_self
@resumeback.send_self(*, catch_stopiteration=True, finalize_callback=None, debug=False)

Decorator that sends a “generator function” a wrapper of its instance.

Can be called with parameters or used as a decorator directly.

When a generator decorated by this is called, it receives a wrapper of its instance as the first parameter. The wrapper is an instance of GeneratorWrapper. The function then returns said wrapper.

Useful for creating generators that can leverage callback-based functions in a linear style, by passing the wrapper or one of its method properties as callback parameters and then pausing itself with yield.

For usage with classmethod() or staticmethod(), use send_self() first and wrap it with the *method decorator.

All provided arguments are stored as attributes and may be modified before called.

Note

Binding a strong reference to the generator in the generator’s scope itself will create a circular reference.

Parameters

  • catch_stopiteration (bool) – The wrapper catches StopIteration exceptions by default. If you wish to have them propagated, set this to False. Forwarded to the Wrapper.

  • finalize_callback (callable) – When the generator is garabage-collected and finalized, this callback will be called. It will recieve the weak-referenced object to the dead referent as first parameter, as specified by weakref.ref.

  • debug (bool) – Set this to True if you wish to have some debug output printed to sys.stdout. Probably useful if you are debugging problems with the generator not being resumed or finalized. Forwarded to the Wrapper.

Returns

A StrongGeneratorWrapper instance holding the created generator.

Raises

  • TypeError – If the parameters are not of types as specified.

  • ValueError – If the callable is not a generator function.

send_self.func

The wrapped generator function.

Wrappers

class resumeback.GeneratorWrapper(weak_generator, catch_stopiteration=True, debug=False)

Wraps a weak reference to a generator and adds convenience features.

Generally behaves like a normal generator in terms of the four methods send(), throw(), close() and next() (or with the global next funtion), but has the following convenience features:

  1. Method access will create a strong reference to the generator so that you can pass them as callback arguments from within the generator without causing it to get garbage-collected. Usually the reference count decreases (possibly to 0) when the generator pauses.

  2. The send() method has a default value for its value parameter. This allows it to be used without a parameter, where it will behave like next(generator), unlike the default implementation of send.

  3. The methods send() and throw() optionally catch StopIteration exceptions so that they are not propagated to the caller when the generator terminates.

  4. with_strong_ref() (= __call__()) will return a wrapper with a strong reference to the generator. This allows you to pass the entire wrapper by itself as a “callback” and the delegated function may choose between normally sending a value or throwing an exception where the generator was paused.

Parameters

  • weak_generator (weakref.ref) – Weak reference to a generator.

  • catch_stopiteration (bool) – If True, StopIteration exceptions raised by the generator will be caught by the ‘next’, ‘__next__’, ‘send’ and ‘throw’ methods. On Python >3.3 its value will be returned if available, None otherwise.

  • debug (bool) – Whether debug information should be printed.

generator

Strong reference to the generator. Will be retrieved from weak_generator in a property.

weak_generator

Instance of weakref.ref and weak reference to the generator

catch_stopiteration
debug
next()

Resume the generator.

Depending on catch_stopiteration, StopIteration exceptions will be caught and their values returned instead, if any.

Returns

The next yielded value or the value that the generator returned (using StopIteration or returning normally, Python>3.3).

Raises

Any exception raised by generator.next (or the generator).

with_strong_ref()

Get a StrongGeneratorWrapper with the same attributes.

with_weak_ref()

Get a GeneratorWrapper with the same attributes.

next_wait(timeout=None)

Wait before nexting a value to the generator to resume it.

Generally works like next(), but will wait until a thread is paused before attempting to resume it.

Additional information:

Parameters

timeout – Time in seconds that should be waited for suspension of the generator. No timeout will be in effect for None.

Raises

  • WaitTimeoutError – if the generator has not paused in time.

  • RuntimeError – if the generator has already terminated.

next_wait_async(timeout=None)

Create a waiting daemon thread to resume the generator.

Works like next_wait() but does so asynchronously. The spawned thread raises WaitTimeoutError when it times out.

Return type

threading.Thread

Returns

The created and running thread.

send(value)

Send a value to the generator to resume it.

Depending on catch_stopiteration, StopIteration exceptions will be caught and their values returned instead, if any.

Parameters

value – The value to send to the generator. Default is None, which results in the same behavior as calling next() or using the global ‘next’ function.

Returns

The next yielded value or the value that the generator returned (using StopIteration or returning normally, Python>3.3).

Raises

Any exception raised by generator.send.

send_wait(value, timeout=None)

Wait before sending a value to the generator to resume it.

Generally works like send(), but will wait until a thread is paused before attempting to resume it.

Additional information:

Parameters

timeout – Time in seconds that should be waited for suspension of the generator. No timeout will be in effect if None.

Raises

  • WaitTimeoutError – if the generator has not been paused.

  • RuntimeError – if the generator has already terminated.

send_wait_async(value, timeout=None)

Create a waiting daemon thread to send a value to the generator.

Works like send_wait() but does so asynchronously. The spawned thread raises WaitTimeoutError when it times out.

Return type

threading.Thread

Returns

The created and running thread.

throw(type[, value[, traceback]])

Raises an exception where the generator was suspended.

Depending on catch_stopiteration, StopIteration exceptions will be caught and their values returned instead, if any.

Accepts and expects the same parameters as generator.throw.

Returns

The next yielded value or the value that the generator returned (using StopIteration or returning normally, Python>3.3).

Raises

Any exception raised by the generator. This includes the thrown exception if the generator does not catch it and excludes StopIteration, if catch_stopiteration is set.

throw_wait(type, [value, [traceback, ]]timeout=None)

Wait before throwing a value to the generator to resume it.

Works like throw(), but will wait until a thread is paused before attempting to resume it.

Additional information:

Parameters

timeout – Time in seconds that should be waited for suspension of the generator. No timeout will be in effect if None.

Raises

  • WaitTimeoutError – if the generator has not been paused.

  • RuntimeError – if the generator has already terminated.

throw_wait_async(type, [value, [traceback, ]]timeout=None)

Create a waiting daemon thread to throw a value to the generator.

Works like throw_wait() but does so asynchronously. The spawned thread raises WaitTimeoutError when it times out.

Return type

threading.Thread

Returns

The created and running thread.

close()

Equivalent to self.generator.close().

has_terminated()

Check if the wrapped generator has terminated.

Return bool

Whether the generator has terminated.

can_resume()

Test if the generator can be resumed, i.e. is not running or closed.

Return bool

Whether the generator can be resumed.

__call__()

Alias for with_strong_ref().

class resumeback.StrongGeneratorWrapper(generator, weak_generator=None, catch_stopiteration=True, debug=False)

Wraps a generator and adds convenience features.

Operates similar to GeneratorWrapper, except that it holds a strong reference to the generator. Use this class if you want to pass the generator wrapper itself around, so that the generator is not garbage-collected.

Note

Binding an instance if this in the generator’s scope will create a circular reference.

__call__()

Alias for with_strong_ref().

Exceptions

class resumeback.WaitTimeoutError

Error class that is raised when a specified timeout is exceeded.