# ``twisted`.`spread`.`jelly``

module documentation
(source)

S-expression-based persistence of python objects.

It does something very much like `Pickle`; however, pickle's main goal seems to be efficiency (both in space and time); jelly's main goals are security, human readability, and portability to other environments.

This is how Jelly converts various objects to s-expressions.

Boolean:

        True --> ['boolean', 'true']

Integer:

        1 --> 1

List:

        [1, 2] --> ['list', 1, 2]

String:

        "hello" --> "hello"

Float:

        2.3 --> 2.3

Dictionary:

        {'a': 1, 'b': 'c'} --> ['dictionary', ['b', 'c'], ['a', 1]]

Module:

        UserString --> ['module', 'UserString']

Class:

        UserString.UserString --> ['class', ['module', 'UserString'], 'UserString']

Function:

        string.join --> ['function', 'join', ['module', 'string']]

Instance: s is an instance of UserString.UserString, with a __dict__ {'data': 'hello'}:

        ["UserString.UserString", ['dictionary', ['data', 'hello']]]

Class Method: UserString.UserString.center:

        ['method', 'center', ['None'], ['class', ['module', 'UserString'],
         'UserString']]

Instance Method: s.center, where s is an instance of UserString.UserString:

        ['method', 'center', ['instance', ['reference', 1, ['class',
        ['module', 'UserString'], 'UserString']], ['dictionary', ['data', 'd']]],
        ['dereference', 1]]

The Python 2.x `sets.Set` and `sets.ImmutableSet` classes are serialized to the same thing as the builtin `set` and `frozenset` classes. (This is only relevant if you are communicating with a version of jelly running on an older version of Python.)

Author
Glyph Lefkowitz

