Serializers

Serializers specify how Python objects should be saved to disk and how files from disk should be read as Python objects.

Components of a serializer

A serializer is a Python object with the following methods.

vlermv.serializers.hypothetical_serializer.dump(obj, fp) → None

Write the object obj to the file pointer fp.

vlermv.serializers.hypothetical_serializer.load(fp) → obj

Represent the file pointer fp as an object obj.

It optionally includes two boolean properties.

vlermv.serializers.hypothetical_serializer.binary_mode

Should binary modes be used for opening file pointers? Default is False. If this is True, pointers will be opened like this.

open(filename, 'rb')
open(filename, 'wb')

If it is False, pointers will be opened like this.

open(filename, 'r')
open(filename, 'w')

vlermv.serializers.hypothetical_serializer.cache_exceptions

Is caching of exceptions is supported? Default is True. This is relevant when the serializer is used with memoize.

If vermv_cache_exceptions is False but Vlermv is initialized with cache_exceptions = True, an exception is raised.

What exactly is obj?

The obj that is referenced in the above function signatures is manipulated if you enable the caching of exceptions. (Exception caching is disabled by default.)

Default behavior

If Vlermv is initialized with cache_exceptions = False, obj is simply the object that was passed to vlermv.Vlermv.__setitem__. This is the default; in the following example obj is 8.

Vlermv('/tmp/a')['b'] = 8

And in the following case, obj is 103.

@Vlermv.memoize(cache_exceptions = False)
def f(x):
    return x + 3
f(100) # <- Returns 103

cache_exceptions is False by default, so the following block is the same as the previous one.

@cache()
def f(x):
    return x + 3
f(100) # <- Returns 103

If exception caching is enabled

You probably want to set cache_exceptions only if you are using the memoize decorator, as it doesn’t do anything otherwise.

If cache_exceptions is True, obj is a tuple of (exception, result), where result is the result of the decorated function. (If cache_exceptions is False, obj is simply result.)

exception is None if the function ran without error, and result is None if there was an error.

Consider the function g below.

@cache(cache_exceptions = True)
def g(x):
    return x + 3

It is just like the f we saw before except with exception caching enabled. If we call it like we called f before,

g(100) # returns 103

then obj is (None, 103). This is because the value 103 is returned without error.

The following g call, on the other hand, produces an error,

>>> g('one hundred')
TypeError: Can't convert 'int' object to str implicitly

In this case, obj looks like this.

(TypeError("Can't convert 'int' object to str implicitly"), None)

If exception caching had been disabled, the serializer would never have gotten called; the error would have been raised but not saved.

Example serializers

The json module is a valid serializer,

import json

and so is simple_identity.

class simple_identity:
    @staticmethod
    def dump(obj, fp):
        fp.write(obj)

    @staticmethod
    def load(fp):
        return fp.read()

    binary_mode = True
    cache_exceptions = False

On the other hand, pickle does not function properly as a serializer.

import pickle

This is because pickle requires that file pointers be opened in binary mode rather than string mode; the Vlermv’s default pickle serializer thus has to set binary_mode to True.

from pickle import load, dump
binary_mode = True

Serializers included with Vlermv

The following serializers are included.

vlermv.serializers.identity_str

Write raw strings to files.

vlermv.serializers.identity_bytes

Write raw bytes to files.

vlermv.serializers.pickle

Serialize with pickle.

vlermv.serializers.html

Serialize HTML trees from lxml.

vlermv.serializers.xml

Serialize XML etrees from lxml.