• linux-64 v0.13.0

conda install

To install this package run one of the following:
conda install phygbu::py-ubjson

---

Overview

This is a Python v3.2+ (and 2.7+) Universal Binary JSON <http://ubjson.org>_ encoder/decoder based on the draft-12 <UBJSON-Specification.md>_ specification.

Installing / packaging

.. code:: shell

# To get from PyPI
pip3 install py-ubjson

# To only build extension modules inline (e.g. in repository)
python3 setup.py build_ext -i

# To build & install globally
python3 setup.py install

# To skip building of extensions when installing (or building)
PYUBJSON_NO_EXTENSION=1 python3 setup.py install

Notes

• The extension module is not required but provide a significant speed boost.
• The above can also be run with v2.7+
• This module is also available via Anaconda (conda-forge) <https://anaconda.org/conda-forge/py-ubjson>__
• PyPI releases are signed with the Iotic Labs Software release signing key <https://iotic-labs.com/iotic-labs.com.asc>__
• At run time, one can check whether compiled version is in use via the ubjson.EXTENSION_ENABLED boolean

Usage

It's meant to behave very much like Python's built-in JSON module <https://docs.python.org/3/library/json.html>__, e.g.:

.. code:: python

import ubjson

encoded = ubjson.dumpb({u'a': 1})

decoded = ubjson.loadb(encoded)

Note: Only unicode strings in Python 2 will be encoded as strings, plain str will be encoded as a byte array.

Documentation

.. code:: python

import ubsjon
help(ubjson.dump)
help(ubjson.load)

Command-line utility

This converts between JSON and UBJSON formats:

.. code:: shell

python3 -mubjson
USAGE: ubjson (fromjson|tojson) (INFILE|-) [OUTFILE]

Tests

Static

This library has been checked using flake8 <https://pypi.python.org/pypi/flake8>_ and pylint <http://www.pylint.org>_, using a modified configuration - see pylint.rc and flake8.cfg.

Unit

.. code:: shell

./coverage_test.sh

Note: This requires coverage <https://pypi.python.org/pypi/coverage>__.

Limitations

• The No-Op type is only supported by the decoder. (This should arguably be a protocol-level rather than serialisation-level option.) Specifically, it is only allowed to occur at the start or between elements of a container and only inside un-typed containers. (In a typed container it is impossible to tell the difference between an encoded element and a No-Op.)
• Strongly-typed containers are only supported by the decoder (apart from for bytes/bytearray) and not for No-Op.
• Encoder/decoder extensions are not supported at this time.

Why?

The only existing implementation I was aware of at the time of writing (simpleubjson <https://github.com/brainwater/simpleubjson>__) had the following limitations:

• Does not support efficient binary encoding
• Only supports draft-9
• Only supports individual Python types rather than anything implementing an interface (e.g. Mapping)
• Does not decode nested arrays or objects in expected form
• Lacks C extension speed-up