.. image:: https://github.com/agronholm/cbor2/actions/workflows/test.yml/badge.svg :target: https://github.com/agronholm/cbor2/actions/workflows/test.yml :alt: Testing Status .. image:: https://github.com/agronholm/cbor2/actions/workflows/publish.yml/badge.svg :target: https://github.com/agronholm/cbor2/actions/workflows/publish.yml :alt: Publish Status .. image:: https://coveralls.io/repos/github/agronholm/cbor2/badge.svg?branch=master :target: https://coveralls.io/github/agronholm/cbor2?branch=master :alt: Code Coverage .. image:: https://readthedocs.org/projects/cbor2/badge/?version=latest :target: https://cbor2.readthedocs.io/en/latest/?badge=latest :alt: Documentation Status
This library provides encoding and decoding for the Concise Binary Object Representation (CBOR)
(RFC 8949
) serialization format. The specification is fully compatible with the original RFC 7049.
Read the docs <https://cbor2.readthedocs.io/>
to learn more.
It is implemented in pure python with an optional C backend.
On PyPy, cbor2 runs with almost identical performance to the C backend.
.. _RFC 8949: https://www.rfc-editor.org/rfc/rfc8949.html
json
or pickle
modules.CBOR tags
with stdlib objects
.Shared value
_ references including cyclic references.String references
_ compact encoding with repeated strings replaced with indices.tagged value handling
_ using tag_hook
and object_hook
on decode and default
on encode.python -m cbor2.tool
(This is a lossy conversion, for diagnostics only).. _CBOR tags: https://www.iana.org/assignments/cbor-tags/cbor-tags.xhtml .. _stdlib objects: https://cbor2.readthedocs.io/en/latest/usage.html#tag-support .. _Shared value: http://cbor.schmorp.de/value-sharing .. _String references: http://cbor.schmorp.de/stringref .. _tagged value handling: https://cbor2.readthedocs.io/en/latest/customizing.html#using-the-cbor-tags-for-custom-types
::
pip install cbor2
PyPy3
_ 3.9+).. _PyPy3: https://www.pypy.org/
To force building of the optional C-extension, set OS env CBOR2_BUILD_C_EXTENSION=1
.
To disable building of the optional C-extension, set OS env CBOR2_BUILD_C_EXTENSION=0
.
If this environment variable is unset, setup.py will default to auto detecting a compatible C library and
attempt to compile the extension.
Basic Usage <https://cbor2.readthedocs.io/en/latest/usage.html#basic-usage>
_
The provided command line tool (cbor2
) converts CBOR data in raw binary or base64
encoding into a representation that allows printing as JSON. This is a lossy
transformation as each datatype is converted into something that can be represented as a
JSON value.
The tool can alternatively be invoked with python -m cbor2.tool
.
Usage::
# Pass hexadecimal through xxd.
$ echo a16568656c6c6f65776f726c64 | xxd -r -ps | cbor2 --pretty
{
"hello": "world"
}
# Decode Base64 directly
$ echo ggEC | python -m cbor2.tool --decode
[1, 2]
# Read from a file encoded in Base64
$ python -m cbor2.tool -d tests/examples.cbor.b64
{...}
It can be used in a pipeline with json processing tools like jq
_ to allow syntax
coloring, field extraction and more.
CBOR data items concatenated into a sequence can be decoded also::
$ echo ggECggMEggUG | cbor2 -d --sequence
[1, 2]
[3, 4]
[5, 6]
Multiple files can also be sent to a single output file::
$ cbor2 -o all_files.json file1.cbor file2.cbor ... fileN.cbor
.. _jq: https://stedolan.github.io/jq/
This library has not been tested against malicious input. In theory it should be
as safe as JSON, since unlike pickle
the decoder does not execute any code.