https://github.com/msiemens/tinydb-serialization

Serialization for objects which TinyDB couldn't handle otherwise
https://github.com/msiemens/tinydb-serialization

Last synced: 7 days ago
JSON representation

Serialization for objects which TinyDB couldn't handle otherwise

• Host: GitHub
• URL: https://github.com/msiemens/tinydb-serialization
• Owner: msiemens
• License: mit
• Created: 2015-09-27T13:00:15.000Z (about 9 years ago)
• Default Branch: master
• Last Pushed: 2024-10-05T18:56:50.000Z (29 days ago)
• Last Synced: 2024-10-14T21:09:19.013Z (20 days ago)
• Language: Python
• Size: 80.1 KB
• Stars: 53
• Watchers: 5
• Forks: 17
• Open Issues: 1
• Metadata Files:
  • Readme: README.rst
  • License: LICENSE

Awesome Lists containing this project

README

        
tinydb-serialization

^^^^^^^^^^^^^^^^^^^^

|Build Status| |Coverage| |Version|

``tinydb-serialization`` provides serialization for objects that TinyDB

otherwise couldn't handle.

Usage

*****

General Usage

-------------

To use a serializer, create a ``SerializationMiddleware`` instance with

the storage class you want to use and register the serializers you want

to use. Then you pass the middleware instance as the storage to TinyDB:

.. code-block:: python

    >>> from tinydb import TinyDB, Query

    >>> from tinydb.storages import JSONStorage

    >>> from tinydb_serialization import SerializationMiddleware

    >>> from tinydb_serialization.serializers import DateTimeSerializer

    >>>

    >>> from datetime import datetime

    >>>

    >>> serialization = SerializationMiddleware(JSONStorage)

    >>> serialization.register_serializer(DateTimeSerializer(), 'TinyDate')

    >>>

    >>> db = TinyDB('db.json', storage=serialization)

    >>> db.insert({'date': datetime(2000, 1, 1, 12, 0, 0)})

    >>> db.all()

    [{'date': datetime.datetime(2000, 1, 1, 12, 0)}]

    >>> query = Query()

    >>> db.insert({'date': datetime(2010, 1, 1, 12, 0, 0)})

    >>> db.search(query.date > datetime(2005, 1, 1))

    [{'date': datetime.datetime(2010, 1, 1, 12, 0)}]

**Important:** A ``SerializationMiddleware`` instance always wraps a database's storage.

This means that the ``SerializationMiddleware`` instance **cannot** be shared

between multiple ``TinyDB`` instances as they would use the same underlying storage

instance and thus share all data between both instances.

Provided Serializers

--------------------

- ``tinydb_serialization.serializers.DateTimeSerializer``: serializes ``datetime`` objects

  as ISO 8601 formatted strings

- ``tinydb_serialization.serializers.DateSerializer``: serializes ``date`` objects

  as ISO 8601 formatted strings

Creating Custom Serializers

---------------------------

In this example we implement a serializer for ``datetime`` objects (like the one provided

by this package):

.. code-block:: python

    from datetime import datetime

    from tinydb_serialization import Serializer

    class DateTimeSerializer(Serializer):

        OBJ_CLASS = datetime  # The class this serializer handles

        def encode(self, obj):

            return obj.isoformat()

        def decode(self, s):

            return datetime.fromisoformat(s)

Changelog

*********

**v2.2.0** (2024-10-05)

-----------------------

- Include the ``DateSerializer`` in this package (see `issue #16 `_)

**v2.1.1** (2023-07-24)

-----------------------

- Fix VSCode Pylance type error (see `pull request #14 `_)

- Add support for storages that encode as binary strings (see `pull request #17 `_)

- Drop Python 3.7 support

**v2.1.0** (2021-01-23)

-----------------------

- Include the ``DateTimeSerializer`` in this package (see `issue #10 `_)

- Drop Python 3.6 support (as 3.7 is needed for date parsing)

**v2.0.0** (2020-05-26)

-----------------------

- Add TinyDB v4.0.0 support (see `pull request #9 `_)

**v1.0.4** (2017-03-27)

-----------------------

- Don't modify the original element if it contains a list (see

  `pull request #5 `_)

**v1.0.3** (2016-02-11)

-----------------------

- Handle nested data (nested dicts, lists) properly when serializing/deserializing (see

  `pull request #3 `_)

**v1.0.2** (2016-01-04)

-----------------------

- Don't destroy original data when serializing (see

  `pull request #2 `_)

**v1.0.1** (2015-11-17)

-----------------------

- Fix installation via pip (see `issue #1 `_)

**v1.0.0** (2015-09-27)

-----------------------

- Initial release on PyPI

.. |Build Status| image:: https://img.shields.io/github/actions/workflow/status/msiemens/tinydb-serialization/ci-workflow.yml?style=flat-square

   :target: https://github.com/msiemens/tinydb-serialization/actions?query=workflow%3A%22Python+CI%22

.. |Coverage| image:: https://img.shields.io/coveralls/msiemens/tinydb-serialization.svg?style=flat-square

   :target: https://coveralls.io/r/msiemens/tinydb-serialization

.. |Version| image:: https://img.shields.io/pypi/v/tinydb-serialization.svg?style=flat-square

   :target: https://pypi.python.org/pypi/tinydb-serialization/