Home

Awesome

Pickle - Java and .NET library for Python's pickle serialization protocol

Maven Central NuGet

Pickle is written by Irmen de Jong (irmen@razorvine.net). This software is distributed under the terms written in the file LICENSE.

The pickle serialization protocol

This is a feature complete pickle protocol implementation. You can read and write pickle files. Pickle is Python's serialization protocol.

Pickle protocol version support: reading: 0,1,2,3,4,5; writing: 2. We can read all pickle protocol versions (0 to 5, so this includes the latest additions made in Python 3.8 related to out-of-band buffers). We always writes pickles in protocol version 2. There are no plans on including protocol version 1 support. Protocols 3 and 4 contain some nice new features which may eventually be utilized (protocol 5 is quite obscure), but for now, only version 2 is used.

Size limitations

Unlike Python where the length of strings and (byte)arrays is only limited by the available memory, Java and .NET do have an arbitrary maximum object size. The maximum length of strings and byte arrays of both platforms is limited to 2 gigabytes (2^31 - 1). This is not a Pickle library limitation, this is a limitation of the underlying platform. If an object in your pickle exceeds this limit the code will crash with something like an NegativeArraySizeException, OverflowException or perhaps an out of memory error of some sort. You should make sure in your own code that the size of the pickled objects does not exceed 2 gigabyte.

Type Mapping

Python to Java (unpickling)

The Unpickler simply returns an Object. Because Java is a statically typed language you will have to cast that to the appropriate type. Refer to this table to see what you can expect to receive.

PYTHONJAVA
Nonenull
boolboolean
intint
longlong or BigInteger (depending on size)
stringString
unicodeString
complexnet.razorvine.pickle.objects.ComplexNumber
datetime.datejava.util.Calendar
datetime.datetimejava.util.Calendar
datetime.timenet.razorvine.pickle.objects.Time
datetime.timedeltanet.razorvine.pickle.objects.TimeDelta
floatdouble (float isn't used)
array.arrayarray of appropriate primitive type (char, int, short, long, float, double)
listjava.util.List<Object>
tupleObject[]
setjava.util.Set
dictjava.util.Map
bytesbyte[]
bytearraybyte[]
decimalBigDecimal (except NaN which is mapped to Double.NaN)
custom classMap<String, Object> (dict with class attributes including its name in "class")
Pyro4.core.URInet.razorvine.pyro.PyroURI
Pyro4.core.Proxynet.razorvine.pyro.PyroProxy
Pyro4.errors.*net.razorvine.pyro.PyroException
Pyro4.utils.flame.FlameBuiltinnet.razorvine.pyro.FlameBuiltin
Pyro4.utils.flame.FlameModulenet.razorvine.pyro.FlameModule
Pyro4.utils.flame.RemoteInteractiveConsolenet.razorvine.pyro.FlameRemoteConsole

Java to Python (pickling)

JAVAPYTHON
nullNone
booleanbool
byteint
charstr/unicode (length 1)
Stringstr/unicode
doublefloat
floatfloat
intint
shortint
BigDecimaldecimal
BigIntegerlong
any arrayarray if elements are primitive type (else tuple)
Object[]tuple (cannot contain self-references)
byte[]bytearray
java.util.Datedatetime.datetime
java.util.Calendardatetime.datetime
java.sql.Datedatetime.date
java.sql.Timedatetime.time
java.sql.Timestampdatetime.datetime
Enumthe enum value as string
java.util.Setset
Map, Hashtabledict
Vector, Collectionlist
Serializabletreated as a JavaBean, see below.
JavaBeandict of the bean's public properties + __class__ for the bean's type.
net.razorvine.pyro.PyroURIPyro4.core.URI
net.razorvine.pyro.PyroProxycannot be pickled.

Python to .NET (unpickling)

The unpickler simply returns an object. In the case of C#, that is a statically typed language so you will have to cast that to the appropriate type. Refer to this table to see what you can expect to receive. Tip: you can use the 'dynamic' type in some places to avoid excessive type casting.

PYTHON.NET
Nonenull
boolbool
intint
longlong (c# doesn't have BigInteger so there's a limit on the size)
stringstring
unicodestring
complexRazorvine.Pickle.Objects.ComplexNumber
datetime.dateDateTime
datetime.datetimeDateTime
datetime.timeTimeSpan
datetime.timedeltaTimeSpan
floatdouble
array.arrayarray (all kinds of element types supported)
listArrayList (of objects)
tupleobject[]
setHashSet<object>
dictHashtable (key=object, value=object)
bytesubyte[]
bytearrayubyte[]
decimaldecimal (except NaN which is mapped to double.NaN)
custom classIDictionary<string, object> (dict with class attributes including its name in "class")
Pyro4.core.URIRazorvine.Pyro.PyroURI
Pyro4.core.ProxyRazorvine.Pyro.PyroProxy
Pyro4.errors.*Razorvine.Pyro.PyroException
Pyro4.utils.flame.FlameBuiltinRazorvine.Pyro.FlameBuiltin
Pyro4.utils.flame.FlameModuleRazorvine.Pyro.FlameModule
Pyro4.utils.flame.RemoteInteractiveConsoleRazorvine.Pyro.FlameRemoteConsole

.NET to Python (pickling)

.NETPYTHON
nullNone
booleanbool
bytebyte
sbyteint
charstr/unicode (length 1)
stringstr/unicode
doublefloat
floatfloat
int/short/sbyteint
uint/ushort/byteint
decimaldecimal
byte[]bytearray
primitivetype[]array
object[]tuple (cannot contain self-references)
DateTimedatetime.datetime
TimeSpandatetime.timedelta
Enumjust the enum value as string
HashSetset
Map, Hashtabledict
Collectionlist
Enumerablelist
object with public propertiesdictionary of those properties + class
anonymous class typedictonary of the public properties
Razorvine.Pyro.PyroURIPyro4.core.URI
Razorvine.Pyro.PyroProxycannot be pickled.