diff options
Diffstat (limited to 'docs/userguide')
-rw-r--r-- | docs/userguide/index.rst | 1 | ||||
-rw-r--r-- | docs/userguide/serialization.rst | 94 |
2 files changed, 95 insertions, 0 deletions
diff --git a/docs/userguide/index.rst b/docs/userguide/index.rst index 2b241bbc..3010fd10 100644 --- a/docs/userguide/index.rst +++ b/docs/userguide/index.rst @@ -10,3 +10,4 @@ connections simple + serialization diff --git a/docs/userguide/serialization.rst b/docs/userguide/serialization.rst new file mode 100644 index 00000000..4f24f166 --- /dev/null +++ b/docs/userguide/serialization.rst @@ -0,0 +1,94 @@ +.. _guide-serialization: + +=============== + Serialization +=============== + +.. _serializers: + +Serializers +=========== + +By default every message is encoded using `JSON`_, so sending +Python data structures like dictionaries and lists works. +`YAML`_, `msgpack`_ and Python's built-in `pickle` module is also supported, +and if needed you can register any custom serialization scheme you +want to use. + +.. _`JSON`: http://www.json.org/ +.. _`YAML`: http://yaml.org/ +.. _`msgpack`: http://msgpack.sourceforge.net/ + +Each option has its advantages and disadvantages. + +`json` -- JSON is supported in many programming languages, is now + a standard part of Python (since 2.6), and is fairly fast to + decode using the modern Python libraries such as `cjson` or + `simplejson`. + + The primary disadvantage to `JSON` is that it limits you to + the following data types: strings, unicode, floats, boolean, + dictionaries, and lists. Decimals and dates are notably missing. + + Also, binary data will be transferred using base64 encoding, which + will cause the transferred data to be around 34% larger than an + encoding which supports native binary types. + + However, if your data fits inside the above constraints and + you need cross-language support, the default setting of `JSON` + is probably your best choice. + +`pickle` -- If you have no desire to support any language other than + Python, then using the `pickle` encoding will gain you + the support of all built-in Python data types (except class instances), + smaller messages when sending binary files, and a slight speedup + over `JSON` processing. + +`yaml` -- YAML has many of the same characteristics as `json`, + except that it natively supports more data types (including dates, + recursive references, etc.) + + However, the Python libraries for YAML are a good bit slower + than the libraries for JSON. + + If you need a more expressive set of data types and need to maintain + cross-language compatibility, then `YAML` may be a better fit + than the above. + +To instruct carrot to use an alternate serialization method, +use one of the following options. + + 1. Set the serialization option on a per-producer basis:: + + >>> producer = Producer(channel, + ... exchange=exchange, + ... serializer="yaml") + + 2. Set the serialization option per message:: + + >>> producer.publish(message, routing_key=rkey, + ... serializer="pickle") + +Note that a `Consumer` do not need the serialization method specified. +They can auto-detect the serialization method as the +content-type is sent as a message header. + +.. _sending-raw-data: + +Sending raw data without Serialization +====================================== + +In some cases, you don't need your message data to be serialized. If you +pass in a plain string or unicode object as your message, then carrot will +not waste cycles serializing/deserializing the data. + +You can optionally specify a `content_type` and `content_encoding` +for the raw data:: + + >>> producer.send(open('~/my_picture.jpg','rb').read(), + content_type="image/jpeg", + content_encoding="binary", + routing_key=rkey) + +The `Message` object returned by the `Consumer` class will have a +`content_type` and `content_encoding` attribute. |