API reference

Core

gentools.core.reusable(func)

Create a reusable class from a generator function

Parameters:func (GeneratorCallable[T_yield, T_send, T_return]) – the function to wrap

Note

• the callable must have an inspectable signature
• If bound to a class, the new reusable generator is callable as a method. To opt out of this, add a staticmethod() decorator above this decorator.

class gentools.core.oneyield(func)

Decorate a function to turn it into a basic generator

The resulting generator yields the function’s return value once, and then returns the value it is sent (with send()).

__init__(func)

Initialize self. See help(type(self)) for accurate signature.

gentools.core.sendreturn(gen, value)

Send an item into a generator expecting a final return value

Parameters:

• gen (Generator[T_yield, T_send, T_return]) – the generator to send the value to
• value (T_send) – the value to send

Raises:

RuntimeError – if the generator did not return as expected

Returns:

the generator’s return value

Return type:

T_return

class gentools.core.relay(*genfuncs)

Decorate a generator callable to relay yield/send values through another generator

Example

>>> def try_until_positive(outvalue):
...     value = yield outvalue
...     while value < 0:
...         value = yield 'not positive, try again'
...     return value
...
>>> @relay(try_until_positive)
... def my_max(value):
...     while value < 100:
...         newvalue = yield value
...         if newvalue > value:
...             value = newvalue
...     return value
...
>>> gen = my_max(5)
>>> next(gen)
5
>>> gen.send(-4)
'not positive, try again'
>>> gen.send(-1)
'not positive, try again'
>>> gen.send(8)
8
>>> gen.send(104)
StopIteration(104)

See also

irelay()

__call__(func)

Call self as a function.

__init__(*genfuncs)

Initialize self. See help(type(self)) for accurate signature.

class gentools.core.map_yield(*funcs)

Decorate a generator callable to apply a function to each yield value

Example

>>> @map_yield('the current max is: {}'.format)
... def my_max(value):
...     while value < 100:
...         newvalue = yield value
...         if newvalue > value:
...             value = newvalue
...     return value
...
>>> gen = my_max(5)
>>> next(gen)
'the current max is: 5'
>>> gen.send(11)
'the current max is: 11'
>>> gen.send(104)
StopIteration(104)

See also

imap_yield()

__call__(func)

Call self as a function.

__init__(*funcs)

Initialize self. See help(type(self)) for accurate signature.

class gentools.core.map_send(*funcs)

Decorate a generator callable to apply functions to each send value

Example

>>> @map_send(int)
... def my_max(value):
...     while value < 100:
...         newvalue = yield value
...         if newvalue > value:
...             value = newvalue
...     return value
...
>>> gen = my_max(5)
>>> next(gen)
5
>>> gen.send(11.3)
11
>>> gen.send('104')
104

See also

imap_send()

__call__(func)

Call self as a function.

__init__(*funcs)

Initialize self. See help(type(self)) for accurate signature.

class gentools.core.map_return(*funcs)

Decorate a generator callable to apply functions to the return value

Example

>>> @map_return('final value: {}'.format)
... def my_max(value):
...     while value < 100:
...         newvalue = yield value
...         if newvalue > value:
...             value = newvalue
...     return value
...
>>> gen = my_max(5)
>>> next(gen)
5
>>> gen.send(11.3)
11.3
>>> gen.send(104)
StopIteration('final value: 104')

See also

imap_return()

__call__(func)

Call self as a function.

__init__(*funcs)

Initialize self. See help(type(self)) for accurate signature.

gentools.core.py2_compatible(func)

Decorate a generator function to make it Python 2/3 compatible. Use together with return_().

Example

>>> @py2_compatible
... def my_max(value):
...     while value < 100:
...         newvalue = yield value
...         if newvalue > value:
...             value = newvalue
...     return_(value)

is equivalent to:

>>> def my_max(value):
...     while value < 100:
...         newvalue = yield value
...         if newvalue > value:
...             value = newvalue
...     return value

Note

This is necessary because PEP479 makes it impossible to replace return with raise StopIteration in newer python 3 versions.

Warning

Although the wrapped generator acts like a generator, it is not an strict generator instance. For most purposes (e.g. yield from) it works fine, but isgenerator() will return False.

See also

PEP 479

gentools.core.return_(value)

Python 2/3 compatible way to return a value from a generator

Use only with the py2_compatible() decorator

class gentools.core.compose(*funcs)

compose a function from a chain of functions

Parameters:*funcs – callables to compose

Note

• if given no functions, acts as an identity function

__call__(*args, **kwargs)

Call self as a function.

__eq__(other)

Return self==value.

__hash__()

Return hash(self).

__init__(*funcs)

Initialize self. See help(type(self)) for accurate signature.

__ne__(other)

Return self!=value.

Types

base classes and interfaces

class gentools.types.Generable

ABC for generable objects. Any object where __iter__() returns a generator implements it.

__iter__()

Returns:the generator iterator Return type:Generator[T_yield, T_send, T_return]

class gentools.types.GeneratorCallable

ABC for callables which return a generator. Note that generator functions already implement this.

__call__(*args, **kwargs)

Returns:the resulting generator Return type:Generator[T_yield, T_send, T_return]

class gentools.types.ReusableGenerator(*args, **kwargs)

base class for reusable generator functions

Warning

• Do not subclass directly. Subclasses are created with the reusable() decorator.
• Instances if this class are only picklable on python 3.5+

__eq__(other)

Return self==value.

__hash__()

Return hash(self).

__init__(*args, **kwargs)

Initialize self. See help(type(self)) for accurate signature.

__iter__()

Returns:the generator iterator Return type:Generator[T_yield, T_send, T_return]

__ne__(other)

Return self!=value.

__repr__()

Return repr(self).

replace(**kwargs)

create a new instance with certain fields replaced

Parameters:**kwargs – fields to replace Returns:a copy with replaced fields Return type:ReusableGenerator