cbor2.encoder

class cbor2.encoder.CBOREncoder(fp, datetime_as_timestamp=False, timezone=None, value_sharing=False, default=None, canonical=False, date_as_datetime=False, string_referencing=False)

The CBOREncoder class implements a fully featured CBOR encoder with several extensions for handling shared references, big integers, rational numbers and so on. Typically the class is not used directly, but the dump() and dumps() functions are called to indirectly construct and use the class.

When the class is constructed manually, the main entry points are encode() and encode_to_bytes().

Parameters
  • datetime_as_timestamp (bool) – set to True to serialize datetimes as UNIX timestamps (this makes datetimes more concise on the wire, but loses the timezone information)

  • timezone (datetime.tzinfo) – the default timezone to use for serializing naive datetimes; if this is not specified naive datetimes will throw a ValueError when encoding is attempted

  • value_sharing (bool) – set to True to allow more efficient serializing of repeated values and, more importantly, cyclic data structures, at the cost of extra line overhead

  • default – a callable that is called by the encoder with two arguments (the encoder instance and the value being encoded) when no suitable encoder has been found, and should use the methods on the encoder to encode any objects it wants to add to the data stream

  • canonical (bool) – when True, use “canonical” CBOR representation; this typically involves sorting maps, sets, etc. into a pre-determined order ensuring that serializations are comparable without decoding

  • date_as_datetime (bool) – set to True to serialize date objects as datetimes (CBOR tag 0), which was the default behavior in previous releases (cbor2 <= 4.1.2).

  • string_referencing (bool) – set to True to allow more efficient serializing of repeated string values

disable_string_namespacing()

Disable generation of new string namespaces for the duration of the context block.

disable_string_referencing()

Disable tracking of string references for the duration of the context block.

disable_value_sharing()

Disable value sharing in the encoder for the duration of the context block.

encode(obj)

Encode the given object using CBOR.

Parameters

obj – the object to encode

encode_canonical_map(value)

Reorder keys according to Canonical CBOR specification

encode_sortable_key(value)

Takes a key and calculates the length of its optimal byte representation, along with the representation itself. This is used as the sorting key in CBOR’s canonical representations.

encode_to_bytes(obj)

Encode the given object to a byte buffer and return its value as bytes.

This method was intended to be used from the default hook when an object needs to be encoded separately from the rest but while still taking advantage of the shared value registry.

write(data)

Write bytes to the data stream.

Parameters

data (bytes) – the bytes to write

cbor2.encoder.container_encoder(func)

The given encoder is a container with child values. Handle cyclic or duplicate references to the value and strings within the value efficiently.

Containers may contain cyclic data structures or may contain values or themselves by referenced multiple times throughout the greater encoded value and could thus be more efficiently encoded with shared value references and string references where duplication occurs.

If value sharing is enabled, this marks the given value shared in the datastream on the first call. If the value has already been passed to this method, a reference marker is instead written to the data stream and the wrapped function is not called.

If value sharing is disabled, only infinite recursion protection is done.

If string referencing is enabled and this is the first use of this method in encoding a value, all repeated references to long strings and bytearrays will be replaced with references to the first occurrence of those arrays.

If string referencing is disabled, all strings and bytearrays will be encoded directly.

cbor2.encoder.dump(obj, fp, **kwargs)

Serialize an object to a file.

Parameters
  • obj – the object to serialize

  • fp – a file-like object

  • kwargs – keyword arguments passed to CBOREncoder

cbor2.encoder.dumps(obj, **kwargs)

Serialize an object to a bytestring.

Parameters
  • obj – the object to serialize

  • kwargs – keyword arguments passed to CBOREncoder

Returns

the serialized output

Return type

bytes

cbor2.encoder.shareable_encoder(func)

Wrap the given encoder function to gracefully handle cyclic data structures.

If value sharing is enabled, this marks the given value shared in the datastream on the first call. If the value has already been passed to this method, a reference marker is instead written to the data stream and the wrapped function is not called.

If value sharing is disabled, only infinite recursion protection is done.