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 pointerfp
.
-
vlermv.serializers.hypothetical_serializer.
load
(fp) → obj¶ Represent the file pointer
fp
as an objectobj
.
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 isTrue
, 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')
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.