serdio.io_lifter module

Tools for lifting arbitrary functions into functions mapping bytes to bytes.

This module deals with automatically converting between arbitrary functions and “byte-handlers”, i.e. functions mapping bytes to bytes. The lift_io() decorator allows a user to convert an arbitrary function to a bytes-handler. lift_io() returns an IOLifter, a Callable class that wraps an arbitrary function with the machinery needed to convert it into a byte-handler via IOLifter.as_bytes_handler(). IOLifter does not otherwise change the function’s call-behavior.

Usage

@serdio.lift_io
def my_cool_function(x: int, y: float, b: float = 1.0) -> float:
    z = x * y
    z += b
    return z

bytes_handler: Callable[bytes, bytes] = my_cool_function.as_bytes_handler()

z = my_cool_function(2, 3.0)
assert z == 7.0

class serdio.io_lifter.IOLifter(f, hook_bundle)

Bases: object

A Callable for lifting arbitrary functions into equivalent bytes-handlers.

Parameters:

• f (Callable) – The function we want to lift.

• hook_bundle (Optional[SerdeHookBundle]) – An optional SerdeHookBundle for dealing with user-defined types

as_bytes_handler()

Lift the wrapped Callable into its functionally-equivalent bytes-handler.

A bytes-handler is a Callable mapping Serdio bytes to Serdio bytes.

as_cape_handler()

Alias of IOLifter.as_bytes_handler().

property decoder

property encoder

property hook_bundle

serdio.io_lifter.lift_io(f=None, *, encoder_hook=None, decoder_hook=None, hook_bundle=None, as_handler=False)

Lift a function into an IOLifter.

The resulting IOLifter Callable is nearly identical to the original function, however it can also easily be converted to a bytes-handler with as_bytes_handler(). The bytes-handler expects Serdio bytes as input and returns Serdio bytes as its output.

This decorator expects at most one of these sets of kwargs to be specified:

• encoder_hook and decoder_hook

• hook_bundle

Parameters:

• f (Optional[Callable]) – A Callable to be IO-lifted into a bytes-handler.

• encoder_hook (Optional[Callable]) – An optional Callable that specifies how to convert custom-typed inputs or outputs into msgpack-able Python types (e.g. converting MyCustomClass into a dictionary of Python natives). See serdio.SerdeHookBundle for details.

• decoder_hook (Optional[Callable]) – An optional Callable that specifies how to invert encoder_hook for custom-typed inputs and outputs. See serdio.SerdeHookBundle for details.

• hook_bundle – An optional tuple, list, or SerdeHookBundle that simply packages up encoder_hook and decoder_hook Callables into a single object.

• as_handler (bool) – A boolean controlling the return type of the decorator. If False, returns an IOLifter wrapping up f and the hook bundle specified by the supplied combination of encoder_hook, decoder_hook, and hook_bundle. If True, returns the result of applying lambda x: x.as_bytes_handler() to the IOLifter.

Returns:

An IOLifter wrapping up f, encoder_hook, and decoder_hook with the machinery needed to convert arbitrary functions into bytes-handlers. If as_handler=True, returns the bytes-handler version of f.

Raises:

• ValueError – if user supplies wrong combination of encoder_hook, decoder_hook, and hook_bundle.

• TypeError – if hook_bundle is not coercible to SerdeHookBundle, or if encoder_hook/decoder_hook are not Callables.