Module brine

Brine provides a way to wrap function objects so that they may be pickled.

To truly pickle a function we need to be able to duplicate its code and its closures. By default, pickle will simply store the function’s name, and then attempt to associate that with a function when unpickling. This of course fails when the function is a lambda or not otherwise defined at the top level.

In order to mark a function, method, or partial for storage, use the brine function to create a wrapper. Later, after pickling and unpickling the wrapper, call unbrine to get a new copy of the original function.

Loading this module has the side effect of registering a pickle handler for the CellType and CodeType types. This should be of low impact, as the only place these types are used is within function instances, and are typically unexposed.

author:Christopher O’Brien <obriencj@gmail.com> license:LGPL v.3

Functions

brine.brine(value)

Wrap an object so that it may be pickled. Behavior by type of value is as follows:

• builtin_function_or_method is unchanged
• partial is wrapped as a BrinedPartial
• instancemethod is wrapped as a BrinedMethod
• function is wrapped as a BrinedFunction
• list and tuple are duplicated and contents are brined
• dict is duplicated and its values are brined
• all other types are returned unchanged

This function provides neither caching nor preservation of uniqueness – if the same function is in a list multiple times, each will be wrapped individually and as a result will be duplicated when unbrined.

In cases where uniqueness needs to be preserved, use a Barrel instead.

Also, if a brined function refers to other functions in its closure cells, they will not be brined. Use a Barrel for those cases as well.

Parameters:

value : object

object to be brined for pickling

Returns:

wrapped : object

as defined by the value parameter

brine.unbrine(value, with_globals=None)

Unwrap a value previously wrapped with the brine function. Behavior by type of value is as follows:

• BrinedPartial unwraps to a partial
• BrinedMethod unwraps to a instancemethod
• BrinedFunction unwraps to a function
• list and tuple are duplicated and contents unbrined
• dict is duplicated and its values are unbrined

Parameters:

value : object

value to be unbrined

with_globals : dict or None

globals dictionary to use when recreating functions. None is the same as globals()

Returns:

unwrapped : object

as defined by the type of value

Wrapper Classes

class brine.BrinedObject(value)

Abstract base class for brine wrappers. Defines the interface required for brine.

• When instantiated, should accept a value to wrap
• The get method should return a new copy of the wrapped value
• Must define the __getstate__ and __setstate__ methods for pickle support.

__init__(value)

Wrap value so that it may be pickled.

Parameters:

value : object

the instance needing to be wrapped for pickling

__getstate__()

Special method used by a pickle.Pickler to serialize an instance of this class.

Returns:

data : tuple

information to provide to the pickle API. Should be the same as what is expected in the __setstate__ method

__setstate__(data)

Special method used by a pickle.Unpickler to deserialize an instance of this class. Should accept the same data returned by the __getstate__ method

Parameters:

data : tuple

information provided by the pickle API to instantiate a new copy

get(with_globals)

Recreate a copy of the initial brined value

Parameters:

with_globals : globals() or dict-like

The global namespace to be used when recreating the value.

Returns:

value : object

A copy of the value originally passed to __init__

class brine.BrinedFunction(function)

Bases: brine.BrinedObject

Wraps a function so that it may be pickled. For the most part you’ll want to use the brine and unbrine functions from this module rather than instantiating or accessing this class directly

class brine.BrinedMethod(boundmethod)

Bases: brine.BrinedObject

Wraps a bound method so that it can be pickled. By default pickle refuses to operate on bound instance method object. This wrapper will still require that the object instance supports pickling, which in turn requires that the class be defined at the top level. As with the BrineFunction class, it is better to use the brine and unbrine functions from this module rather than to create an instance of this class directly.

class brine.BrinedPartial(part)

Bases: brine.BrinedObject

Wrap a functools.partial instance that references a function or method that is otherwise unsupported by pickle.

See Also

pickle, functools.partial()