django-contentrelations 1.1 documentation

Serializing Resources

Many times resources are used in another context, such as an Adobe Flash application. Serialization is the process of converting a set of resources into another format such as XML or JSON. Supply Closet’s serialization framework provides a mechanism for “translating” Resources into other formats. Usually these other formats will be text-based and used for sending Resources over a wire, but it’’’s possible for a serializer to handle any format (text-based or not).

Supply Closet’s serializization framework is closely based on Django’s serialization framework. But there is one fundamental difference. Since the nature of a Resource is flexible, there is no way to determine the fields or attributes of a Resource. Therefore it is difficult to write a completely generic serializer for a given format.

How to serialize a list of resources

  1. Load your serializer (see Writing a serializer)
  2. Instantiate your serializer
  3. Call its Serializer.serialize() method with your list of objects. These objects should have a Resource class registered.

It could look like this:

>>> from myresources.resources import MySerializer
>>> myserializer = MySerializer()
>>> output = myserializer.serialize(object_list)

In this example, object_list is simply an iterable of Django Model instances with registered Resources. Internally the serializer wraps the object_list in a ResourceIterator

Writing a serializer

Your serializer should subclass Serializer. Creating a functioning serializer requires only implementing one of two methods: either Serializer.serialize_object() or Serializer.handle_field(). You can only use handle_field if you pass a selected_fields parameter to the Serializer.serialize() method.

Basic serialization

Here is a very simplistic CSV serializer for a Resource:

from contentrelations.serializer import Serializer
import csv

class SimpleCSVSerializer(Serializer):
    """
    This will serialize resources with name and description attributes
    """

    def serialize_object(self, obj):
        csv_writer = csv.writer(self.stream)
        csv_writer.writerow([obj.name, obj.description])

This only implements the serialize_object method. For more complex formats, you will probably need to do more.

Advanced serialization

The Serializer object has several event methods that you can use to help with the out put.

  • start serialization() Called at the start of the process
  • end serialization() Called at the end of the process
  • start object(obj) Called before serializing of the passed object
  • end object(obj) Called after serializing of the passed object

Here is an example of a very simple JSON serializer:

from contentrelations.serializer import Serializer
import json

class SimpleJSONSerializer(Serializer):
    """
    This will serialize resources with name and description attributes
    """

    def start_serialization(self):
        self.stream.write("[")

    def end_serialization(self):
        self.stream.write("]")

    def serialize_object(self, obj):
        out = {'name': obj.name, 'description': obj.description}
        if not self.first:
            self.stream.write(",")
        self.stream.write(json.dumps(out))

This serializer uses the start_serialization and end_serialization methods to add the enclosing brackets [] around the objects.