https://github.com/jayclassless/basicserial

A convenience wrapper around serialization libraries to handle common tasks.
https://github.com/jayclassless/basicserial

json python serialization toml yaml

Last synced: 2 days ago
JSON representation

A convenience wrapper around serialization libraries to handle common tasks.

• Host: GitHub
• URL: https://github.com/jayclassless/basicserial
• Owner: jayclassless
• License: mit
• Created: 2018-06-09T15:23:26.000Z (over 6 years ago)
• Default Branch: master
• Last Pushed: 2022-10-30T01:02:51.000Z (about 2 years ago)
• Last Synced: 2024-12-17T17:13:17.866Z (about 1 month ago)
• Topics: json, python, serialization, toml, yaml
• Language: Python
• Size: 51.8 KB
• Stars: 2
• Watchers: 3
• Forks: 0
• Open Issues: 0
• Metadata Files:
  • Readme: README.rst
  • Changelog: CHANGES.rst
  • License: LICENSE.rst

Awesome Lists containing this project

README

        
***********

basicserial

***********

.. image:: https://img.shields.io/pypi/v/basicserial.svg

   :target: https://pypi.python.org/pypi/basicserial

.. image:: https://img.shields.io/pypi/l/basicserial.svg

   :target: https://pypi.python.org/pypi/basicserial

.. image:: https://github.com/jayclassless/basicserial/workflows/Test/badge.svg

   :target: https://github.com/jayclassless/basicserial/actions

.. contents:: Contents

Overview

========

Does this look familiar?

::

    >>> import json

    >>> from datetime import date

    >>> MY_DATA = {'foo': 123, 'bar': date(2018, 5, 22)}

    >>> json.dumps(MY_DATA)

    Traceback (most recent call last):

        ...

    TypeError: datetime.date(2018, 5, 22) is not JSON serializable

It's one thing when your serialization tools don't know how to handle your

custom classes, but it's annoying when they don't handle the built-in and/or

common data types. Thus, ``basicserial`` was born.

This package is a thin wrapper around the common serialization tools that can

do the following for you when working with JSON, YAML, and TOML:

* Automatically serializes the following types to common-sense representations:

  .. list-table::

     :header-rows: 1

     * - Type

       - JSON

       - YAML

       - TOML

     * - `set `_

       - array

       - sequence

       - array

     * - `frozenset `_

       - array

       - sequence

       - array

     * - `Decimal `_

       - number

       - float

       - float

     * - `Fraction `_

       - string

       - string

       - string

     * - `date `_

       - string (ISO 8601)

       - timestamp

       - string (ISO 8601)

     * - `time `_

       - string (ISO 8601)

       - string (ISO 8601)

       - string (ISO 8601)

     * - `datetime `_

       - string (ISO 8601)

       - timestamp

       - string (ISO 8601)

     * - `complex `_

       - string

       - string

       - string

     * - `OrderedDict `_

       - object

       - map

       - key/value

     * - `defaultdict `_

       - object

       - map

       - key/value

     * - `namedtuple `_

       - object

       - map

       - key/value

     * - `UserDict `_

       - object

       - map

       - key/value

     * - `UserList `_

       - array

       - sequence

       - array

     * - `UserString `_

       - string

       - string

       - string

     * - `UUID `_

       - string

       - string

       - string

* Can serialize `Enum `_ members

  appropriately based on their type.

* Can automatically deserialize dates, times, and datetimes into the native

  Python objects.

* Provides a simple flag for generating "pretty" strings.

Usage

=====

To use this package, install it from PyPI (``pip install basicserial``). Then,

make sure you install the serialization package you'd like ``basicserial`` to

use:

* For YAML, it supports `PyYAML `_ and

  `ruamel.yaml `_.

* For TOML, it supports `toml `_, `pytoml

  `_, `qtoml

  `_, `tomlkit

  `_, and `tomli

  `_/`tomli-w `_.

* For JSON, it supports Python's built-in `json

  `_ module, `simplejson

  `_, `orjson

  `_, `rapidjson

  `_, `ujson

  `_, `hyperjson

  `_, and `pysimdjson

  `_.

``basicserial`` will automatically find a package to use, but if you want to

use a specific one, you can specify its name via the ``pkg`` argument to the

functions.

JSON::

    >>> print(basicserial.to_json(MY_DATA))

    {"foo": 123, "bar": "2018-05-22"}

    >>> print(basicserial.to_json(MY_DATA, pretty=True))

    {

      "foo": 123,

      "bar": "2018-05-22"

    }

    >>> basicserial.from_json(basicserial.to_json(MY_DATA))

    {u'foo': 123, u'bar': datetime.date(2018, 5, 22)}

    >>> basicserial.from_json(basicserial.to_json(MY_DATA), native_datetimes=False)

    {u'foo': 123, u'bar': u'2018-05-22'}

YAML::

    >>> print(basicserial.to_yaml(MY_DATA))

    {bar: 2018-05-22, foo: 123}

    >>> print(basicserial.to_yaml(MY_DATA, pretty=True))

    bar: 2018-05-22

    foo: 123

    >>> basicserial.from_yaml(basicserial.to_yaml(MY_DATA))

    {u'foo': 123, u'bar': datetime.date(2018, 5, 22)}

    >>> basicserial.from_yaml(basicserial.to_yaml(MY_DATA), native_datetimes=False)

    {'foo': 123, 'bar': u'2018-05-22'}

TOML::

    >>> print(basicserial.to_toml(MY_DATA))

    foo = 123

    bar = "2018-05-22"

    >>> print(basicserial.to_toml(MY_DATA, pretty=True))

    foo = 123

    bar = "2018-05-22"

    >>> basicserial.from_toml(basicserial.to_toml(MY_DATA))

    {u'foo': 123, u'bar': datetime.date(2018, 5, 22)}

    >>> basicserial.from_toml(basicserial.to_toml(MY_DATA), native_datetimes=False)

    {u'foo': 123, u'bar': u'2018-05-22'}

License

=======

This project is released under the terms of the `MIT License`_.

.. _MIT License: https://opensource.org/licenses/MIT