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)

__call__(*args, **kwargs)

Returns:

the resulting generator

Return type:

Generator[T_yield, T_send, T_return]

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()

__init__(*genfuncs)

__call__(func)

Call self as a function.

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()

__init__(*funcs)

__call__(func)

Call self as a function.

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()

__init__(*funcs)

__call__(func)

Call self as a function.

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()

__init__(*funcs)

__call__(func)

Call self as a function.

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

__init__(*funcs)

__hash__()

Return hash(self).

__eq__(other)

Return self==value.

__ne__(other)

Return self!=value.

__call__(*args, **kwargs)

Call self as a function.

gentools.core.imap_yield(func, gen)

Apply a function to all yield values of a generator

Parameters:

• func (Callable[[T_yield], T_mapped]) – the function to apply

• gen (Generable[T_yield, T_send, T_return]) – the generator iterable.

Returns:

the mapped generator

Return type:

Generator[T_mapped, T_send, T_return]

gentools.core.imap_send(func, gen)

Apply a function to all send values of a generator

Parameters:

• func (Callable[[T_send], T_mapped]) – the function to apply

• gen (Generable[T_yield, T_mapped, T_return]) – the generator iterable.

Returns:

the mapped generator

Return type:

Generator[T_yield, T_send, T_return]

gentools.core.imap_return(func, gen)

Apply a function to the return value of a generator

Parameters:

• func (Callable[[T_return], T_mapped]) – the function to apply

• gen (Generable[T_yield, T_send, T_return]) – the generator iterable.

Return type:

Generator[T_yield, T_send, T_mapped]

gentools.core.irelay(gen, thru)

Create a new generator by relaying yield/send interactions through another generator

Parameters:

• gen (Generable[T_yield, T_send, T_return]) – the original generator

• thru (Callable[[T_yield], Generator]) – the generator callable through which each interaction is relayed

Returns:

the relayed generator

Return type:

Generator

Types

base classes and interfaces

class gentools.types.Generable

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

abstract __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.

__init__(*args, **kwargs)

__iter__()

Returns:

the generator iterator

Return type:

Generator[T_yield, T_send, T_return]

__eq__(other)

Return self==value.

__repr__()

Return repr(self).

__hash__()

Return hash(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