# evennia.utils.dbserialize

This module handles serialization of arbitrary python structural data, intended primarily to be stored in the database. It also supports storing Django model instances (which plain pickle cannot do).

This serialization is used internally by the server, notably for storing data in Attributes and for piping data to process pools.

The purpose of dbserialize is to handle all forms of data. For well-structured non-arbitrary exchange, such as communicating with a rich web client, a simpler JSON serialization makes more sense.

This module also implements the SaverList, SaverDict and SaverSet classes. These are iterables that track their position in a nested structure and makes sure to send updates up to their root. This is used by Attributes - without it, one would not be able to update mutables in-situ, e.g obj.db.mynestedlist[3][5] = 3 would never be saved and be out of sync with the database.

`evennia.utils.dbserialize.``to_pickle`(data)

  This prepares data on arbitrary form to be pickled. It handles any nested structure and returns data on a form that is safe to pickle (including having converted any database models to their internal representation). We also convert any Saver*-type objects back to their normal representations, they are not pickle-safe.

  Parameters

    data (any) – Data to pickle.

  Returns

    data (any) – Pickled data.

`evennia.utils.dbserialize.``from_pickle`(data, db_obj=None)

  This should be fed a just de-pickled data object. It will be converted back to a form that may contain database objects again. Note that if a database object was removed (or changed in-place) in the database, None will be returned.

  Parameters

    - data (any) – Pickled data to unpickle.

    - db_obj (Atribute, any) – This is the model instance (normally an Attribute) that _Saver*-type iterables (_SaverList etc) will save to when they update. It must have a ‘value’ property that saves assigned data to the database. Skip if not serializing onto a given object. If db_obj is given, this function will convert lists, dicts and sets to their _SaverList, _SaverDict and _SaverSet counterparts.

  Returns

    data (any) – Unpickled data.

`evennia.utils.dbserialize.``do_pickle`(data)

  Perform pickle to string

`evennia.utils.dbserialize.``do_unpickle`(data)

  Retrieve pickle from pickled string

`evennia.utils.dbserialize.``dbserialize`(data)

  Serialize to pickled form in one step

`evennia.utils.dbserialize.``dbunserialize`(data, db_obj=None)

  Un-serialize in one step. See from_pickle for help db_obj.