Class | `DummySecurityOptions` | DummySecurityOptions() -> insecure security options Dummy security options -- this class will allow anything.
Class | `InsecureJelly` | This exception will be raised when a jelly is deemed `insecure'; e.g. it contains a type, class, or module disallowed by the specified `taster'
Class | `Jellyable` | Inherit from me to Jelly yourself directly with the `getStateFor' convenience method.
Class | `SecurityOptions` | This will by default disallow everything, except for 'none'.
Class | `Unjellyable` | Inherit from me to Unjelly yourself directly with the `setStateFor` convenience method.
Class | `Unpersistable` | This is an instance of a class that comes back when something couldn't be unpersisted.
Function | `getInstanceState` | Utility method to default to 'normal' state rules in serialization.
Function | `jelly` | Serialize to s-expression.
Function | `setInstanceState` | Utility method to default to 'normal' state rules in unserialization.
Function | `setUnjellyableFactoryForClass` | Set the factory to construct a remote instance of a type:
Function | `setUnjellyableForClass` | Set which local class will represent a remote type.
Function | `setUnjellyableForClassTree` | Set all classes in a module derived from `baseClass` as copiers for a corresponding remote class.
Function | `unjelly` | Unserialize from s-expression.
Variable | `class_atom` | Undocumented
Variable | `dereference_atom` | Undocumented
Variable | `dictionary_atom` | Undocumented
Variable | `DictTypes` | Undocumented
Variable | `frozenset_atom` | Undocumented
Variable | `function_atom` | Undocumented
Variable | `globalSecurity` | Undocumented
Variable | `instance_atom` | Undocumented
Variable | `list_atom` | Undocumented
Variable | `module_atom` | Undocumented
Variable | `None_atom` | Undocumented
Variable | `persistent_atom` | Undocumented
Variable | `reference_atom` | Undocumented
Variable | `set_atom` | Undocumented
Variable | `tuple_atom` | Undocumented
Variable | `unjellyableFactoryRegistry` | Undocumented
Variable | `unjellyableRegistry` | Undocumented
Variable | `unpersistable_atom` | Undocumented
Class | `_Jellier` | (Internal) This class manages state for a call to jelly()
Class | `_Unjellier` | No class docstring; 0/5 instance variable, 8/29 methods documented
Function | `_createBlank` | Given an object, if that object is a type, return a new, blank instance of that type which has not had `__init__` called on it. If the object is not a type, return `None`.
Function | `_maybeClass` | Undocumented
Function | `_newInstance` | Make a new instance of a class without calling its __init__ method.

def getInstanceState(inst, jellier): (source)
Utility method to default to 'normal' state rules in serialization.
def jelly(object, taster=DummySecurityOptions(), persistentStore=None, invoker=None): (source)

Serialize to s-expression.

Returns a list which is the serialized representation of an object. An optional 'taster' argument takes a SecurityOptions and will mark any insecure objects as unpersistable rather than serializing them.

def setInstanceState(inst, unjellier, jellyList): (source)
Utility method to default to 'normal' state rules in unserialization.
def setUnjellyableFactoryForClass(classname, copyFactory): (source)

Set the factory to construct a remote instance of a type:

      jellier.setUnjellyableFactoryForClass('module.package.Class', MyFactory)

Call this at the module level immediately after its class definition. `copyFactory` should return an instance or subclass of `RemoteCopy`.

Similar to `setUnjellyableForClass` except it uses a factory instead of creating an instance.

def setUnjellyableForClass(classname, unjellyable): (source)

Set which local class will represent a remote type.

If you have written a Copyable class that you expect your client to be receiving, write a local "copy" class to represent it, then call:

        jellier.setUnjellyableForClass('module.package.Class', MyCopier).

Call this at the module level immediately after its class definition. MyCopier should be a subclass of RemoteCopy.

The classname may be a special tag returned by 'Copyable.getTypeToCopyFor' rather than an actual classname.

This call is also for cached classes, since there will be no overlap. The rules are the same.

def setUnjellyableForClassTree(module, baseClass, prefix=None): (source)

Set all classes in a module derived from `baseClass` as copiers for a corresponding remote class.

When you have a hierarchy of Copyable (or Cacheable) classes on one side, and a mirror structure of Copied (or RemoteCache) classes on the other, use this to setUnjellyableForClass all your Copieds for the Copyables.

Each copyTag (the "classname" argument to getTypeToCopyFor, and what the Copyable's getTypeToCopyFor returns) is formed from adding a prefix to the Copied's class name. The prefix defaults to module.__name__. If you wish the copy tag to consist of solely the classname, pass the empty string ''.

Parameters
module | a module object from which to pull the Copied classes. (passing sys.modules[__name__] might be useful)
baseClass | the base class from which all your Copied classes derive.
prefix | the string prefixed to classnames to form the unjellyableRegistry.

def unjelly(sexp, taster=DummySecurityOptions(), persistentLoad=None, invoker=None): (source)

Unserialize from s-expression.

Takes a list that was the result from a call to jelly() and unserializes an arbitrary object from it. The optional 'taster' argument, an instance of SecurityOptions, will cause an InsecureJelly exception to be raised if a disallowed type, module, or class attempted to unserialize.

class_atom: `bytes` = (source)

Undocumented

dereference_atom: `bytes` = (source)

Undocumented

dictionary_atom: `bytes` = (source)

Undocumented

DictTypes = (source)

Undocumented

frozenset_atom: `bytes` = (source)

Undocumented

function_atom: `bytes` = (source)

Undocumented

globalSecurity = (source)

Undocumented

instance_atom: `bytes` = (source)

Undocumented

list_atom: `bytes` = (source)

Undocumented

module_atom: `bytes` = (source)

Undocumented

None_atom: `bytes` = (source)

Undocumented

persistent_atom: `bytes` = (source)

Undocumented

reference_atom: `bytes` = (source)

Undocumented

set_atom: `bytes` = (source)

Undocumented

tuple_atom: `bytes` = (source)

Undocumented

unjellyableFactoryRegistry: `dict` = (source)

Undocumented

unjellyableRegistry: `dict` = (source)

Undocumented

unpersistable_atom: `bytes` = (source)

Undocumented

def _createBlank(cls): (source)
Given an object, if that object is a type, return a new, blank instance of that type which has not had `__init__` called on it. If the object is not a type, return `None`.

Parameters
cls:`type` or something else that cannot be instantiated. | The type (or class) to create an instance of.
Returns
a new blank instance or `None` if `cls` is not a class or type.

def _maybeClass(classnamep): (source)

Undocumented

def _newInstance(cls, state): (source)
Make a new instance of a class without calling its __init__ method.

Parameters
state | A `dict` used to update `inst.__dict__` either directly or via `__setstate__`, if available.
Returns
A new instance of `cls`.