Metadata-Version: 1.1
Name: Serialize
Version: 0.1
Summary: A common API for multiple serialization formats with support for custom classes
Home-page: https://github.com/hgrecco/serialize
Author: Hernan E. Grecco
Author-email: hernan.grecco@gmail.com
License: BSD
Description: Serialize: A common Python API for multiple serialization formats
        =================================================================
        
        There are multiple serialization formats out there ...
        
                                ... and great packages to use them.
        
        But they all have a different API and switching among them is not so simple
        as it should be. Serialize helps you to do it, including dealing with custom
        classes. Let's dump a dict using the `pickle` format:
        
        .. code-block:: python
        
            >>> from serialize import dumps, loads
            >>> dumps(dict(answer=42), fmt='pickle')
            b'\x80\x03}q\x00X\x06\x00\x00\x00answerq\x01K*s.'
            >>> loads(_, fmt='pickle')
            {'answer': 42}
        
        And here comes the cool thing, you can just change the serialization format
        without having to learn a new API. Let's now dump it using msgpack:
        
        .. code-block:: python
        
            >>> dumps(dict(answer=42), fmt='msgpack')
            b'\x81\xa6answer*'
            >>> loads(_, fmt='msgpack')
            {'answer': 42}
        
        Serialize currently support 8 different formats: `bson`, `dill`, `json`, `msgpack`,
        `phpserialize`, `pickle`, `serpent` and `yaml`. Serialize does not implement these
        formats but rather relies on established, well tested packages. If they are installed,
        serialize will use them.
        
             ** Serialize allows you to use them all with the same API! **
        
        You can also use the `dump` and `load` to write directly to file-like object:
        
        .. code-block:: python
        
            >>> from serialize import dump, load
            >>> with open('output.yaml', 'wb') as fp:
            ...     dump(dict(answer=42), fp, fmt='yaml')
            >>> with open('output.yaml', 'rb') as fp:
            ...     load(fp, fmt='yaml')
            {'answer': 42}
        
        or use directly the filename and the format will be inferred:
        
        .. code-block:: python
        
            >>> dump(dict(answer=42), 'output.yaml')
            >>> load('output.yaml')
            {'answer': 42}
        
        A very common case is to dump and load objects from custom classes such as:
        
        .. code-block:: python
        
            >>> class User:
            ...     def __init__(self, name, age):
            ...         self.name = name
            ...         self.age = age
            ...
            >>> john = User('John Smith', 27)
        
        
        But some serialization packages do not support this important feature and the
        rest usually have very different API between them. Serialize provides
        you a common, simple interface for this. You just need to define a function
        that is able to convert the object to an instance of a builtin type and the
        converse:
        
        .. code-block:: python
        
            >>> from serialize import register_class
            >>> def user_to_builtin(u):
            ...     return (u.name, u.age)
            ...
            >>> def user_from_builtin(c):
            ...     return User(c[0], c[1])
            ...
        
            >>> register_class(User, user_to_builtin, user_from_builtin)
        
        
        And that's all. You can then use it directly without any hassle:
        
        .. code-block:: python
        
            >>> dumps(john, fmt='bson')
            b"y\x00\x00\x00\x03__bson_follow__\x00c\x00\x00\x00\x04__dumped_obj__
            \x00\x1e\x00\x00\x00\x020\x00\x0b\x00\x00\x00John Smith\x00\x101\x00
            \x1b\x00\x00\x00\x00\x02__class_name__\x00\x1c\x00\x00\x00<class '__m
            ain__.Username'>\x00\x00\x00"
            >>> v = loads(_, fmt='bson')
            >>> v.name
            'John Smith'
            >>> v.age
            27
        
        
        Enjoy!
        
        
        
        Serialize is written and maintained by Hernan E. Grecco <hernan.grecco@gmail.com>.
        
        
        Serialize Changelog
        ===================
        
        
        0.1 (2016-01-28)
        ----------------
        - Initial Release. Implement a generic dump/dumps and load/loads.
        - Added support for registering new serializer/deserializer.
        - Added support for registering custom classes.
        - Format inference for file extension.
        - Added support for bson using https://pypi.python.org/pypi/bson
        - Added support for dill using https://pypi.python.org/pypi/dill
        - Added support for json using https://docs.python.org/3/library/json.html
        - Added support for msgpack using https://pypi.python.org/pypi/msgpack-python
        - Added support for phpserialize using https://pypi.python.org/pypi/phpserialize
        - Added support for pickle using https://docs.python.org/3/library/pickle.html
        - Added support for serpent using https://pypi.python.org/pypi/serpent
        - Added support for yaml using https://pypi.python.org/pypi/pyyaml
        
        
        
Keywords: serialization deserialization packing unpacking
Platform: UNKNOWN
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: End Users/Desktop
Classifier: License :: OSI Approved :: BSD License
Classifier: Operating System :: MacOS :: MacOS X
Classifier: Operating System :: Microsoft :: Windows
Classifier: Operating System :: POSIX
Classifier: Programming Language :: Python
Classifier: Topic :: Software Development :: Libraries
Classifier: Programming Language :: Python :: 3.3
Classifier: Programming Language :: Python :: 3.4
Classifier: Programming Language :: Python :: 3.5
