Metadata-Version: 2.4
Name: cbor2
Version: 6.3.0
Summary: CBOR (de)serializer with extensive tag support
Author-email: Alex Grönholm <alex.gronholm@nextday.fi>
License-Expression: MIT
Project-URL: Changelog, https://cbor2.readthedocs.io/en/latest/versionhistory.html
Project-URL: Documentation, https://cbor2.readthedocs.org/en/latest/
Project-URL: Source Code, https://github.com/agronholm/cbor2
Project-URL: Issue Tracker, https://github.com/agronholm/cbor2/issues
Keywords: serialization,cbor
Classifier: Development Status :: 5 - Production/Stable
Classifier: Environment :: WebAssembly :: Emscripten
Classifier: Intended Audience :: Developers
Classifier: Typing :: Typed
Classifier: Programming Language :: Python :: Free Threading :: 2 - Beta
Classifier: Programming Language :: Rust
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Programming Language :: Python :: 3.15
Requires-Python: >=3.10
Description-Content-Type: text/x-rst
License-File: LICENSE.txt
Dynamic: license-file

.. 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
.. image:: https://tidelift.com/badges/package/pypi/cbor2
  :target: https://tidelift.com/subscription/pkg/pypi-cbor2
  :alt: Tidelift

About
=====

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 Rust.

.. _RFC 8949: https://www.rfc-editor.org/rfc/rfc8949.html

Features
--------

* Simple API like the ``json`` or ``pickle`` modules
* Support many `CBOR tags`_ with `stdlib objects`_
* Generic tag decoding
* `Shared value`_ references including cyclic references
* `String references`_ compact encoding with repeated strings replaced with indices
* Extensible `tagged value handling`_ using ``tag_hook`` and ``object_hook`` on decode and
  ``default`` on encode.
* Command-line diagnostic tool (``python -m cbor2.tool`` or just ``cbor2``)

  * Can convert a CBOR file or stream to JSON (lossy conversion, for diagnostics only)
  * Can convert a JSON to binary CBOR (with ``--format=json``)
* Thorough test suite (Tested on big- and little-endian architectures)

.. _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

Installation
============

The simplest way to install the library is with pip_:

::

    pip install cbor2

If this fails, see the next section.

.. _pip: https://packaging.python.org/en/latest/tutorials/installing-packages/

Build requirements
------------------

If you wish to compile the code yourself, or are installing on a yet unsupported Python version
or platform where there are no wheels available, you need the following pre-requisites:

* Python >= 3.10 (or `PyPy3`_ 3.11+)
* `Rust toolchain`_ (tested with v1.93.0)

.. _PyPy3: https://www.pypy.org/
.. _Rust toolchain: https://rust-lang.org/tools/install/

Usage
=====

`Basic Usage <https://cbor2.readthedocs.io/en/latest/usage.html#basic-usage>`_

Command-line 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

To encode a JSON document as binary CBOR, select the JSON input format::

    $ cbor2 --format=json -o output.cbor input.json
    $ echo '{"hello": "world"}' | python -m cbor2.tool --format=json > output.cbor

Each input file (or standard input, ``-``) must contain one complete JSON value,
which may be an object, array or scalar. Multiple input files produce concatenated
CBOR items in the given order. Output is raw binary, with no added separators or
newlines. JSON is read with Python's ``json`` module, then encoded using the normal
``cbor2.dump`` defaults. Diagnostic strings representing CBOR-specific types are
encoded as strings; this does not reverse the lossy diagnostic conversion.

The ``--decode``, ``--pretty``, ``--sort-keys``, ``--sequence`` and ``--tag-ignore``
options apply only to CBOR input and cannot be combined with ``--format=json``.

.. _jq: https://stedolan.github.io/jq/

Security
========

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.
