Transcoders and serializers

couchbase.transcoder

class couchbase.transcoder.JSONTranscoder(serializer: Serializer | None = None)

The default transcoder, which stores every value as JSON.

It encodes a str, list, tuple, dict, bool, int, float or None, and refuses bytes. It decodes a document flagged as JSON, or with no flags, and returns the raw bytes if that is not valid JSON. It refuses a document flagged as binary or as a string.

Parameters:

serializer (Serializer, optional) – The serializer that does the JSON encoding and decoding. Defaults to DefaultJsonSerializer.

decode_value(value: bytes, flags: int | None) → Any

Decode stored bytes into a value.

Parameters:
  • value (bytes) – The bytes the document stores.

  • flags (int | None) – The flags stored with them.

Returns:

The decoded value.

Return type:

Any

Raises:

ValueFormatException – If the transcoder cannot decode the format the flags record.

encode_value(value: Any) → tuple[bytes, int]

Encode a value for storage.

Parameters:

value (Any) – The value to store.

Returns:

The bytes to store and the flags recording their format.

Return type:

tuple[bytes, int]

Raises:

ValueFormatException – If the transcoder cannot encode the value.

class couchbase.transcoder.LegacyTranscoder

A transcoder that picks the format from the value’s type.

It stores a str as a string, bytes as binary, a list, tuple, dict, bool, int, float or None as JSON, and pickles anything else. Decoding follows the flags, and returns the raw bytes for a JSON document that does not parse and for a format it does not know.

Decoding unpickles a document flagged as pickled, which can run arbitrary code, so read with it only documents written by code you trust.

decode_value(value: bytes, flags: int | None) → Any

Decode stored bytes into a value.

Parameters:
  • value (bytes) – The bytes the document stores.

  • flags (int | None) – The flags stored with them.

Returns:

The decoded value.

Return type:

Any

Raises:

ValueFormatException – If the transcoder cannot decode the format the flags record.

encode_value(value: Any) → tuple[bytes, int]

Encode a value for storage.

Parameters:

value (Any) – The value to store.

Returns:

The bytes to store and the flags recording their format.

Return type:

tuple[bytes, int]

Raises:

ValueFormatException – If the transcoder cannot encode the value.

class couchbase.transcoder.RawBinaryTranscoder

A transcoder for binary data.

It stores bytes or a bytearray flagged as binary, and returns a document so flagged as bytes. It refuses any other value, and a document flagged as a string or as JSON.

decode_value(value: bytes, flags: int | None) → bytes

Decode stored bytes into a value.

Parameters:
  • value (bytes) – The bytes the document stores.

  • flags (int | None) – The flags stored with them.

Returns:

The decoded value.

Return type:

Any

Raises:

ValueFormatException – If the transcoder cannot decode the format the flags record.

encode_value(value: bytes | bytearray) → tuple[bytes, int]

Encode a value for storage.

Parameters:

value (Any) – The value to store.

Returns:

The bytes to store and the flags recording their format.

Return type:

tuple[bytes, int]

Raises:

ValueFormatException – If the transcoder cannot encode the value.

class couchbase.transcoder.RawJSONTranscoder

A transcoder for JSON that is already encoded.

It stores a str as UTF-8 and bytes as given, both flagged as JSON, and returns a JSON document’s bytes undecoded. It refuses any other value, and a document flagged as binary or as a string.

decode_value(value: bytes, flags: int | None) → str | bytes

Decode stored bytes into a value.

Parameters:
  • value (bytes) – The bytes the document stores.

  • flags (int | None) – The flags stored with them.

Returns:

The decoded value.

Return type:

Any

Raises:

ValueFormatException – If the transcoder cannot decode the format the flags record.

encode_value(value: str | bytes | bytearray) → tuple[bytes, int]

Encode a value for storage.

Parameters:

value (Any) – The value to store.

Returns:

The bytes to store and the flags recording their format.

Return type:

tuple[bytes, int]

Raises:

ValueFormatException – If the transcoder cannot encode the value.

class couchbase.transcoder.RawStringTranscoder

A transcoder for plain strings.

It stores a str as UTF-8 flagged as a string, and decodes a document so flagged back to a str. It refuses any other value, and a document flagged as binary or as JSON.

decode_value(value: bytes, flags: int | None) → str | bytes

Decode stored bytes into a value.

Parameters:
  • value (bytes) – The bytes the document stores.

  • flags (int | None) – The flags stored with them.

Returns:

The decoded value.

Return type:

Any

Raises:

ValueFormatException – If the transcoder cannot decode the format the flags record.

encode_value(value: str) → tuple[bytes, int]

Encode a value for storage.

Parameters:

value (Any) – The value to store.

Returns:

The bytes to store and the flags recording their format.

Return type:

tuple[bytes, int]

Raises:

ValueFormatException – If the transcoder cannot encode the value.

class couchbase.transcoder.Transcoder

The interface a custom transcoder implements.

A transcoder turns a value into the bytes a document stores and the flags that record their format, and turns stored bytes and flags back into a value.

abstract decode_value(value: bytes, flags: int | None) → Any

Decode stored bytes into a value.

Parameters:
  • value (bytes) – The bytes the document stores.

  • flags (int | None) – The flags stored with them.

Returns:

The decoded value.

Return type:

Any

Raises:

ValueFormatException – If the transcoder cannot decode the format the flags record.

abstract encode_value(value: _V_contra) → tuple[bytes, int]

Encode a value for storage.

Parameters:

value (Any) – The value to store.

Returns:

The bytes to store and the flags recording their format.

Return type:

tuple[bytes, int]

Raises:

ValueFormatException – If the transcoder cannot encode the value.

couchbase.serializer

class couchbase.serializer.DefaultJsonSerializer

The serializer the SDK uses when none is given, built on the standard json module.

Warning

couchbase.options.DefaultJsonSerializer and couchbase.transcoder.DefaultJsonSerializer are deprecated, and will be removed in a future release. Import DefaultJsonSerializer from couchbase.serializer.

deserialize(value: bytes) → Any

Decode UTF-8 JSON into a value.

serialize(value: Any) → bytes

Encode a value as UTF-8 JSON, leaving non-ASCII characters unescaped.

class couchbase.serializer.Serializer

The interface a custom JSON serializer implements.

JSONTranscoder uses one to turn values into JSON bytes and back.

abstract deserialize(value: bytes) → Any

Decode JSON into a value.

Parameters:

value (bytes) – UTF-8 JSON.

Returns:

The decoded value.

Return type:

Any

abstract serialize(value: Any) → bytes

Encode a value as JSON.

Parameters:

value (Any) – The value to encode.

Returns:

The value as UTF-8 JSON.

Return type:

bytes