API reference
Encoding
- cbor2.dumps(obj, datetime_as_timestamp=False, timezone=None, value_sharing=False, default=None, canonical=False, date_as_datetime=False, string_referencing=False)
Serialize an object to a bytestring.
- Parameters:
obj – the object to serialize
datetime_as_timestamp – set to
True
to serialize datetimes as UNIX timestamps (this makes datetimes more concise on the wire, but loses the timezone information)timezone – the default timezone to use for serializing naive datetimes; if this is not specified naive datetimes will throw a
ValueError
when encoding is attemptedvalue_sharing – set to
True
to allow more efficient serializing of repeated values and, more importantly, cyclic data structures, at the cost of extra line overheaddefault – 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 – when
True
, use “canonical” CBOR representation; this typically involves sorting maps, sets, etc. into a pre-determined order ensuring that serializations are comparable without decodingdate_as_datetime – 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 – set to
True
to allow more efficient serializing of repeated string values
- Returns:
the serialized output
- cbor2.dump(obj, fp, datetime_as_timestamp=False, timezone=None, value_sharing=False, default=None, canonical=False, date_as_datetime=False, string_referencing=False)
Serialize an object to a file.
- Parameters:
obj – the object to serialize
fp – the file to write to (any file-like object opened for writing in binary mode)
datetime_as_timestamp – set to
True
to serialize datetimes as UNIX timestamps (this makes datetimes more concise on the wire, but loses the timezone information)timezone – the default timezone to use for serializing naive datetimes; if this is not specified naive datetimes will throw a
ValueError
when encoding is attemptedvalue_sharing – set to
True
to allow more efficient serializing of repeated values and, more importantly, cyclic data structures, at the cost of extra line overheaddefault – 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 – when
True
, use “canonical” CBOR representation; this typically involves sorting maps, sets, etc. into a pre-determined order ensuring that serializations are comparable without decodingdate_as_datetime – 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 – set to
True
to allow more efficient serializing of repeated string values
- class cbor2.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()
anddumps()
functions are called to indirectly construct and use the class.When the class is constructed manually, the main entry points are
encode()
andencode_to_bytes()
.- 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.
- 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.- Return type:
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. :rtype: Callable[[cbor2.CBOREncoder, Any], None]
Decoding
- cbor2.loads(s, tag_hook=None, object_hook=None, str_errors='strict')
Deserialize an object from a bytestring.
- Parameters:
s (bytes) – the bytestring to deserialize
tag_hook – callable that takes 2 arguments: the decoder instance, and the
CBORTag
to be decoded. This callback is invoked for any tags for which there is no built-in decoder. The return value is substituted for theCBORTag
object in the deserialized outputobject_hook – callable that takes 2 arguments: the decoder instance, and a dictionary. This callback is invoked for each deserialized
dict
object. The return value is substituted for the dict in the deserialized output.str_errors – determines how to handle unicode decoding errors (see the Error Handlers section in the standard library documentation for details)
- Returns:
the deserialized object
- cbor2.load(fp, tag_hook=None, object_hook=None, str_errors='strict')
Deserialize an object from an open file.
- Parameters:
fp – the file to read from (any file-like object opened for reading in binary mode)
tag_hook – callable that takes 2 arguments: the decoder instance, and the
CBORTag
to be decoded. This callback is invoked for any tags for which there is no built-in decoder. The return value is substituted for theCBORTag
object in the deserialized outputobject_hook – callable that takes 2 arguments: the decoder instance, and a dictionary. This callback is invoked for each deserialized
dict
object. The return value is substituted for the dict in the deserialized output.str_errors – determines how to handle unicode decoding errors (see the Error Handlers section in the standard library documentation for details)
- Returns:
the deserialized object
- class cbor2.CBORDecoder(fp, tag_hook=None, object_hook=None, str_errors='strict')
The CBORDecoder class implements a fully featured CBOR decoder with several extensions for handling shared references, big integers, rational numbers and so on. Typically the class is not used directly, but the
load()
andloads()
functions are called to indirectly construct and use the class.When the class is constructed manually, the main entry points are
decode()
anddecode_from_bytes()
.- decode()
Decode the next value from the stream.
- Raises:
CBORDecodeError – if there is any problem decoding the stream
- Return type:
- decode_from_bytes(buf)
Wrap the given bytestring as a file and call
decode()
with it as the argument.This method was intended to be used from the
tag_hook
hook when an object needs to be decoded separately from the rest but while still taking advantage of the shared value registry.- Return type:
- property immutable: bool
Used by decoders to check if the calling context requires an immutable type. Object_hook or tag_hook should raise an exception if this flag is set unless the result can be safely used as a dict key.
- read(amount)
Read bytes from the data stream.
Types
- class cbor2.CBORSimpleValue(value: int)
Represents a CBOR “simple value”.
- Parameters:
value (int) – the value (0-255)
- class cbor2.CBORTag(tag, value)
Represents a CBOR semantic tag.
- Parameters:
tag (int) – tag number
value (Any) – encapsulated value (any object)
- cbor2.undefined
- A singleton representing the CBOR "undefined" value.
Exceptions
- exception cbor2.CBORError
Base class for errors that occur during CBOR encoding or decoding.
- exception cbor2.CBOREncodeError
Raised for exceptions occurring during CBOR encoding.
- exception cbor2.CBOREncodeTypeError
Raised when attempting to encode a type that cannot be serialized.
- exception cbor2.CBOREncodeValueError
Raised when the CBOR encoder encounters an invalid value.
- exception cbor2.CBORDecodeError
Raised for exceptions occurring during CBOR decoding.
- exception cbor2.CBORDecodeValueError
Raised when the CBOR stream being decoded contains an invalid value.
- exception cbor2.CBORDecodeEOF
Raised when decoding unexpectedly reaches EOF.