Seriando objetos do Django¶

O framework de seriação do Django provê um mecanismo para “traduzir” objetos do Django em outros formatos. Usualmente estes outros formatos serão baseados em texto e usados para enviar objetos do Django por um fio, mas é possível para um seriador manipular qualquer formato (baseado em texto ou não).

Seriando dados¶

No nível mais alto, seriar dados é uma operação muito simples:

from django.core import serializers
data = serializers.serialize("xml", SomeModel.objects.all())

Os argumentos para a função serialize são o formato para o qual os dados serão seriados (veja Formatos de seriação) e um QuerySet para seriar. (Na verdade, o segundo argumento pode ser qualquer iterador que fornece objetos Django, mas quase sempre será um QuerySet).

Você pode usar também um objeto seriador diretamente:

XMLSerializer = serializers.get_serializer("xml")
xml_serializer = XMLSerializer()
xml_serializer.serialize(queryset)
data = xml_serializer.getvalue()

Este é usuál se você quiser seriar dados diretamente para um objeto arquivo (que inclua um HttpResponse):

out = open("file.xml", "w")
xml_serializer.serialize(SomeModel.objects.all(), stream=out)

Subconjunto de campos¶

Se você somente quiser um subconjunto de campos para seriar, você pode especificar um argumento fields para o seriador:

from django.core import serializers
data = serializers.serialize('xml', SomeModel.objects.all(), fields=('name','size'))

Neste exemplo, somente os atributos name e size de cada model serão seriados.

Note

Dependendo do seu modelo, você pode descobrir que não é possível desseriar um modelo que teve apenas um subconjunto de seus campos seriados. Se um objeto seriado não especificar todos os campos que são requeridos pelo mode, o desseriador não será capaz de salvar instâncias desseriadas.

Models herdados¶

Se você tem um model que é definido usando uma classe abstrata de base, você não terá de fazer nada especial para seriar este model. Somente chamar o seriador sobre o objeto (ou objetos) que você deseja seriar, e a saída será uma representação completa do objeto seriado.

Porém, se você tem um model que usa herança de multi-tabelas, você também precisa seriar todos as classes que dão base ao model. Isto porque somente os campos que são localmente definidos no model serão seriados. Por exemplo, considere os seguintes models:

class Place(models.Model):
    name = models.CharField(max_length=50)

class Restaurant(Place):
    serves_hot_dogs = models.BooleanField()

Se você somente seriar o model Restaurant:

data = serializers.serialize('xml', Restaurant.objects.all())

os campos na saída seriada conterão somente atributos serves_hot_dogs. O atributo name da classe de base será ignorado.

Afim de permitir uma seriação completa para sua instância Restaurant, você precisará seriar o model Place também:

all_objects = list(Restaurant.objects.all()) + list(Place.objects.all())
data = serializers.serialize('xml', all_objects)

Desseriando dados¶

Desseriamento de dados é também um operação bastante simples:

for obj in serializers.deserialize("xml", data):
    do_something_with(obj)

Como você pode ver, a função deserialize recebe o mesmo argumento de formato que o serialize, uma string ou stream de dados, e retorna um iterador.

Entretanto, aqui fica um pouco complicado. Os objetos retornado pelo iterador do deserialize não são objetos simples do Django. Em vez disso, eles são instâncias especiais DeserializedObject que envolvem o objeto criado – mas não salvo – e toda relação de dados.

Chamando DeserializedObject.save() salva o objeto no banco de dados.

Isso garante que a desseriação é uma operação não destrutiva mesmo se o dado na sua representação não bata com a que estiver agora no seu banco de dados. Normalmente, trabalhar com estas instâncias de DeserializedObject parece algo como:

for deserialized_object in serializers.deserialize("xml", data):
    if object_should_be_saved(deserialized_object):
        deserialized_object.save()

Em outras palavras, o uso normal é examinar os objetos desseriados para ter certeza de que eles estão “adequados” a serem salvos antes de salvá-los. Logicamente, se você confiar na fonte de dados, poderá apenas salvar os objetos e seguir adiante.

O objeto Django em si pode ser inspecionado como deserialized_object.object.

Formatos de seriação¶

O Django suporta vários formatos de seriação, alguns que obrigam você instalar módulos de terceiros do Python:

Identificador	Informações
`xml`	Serializa para e do dialeto simples de XML.
`json`	Serializa para e do JSON (usando uma versão do simplejson empacotada com o Django).
`python`	Traduz para e dos objetos “simples” do Python (listas, dicionários, strings, etc.). Nem tudo dele é realmente útil, mas é usado como base para outros seriadores.
`yaml`	Serializa para YAML (YAML não é uma linguagem de marcação). Este seriador é somente disponível se o PyYAML estiver instalado.

Notas para formatos de seriação específicos¶

json¶

Se você esta usando dados UTF-8 (ou qualquer outra codificação não-ASCII) com o seriador JSON, você passar ensure_ascii=False como parâmetro para a chamada serialize(). Por outro lado, a saída não pode será codificada corretamente.

Por exemplo:

json_serializer = serializers.get_serializer("json")()
json_serializer.serialize(queryset, ensure_ascii=False, stream=response)

O código do Django inclui o módulo simplejson. Tenha cuidado que se você estiver seriando usando este módulo diretamente, nem todas as saídas do Django podem ser passadas sem modificação para o simplejson. Em particular, objetos de tradução tardios precisam de um codificador especial escritos para eles. Algo como isto funcionará:

from django.utils.functional import Promise
from django.utils.encoding import force_unicode

class LazyEncoder(simplejson.JSONEncoder):
    def default(self, obj):
        if isinstance(obj, Promise):
            return force_unicode(obj)
        return super(LazyEncoder, self).default(obj)