pyrakoon.utils

Utility functions

pyrakoon.utils.LOGGER = <logging.Logger object>

Logger for code in this module

pyrakoon.utils.update_argspec(*argnames)

Wrap a callable to use real argument names

When generating functions at runtime, one often needs to fall back to *args and **kwargs usage. Using these features require well-documented code though, and renders API documentation tools less useful.

The decorator generated by this function wraps a decorated function, which takes **kwargs, into a function which takes the given argument names as parameters, and passes them to the decorated function as keyword arguments.

The given argnames can be strings (for normal named arguments), or tuples of a string and a value (for arguments with default values). Only a couple of default value types are supported, an exception will be thrown when an unsupported value type is given.

Example usage:

>>> @update_argspec('a', 'b', 'c')
... def fun(**kwargs):
...     return kwargs['a'] + kwargs['b'] + kwargs['c']

>>> import inspect
>>> tuple(inspect.getargspec(fun))
(['a', 'b', 'c'], None, None, None)

>>> print fun(1, 2, 3)
6
>>> print fun(1, c=3, b=2)
6

>>> print fun(1, 2)
Traceback (most recent call last):
    ...
TypeError: fun() takes exactly 3 arguments (2 given)


>>> @update_argspec()
... def g():
...     print 'Hello'

>>> tuple(inspect.getargspec(g))
([], None, None, None)

>>> g()
Hello

>>> @update_argspec('name', ('age', None))
... def hello(**kwargs):
...     name = kwargs['name']
...
...     if kwargs['age'] is None:
...         return 'Hello, %s' % name
...     else:
...         age = kwargs['age']
...         return 'Hello, %s, who is %d years old' % (name, age)

>>> tuple(inspect.getargspec(hello))
(['name', 'age'], None, None, (None,))

>>> hello('Nicolas')
'Hello, Nicolas'
>>> hello('Nicolas', 25)
'Hello, Nicolas, who is 25 years old'

Parameters:argnames (iterable of str or (str, object)) – Names of the arguments to be used Returns:Decorator which wraps a given callable into one with a correct argspec Return type:callable

pyrakoon.utils.format_doc(doc)

Try to format a docstring

This function will split the given string on line boundaries, strip all lines, and stitch everything back together.

Parameters:doc (str or unicode) – Docstring to format Returns:Formatted docstring Return type:unicode

pyrakoon.utils.kill_coroutine(coroutine, log_fun=None)

Kill a coroutine by injecting StopIteration

If the coroutine has exited already, we ignore any errors.

The provided log_fun function will be called when an unexpected error occurs. It should take a message argument.

Example:

>>> import sys

>>> def f():
...     a = yield 1
...     b = yield 3
...     c = yield 5

>>> f_ = f()
>>> print f_.next()
1
>>> print f_.send('2')
3
>>> kill_coroutine(f_)

>>> def incorrect():
...     try:
...         yield 1
...         a = yield 2
...     except:
...         raise Exception
...     yield 3

>>> i = incorrect()
>>> print i.next()
1
>>> kill_coroutine(i,
...     lambda msg: sys.stdout.write('Error: %s' % msg))
Error: Failure while killing coroutine

Parameters:

• coroutine (generator) – Coroutine to kill
• log_fun (callable) – Function to call when an exception is encountered

pyrakoon.utils.process_blocking(message, stream)

Process a message using a blocking stream API

The given message will be serialized and written to the stream. Once the message was written, the result will be read using read_blocking().

The given stream object should implement write and read methods, somewhat like the file interface.

Parameters:

• message (pyrakoon.protocol.Message) – Message to process
• stream (object) – Stream to work on

Returns:

Result of the command execution

Return type:

object

See:

pyrakoon.client.AbstractClient._process()

See:

pyrakoon.protocol.Message.serialize()

See:

pyrakoon.protocol.Message.receive()

pyrakoon.utils.read_blocking(receiver, read_fun)

Process message result parsing using a blocking stream read function

Given a function to read a given amount of bytes from a result channel, this function handles the interaction with the parsing coroutine of a message (as passed to pyrakoon.client.AbstractClient._process()).

Parameters:

• receiver (generator) – Message result parser coroutine
• read_fun (callable) – Callable to read a given number of bytes from a result stream

Returns:

Message result

Return type:

object

Raises TypeError:  

Coroutine didn’t return a Result

See:

pyrakoon.protocol.Message.receive()