Transcoder Interface¶
The Transcoder interface may be used to provide custom value and key formats. Among the uses of the transcoder class, one may:
Implement compatibility with other client libraries
The
format
option in the operations correspond to a flag value which is stored in the server as meta data along with the key. These flags are utilized by client libraries to determine how to interpret the value on the server (which is just a set of bytes) into a more complex and user-friendly type in the native client language. Some clients may have different ideas about which flags mean which value format, and some clients may use formats which are specific to that platform (for example,FMT_PICKLE
which is typically only native to Python objects). One may implement a custom transcoder class which understands a wider variety of types and flagsImplement Compression
If storing large values, it may be handy to compress them before storing them on the server. This provides for lower network overhead and storage space on the server, at the expense of the computational overhead of compressing and decompressing objects. One may add extra flags to indicate a value has been compressed, and with which format.
Automatic conversion of different value types into custom classes
The built-in transcoder only uses native Python types. One may wish to interpret values as belong to user-defined classes.
The Transcoder
class is implemented in C for efficiency, but
a pure-python implementation is available as the TranscoderPP
class in couchbase/transcoder.py
.
Typically one would subclass the Transcoder
class, and
implement the needed methods, allowing for high efficient built-in
methods to perform the un-needed operations.
Note that the Bucket
does not
use a Transcoder
object by default (however it internally uses
the same routines that the C-implemented Transcoder
does). Thus,
if no custom transcoding is needed, it is more efficient to set the
transcoder
to None
, which
is the default.
-
class
couchbase.transcoder.
Transcoder
¶ -
encode_key
(key)¶ Encode the key as a bytes object.
Parameters: key – This is an object passed as a string key. There is no restriction on this type Returns: a bytes object The default implementation encodes the key as UTF-8. On Python 2.x, bytes
is a synonym forstr
. On Python 3.x,bytes
andstr
are distinct objects, in which one must first encode a string to a specific encoding
-
encode_value
(value, flags)¶ Encode the value into something meaningful
Parameters: - value (any) – A value. This may be a string or a complex python object.
- format (any) – The format argument as passed to the mutator
Returns: A tuple of
(value, flags)
value
must be abytes
object.flags
must be an integer type whose value does not exceed 32 bits
-
decode_key
(key)¶ Convert the key from bytes into something else.
Parameters: key (bytes) – The key, in the form of a bytearray Returns: a string or other object your application will use The returned key must be hashable The default implementation decodes the keys from UTF-8.
-
decode_value
(value, flags)¶ Decode the value from the raw bytes representation into something meaningful
Parameters: - value (bytes) – Raw bytes, as stored on the server
- flags (int) – The flags for the value
Returns: Something meaningful to be used as a value within the application
-
determine_format
(value)¶ - Guess the suitable format for the object specified.
New in version 1.1.0.
Used primarily if received a
FMT_AUTO
for the format parameter in one of the encode methodsParameters: value (object) – The value whose format should be guessed Returns: An integer representing the guessed format. Note that this function is provided as a convenience. It is not called by the Connection object
This function always succeeds
-
-
class
couchbase.transcoder.
TranscoderPP
[source]¶ This is a pure-python Transcoder class. It is here only to show a reference implementation. It is recommended that you subclass from the
Transcoder
object instead if all the methods are not implemented.