|
1 """ |
|
2 Interfaces for serializing Django objects. |
|
3 |
|
4 Usage:: |
|
5 |
|
6 from django.core import serializers |
|
7 json = serializers.serialize("json", some_query_set) |
|
8 objects = list(serializers.deserialize("json", json)) |
|
9 |
|
10 To add your own serializers, use the SERIALIZATION_MODULES setting:: |
|
11 |
|
12 SERIALIZATION_MODULES = { |
|
13 "csv" : "path.to.csv.serializer", |
|
14 "txt" : "path.to.txt.serializer", |
|
15 } |
|
16 |
|
17 """ |
|
18 |
|
19 from django.conf import settings |
|
20 from django.utils import importlib |
|
21 |
|
22 # Built-in serializers |
|
23 BUILTIN_SERIALIZERS = { |
|
24 "xml" : "django.core.serializers.xml_serializer", |
|
25 "python" : "django.core.serializers.python", |
|
26 "json" : "django.core.serializers.json", |
|
27 } |
|
28 |
|
29 # Check for PyYaml and register the serializer if it's available. |
|
30 try: |
|
31 import yaml |
|
32 BUILTIN_SERIALIZERS["yaml"] = "django.core.serializers.pyyaml" |
|
33 except ImportError: |
|
34 pass |
|
35 |
|
36 _serializers = {} |
|
37 |
|
38 def register_serializer(format, serializer_module, serializers=None): |
|
39 """"Register a new serializer. |
|
40 |
|
41 ``serializer_module`` should be the fully qualified module name |
|
42 for the serializer. |
|
43 |
|
44 If ``serializers`` is provided, the registration will be added |
|
45 to the provided dictionary. |
|
46 |
|
47 If ``serializers`` is not provided, the registration will be made |
|
48 directly into the global register of serializers. Adding serializers |
|
49 directly is not a thread-safe operation. |
|
50 """ |
|
51 module = importlib.import_module(serializer_module) |
|
52 if serializers is None: |
|
53 _serializers[format] = module |
|
54 else: |
|
55 serializers[format] = module |
|
56 |
|
57 def unregister_serializer(format): |
|
58 "Unregister a given serializer. This is not a thread-safe operation." |
|
59 del _serializers[format] |
|
60 |
|
61 def get_serializer(format): |
|
62 if not _serializers: |
|
63 _load_serializers() |
|
64 return _serializers[format].Serializer |
|
65 |
|
66 def get_serializer_formats(): |
|
67 if not _serializers: |
|
68 _load_serializers() |
|
69 return _serializers.keys() |
|
70 |
|
71 def get_public_serializer_formats(): |
|
72 if not _serializers: |
|
73 _load_serializers() |
|
74 return [k for k, v in _serializers.iteritems() if not v.Serializer.internal_use_only] |
|
75 |
|
76 def get_deserializer(format): |
|
77 if not _serializers: |
|
78 _load_serializers() |
|
79 return _serializers[format].Deserializer |
|
80 |
|
81 def serialize(format, queryset, **options): |
|
82 """ |
|
83 Serialize a queryset (or any iterator that returns database objects) using |
|
84 a certain serializer. |
|
85 """ |
|
86 s = get_serializer(format)() |
|
87 s.serialize(queryset, **options) |
|
88 return s.getvalue() |
|
89 |
|
90 def deserialize(format, stream_or_string): |
|
91 """ |
|
92 Deserialize a stream or a string. Returns an iterator that yields ``(obj, |
|
93 m2m_relation_dict)``, where ``obj`` is a instantiated -- but *unsaved* -- |
|
94 object, and ``m2m_relation_dict`` is a dictionary of ``{m2m_field_name : |
|
95 list_of_related_objects}``. |
|
96 """ |
|
97 d = get_deserializer(format) |
|
98 return d(stream_or_string) |
|
99 |
|
100 def _load_serializers(): |
|
101 """ |
|
102 Register built-in and settings-defined serializers. This is done lazily so |
|
103 that user code has a chance to (e.g.) set up custom settings without |
|
104 needing to be careful of import order. |
|
105 """ |
|
106 global _serializers |
|
107 serializers = {} |
|
108 for format in BUILTIN_SERIALIZERS: |
|
109 register_serializer(format, BUILTIN_SERIALIZERS[format], serializers) |
|
110 if hasattr(settings, "SERIALIZATION_MODULES"): |
|
111 for format in settings.SERIALIZATION_MODULES: |
|
112 register_serializer(format, settings.SERIALIZATION_MODULES[format], serializers) |
|
113 _serializers = serializers |