This module provides functions for encoding and decoding a lightweight text-based format for serializing the object types supported by UL4.
It is extensible to allow encoding/decoding arbitrary instances (i.e. it is
basically a reimplementation of pickle, but with string input/output
instead of bytes and with an eye towards cross-plattform support).
There are implementations for Python (this module), Java and Javascript (as part of the UL4 packages for those languages).
Furthermore there's an Oracle package that can be used for generating UL4on encoded data.
Basic usage follows the API design of pickle, json, etc. and
supports most builtin Python types:
>>> from ll import ul4on
>>> ul4on.dumps(None)
'n'
>>> ul4on.loads('n')
>>> ul4on.dumps(False)
'bF'
>>> ul4on.loads('bF')
False
>>> ul4on.dumps(42)
'i42'
>>> ul4on.loads('i42')
42
>>> ul4on.dumps(42.5)
'f42.5'
>>> ul4on.loads('f42.5')
42.5
>>> ul4on.dumps('foo')
"S'foo'"
>>> ul4on.loads("S'foo'")
'foo'datetime and timedelta objects are supported too:
>>> import datetime
>>> ul4on.dumps(datetime.datetime.now())
'Z i2014 i11 i3 i18 i16 i45 i314157'
>>> ul4on.loads('Z i2014 i11 i3 i18 i16 i45 i314157')
datetime.datetime(2014, 11, 3, 18, 16, 45, 314157)
>>> ul4on.dumps(datetime.timedelta(days=1))
'T i1 i0 i0'
>>> ul4on.loads('T i1 i0 i0')
datetime.timedelta(1)ll.ul4on also supports Color objects from ll.color:
>>> from ll import color
>>> ul4on.dumps(color.red)
'C i255 i0 i0 i255'
>>> ul4on.loads('C i255 i0 i0 i255')
Color(0xff, 0x00, 0x00)Lists, dictionaries and sets are also supported:
>>> ul4on.dumps([1, 2, 3])
'L i1 i2 i3 ]'
>>> ul4on.loads('L i1 i2 i3 ]')
[1, 2, 3]
>>> ul4on.dumps(dict(one=1, two=2))
"D S'two' i2 S'one' i1 }"
>>> ul4on.loads("D S'two' i2 S'one' i1 }")
{'one': 1, 'two': 2}
>>> ul4on.dumps({1, 2, 3})
'Y i1 i2 i3 }'
>>> ul4on.loads('Y i1 i2 i3 }')
{1, 2, 3}ll.ul4on can also handle recursive data structures:
>>> r = []
>>> r.append(r)
>>> ul4on.dumps(r)
'L ^0 ]'
>>> r2 = ul4on.loads('L ^0 ]')
>>> r2
[[...]]
>>> r2 is r2[0]
True
>>> r = {}
>>> r['recursive'] = r
>>> ul4on.dumps(r)
"D S'recursive' ^0 }"
>>> r2 = ul4on.loads("D S'recursive' ^0 }")
>>> r2
{'recursive': {...}}
>>> r2['recursive'] is r2
TrueUL4ON is extensible. It supports serializing arbitrary instances by registering the class with the UL4ON serialization machinery:
from ll import ul4on
@ul4on.register("com.example.person")
class Person:
def __init__(self, firstname=None, lastname=None):
self.firstname = firstname
self.lastname = lastname
def __repr__(self):
return "<Person firstname={!r} lastname={!r}>".format(self.firstname, self.lastname)
def ul4ondump(self, encoder):
encoder.dump(self.firstname)
encoder.dump(self.lastname)
def ul4onload(self, decoder):
self.firstname = decoder.load()
self.lastname = decoder.load()
jd = Person("John", "Doe")
output = ul4on.dumps(jd)
print("Dump:", output)
jd2 = ul4on.loads(output)
print("Loaded:", jd2)This script outputs:
Dump: O S'com.example.person' S'John' S'Doe' ) Loaded: <Person firstname='John' lastname='Doe'>
def register(name):
This decorator can be used to register the decorated class with the
ll.ul4on serialization machinery.
name must be a globally unique name for the class. To avoid
name collisions Java's class naming system should be used (i.e. an
inverted domain name like com.example.foo.bar).
name will be stored in the class attribute ul4onname.
class Encoder(object):
def __init__(self, stream, indent=None):
Create an encoder for serializing objects to self.stream.
stream must provide a write method.
def _record(self, obj):
def _line(self, line, *items):
def dump(self, obj):
Serialize obj as an UL4ON formatted stream.
class Decoder(object):
def __init__(self, stream):
Create a decoder for deserializing objects from self.stream.
stream must provide a read method.
def load(self):
Deserialize the next object in the stream and return it.
def _readint(self):
def _loading(self, obj):
def _nextchar(self, nextchar=None):
def _beginfakeloading(self):
def _endfakeloading(self, oldpos, value):
def _load(self, typecode):
class StreamBuffer(object):
def __init__(self, stream, bufsize=1048576):
def read(self, size):
def dumps(obj, indent=None):
Serialize obj as an UL4ON formatted string.
def dump(obj, stream, indent=None):
Serialize obj as an UL4ON formatted stream to stream.
stream must provide a write method.
def loadclob(clob, bufsize=1048576):
Deserialize clob (which must be an cx_Oracle CLOB variable
containing an UL4ON formatted object) to a Python object.
bufsize specifies the chunk size for reading the underlying CLOB
object.
def loads(string):
Deserialize string (which must be a string containing an UL4ON
formatted object) to a Python object.
def load(stream):
Deserialize stream (which must be file-like object with a read
method containing an UL4ON formatted object) to a Python object.