Canonical JSON
Find a file
Repository files (latest commit first)
Filename Latest commit message Latest commit date
2026-05-06 14:54:41 +00:00
.github Update and pin GitHub Actions; stop testing EOL Python 3.7-3.9 in CI (#65) 2026-05-06 14:54:41 +00:00
src/canonicaljson Various clean-ups. (#61) 2023-03-16 09:08:21 -04:00
tests Various clean-ups. (#61) 2023-03-16 09:08:21 -04:00
.gitignore Add an API to choose the underlying JSON library. (#25) 2020-07-27 09:52:15 -04:00
CHANGES.md Bump version to 2.0.0 2023-03-15 01:32:42 +00:00
LICENSE A Canonical JSON encoder 2015-08-21 18:58:30 +01:00
MANIFEST.in Properly package the canonicaljson module (#52) 2022-09-23 16:59:39 +02:00
pyproject.toml Remove unused setuptools_scm build requirement (#54) 2022-11-04 17:22:17 +00:00
README.rst Various clean-ups. (#61) 2023-03-16 09:08:21 -04:00
releasing.md Delete .egg-info when releasing 2022-09-23 16:09:36 +01:00
setup.cfg Various clean-ups. (#61) 2023-03-16 09:08:21 -04:00
tox.ini Update and pin GitHub Actions; stop testing EOL Python 3.7-3.9 in CI (#65) 2026-05-06 14:54:41 +00:00

Canonical JSON
==============

.. image:: https://img.shields.io/pypi/v/canonicaljson.svg
    :target: https://pypi.python.org/pypi/canonicaljson/
    :alt: Latest Version

Features
--------

* Encodes objects and arrays as `RFC 7159`_ JSON.
* Sorts object keys so that you get the same result each time.
* Has no insignificant whitespace to make the output as small as possible.
* Escapes only the characters that must be escaped, U+0000 to U+0019 / U+0022 /
  U+0056, to keep the output as small as possible.
* Uses the shortest escape sequence for each escaped character.
* Encodes the JSON as UTF-8.
* Can be configured to encode custom types unknown to the stdlib JSON encoder.

Supports Python versions 3.7 and newer.

.. _`RFC 7159`: https://tools.ietf.org/html/rfc7159

Installing
----------

.. code:: bash

   pip install canonicaljson

Using
-----

To encode an object into the canonicaljson:

.. code:: python

    import canonicaljson
    assert canonicaljson.encode_canonical_json({}) == b'{}'

There's also an iterator version:

.. code:: python

    import canonicaljson
    assert b''.join(canonicaljson.iterencode_canonical_json({})) == b'{}'

A preserialisation hook allows you to encode objects which aren't encodable by the
standard library ``JSONEncoder``.

.. code:: python

    import canonicaljson
    from typing import Dict

    class CustomType:
        pass

    def callback(c: CustomType) -> Dict[str, str]:
        return {"Hello": "world!"}

    canonicaljson.register_preserialisation_callback(CustomType, callback)
    assert canonicaljson.encode_canonical_json(CustomType()) == b'{"Hello":"world!"}'