Package xmlschema_acue ::
Module documents
1
2
3
4
5
6
7
8
9
10
11 from __future__ import unicode_literals
12 from __future__ import absolute_import
13
14 import json
15
16 from xmlschema_acue.compat import ordered_dict_class
17 from xmlschema_acue.resources import fetch_schema_locations
18 from xmlschema_acue.validators.schema import XMLSchema, XMLSchemaBase
19
20
21 -def validate(xml_document, schema=None, cls=None, use_defaults=True, namespaces=None, locations=None, base_url=None):
22 """
23 Validates an XML document against a schema instance. This function builds an
24 :class:`XMLSchema` object for validating the XML document. Raises an
25 :exc:`XMLSchemaValidationError` if the XML document is not validated against
26 the schema.
27
28 :param xml_document: can be a file-like object or a string containing the XML data \
29 or a file path or a URL of a resource or an ElementTree/Element instance.
30 :param schema: can be a schema instance or a file-like object or a file path or a URL \
31 of a resource or a string containing the schema.
32 :param cls: schema class to use for building the instance (for default uses :class:`XMLSchema`).
33 :param use_defaults: defines when to use elements and attribute defaults for filling \
34 missing required values.
35 :param namespaces: is an optional mapping from namespace prefix to URI.
36 :param locations: additional schema location hints, in case a schema instance has to be built.
37 :param base_url: is an optional custom base URL for remapping relative locations, for \
38 default uses the directory where the XSD or alternatively the XML document is located.
39 """
40 cls = XMLSchema if cls is None else XMLSchema
41 if schema is None:
42 schema, locations = fetch_schema_locations(xml_document, locations, base_url=base_url)
43 schema = cls(schema, validation='strict', locations=locations)
44 elif not isinstance(schema, XMLSchemaBase):
45 schema = cls(schema, validation='strict', locations=locations, base_url=base_url)
46 schema.validate(xml_document, use_defaults, namespaces)
47
48
49 -def to_dict(xml_document, schema=None, cls=None, path=None, process_namespaces=True,
50 locations=None, base_url=None, **kwargs):
51 """
52 Decodes an XML document to a Python's nested dictionary. The decoding is based
53 on an XML Schema class instance. For default the document is validated during
54 the decoding phase. Raises an :exc:`XMLSchemaValidationError` if the XML document
55 is not validated against the schema.
56
57 :param xml_document: can be a file-like object or a string containing the XML data \
58 or a file path or a URL of a resource or an ElementTree/Element instance.
59 :param schema: can be a schema instance or a file-like object or a file path or a URL \
60 of a resource or a string containing the schema.
61 :param cls: schema class to use for building the instance (for default uses :class:`XMLSchema`).
62 :param path: is an optional XPath expression that matches the subelement of the document \
63 that have to be decoded. The XPath expression considers the schema as the root element \
64 with global elements as its children.
65 :param process_namespaces: indicates whether to use namespace information in the decoding process.
66 :param locations: additional schema location hints, in case a schema instance has to be built.
67 :param base_url: is an optional custom base URL for remapping relative locations, for \
68 default uses the directory where the XSD or alternatively the XML document is located.
69 :param kwargs: optional arguments of :meth:`XMLSchema.iter_decode` as keyword arguments \
70 to variate the decoding process.
71 :return: an object containing the decoded data. If ``validation='lax'`` keyword argument \
72 is provided the validation errors are collected and returned coupled in a tuple with the \
73 decoded data.
74 :raises: :exc:`XMLSchemaValidationError` if the object is not decodable by \
75 the XSD component, or also if it's invalid when ``validation='strict'`` is provided.
76
77 """
78 cls = XMLSchema if cls is None else XMLSchema
79 if schema is None:
80 schema, locations = fetch_schema_locations(xml_document, locations, base_url=base_url)
81 schema = cls(schema, validation='strict', locations=locations)
82 elif not isinstance(schema, XMLSchemaBase):
83 schema = cls(schema, validation='strict', locations=locations, base_url=base_url)
84 return schema.to_dict(xml_document, path=path, process_namespaces=process_namespaces, **kwargs)
85
86
87 -def to_json(xml_document, fp=None, schema=None, cls=None, path=None, converter=None,
88 process_namespaces=True, locations=None, base_url=None, json_options=None, **kwargs):
89 """
90 Serialize an XML document to JSON. For default the XML data is validated during
91 the decoding phase. Raises an :exc:`XMLSchemaValidationError` if the XML document
92 is not validated against the schema.
93
94 :param xml_document: can be a file-like object or a string containing the XML data \
95 or a file path or an URI of a resource or an ElementTree/Element instance.
96 :param fp: can be a :meth:`write()` supporting file-like object.
97 :param schema: can be a schema instance or a file-like object or a file path or an URL \
98 of a resource or a string containing the schema.
99 :param cls: schema class to use for building the instance (for default uses :class:`XMLSchema`).
100 :param path: is an optional XPath expression that matches the subelement of the document \
101 that have to be decoded. The XPath expression considers the schema as the root element \
102 with global elements as its children.
103 :param converter: an :class:`XMLSchemaConverter` subclass or instance to use for the decoding.
104 :param process_namespaces: indicates whether to use namespace information in the decoding process.
105 :param locations: additional schema location hints, in case a schema instance has to be built.
106 :param base_url: is an optional custom base URL for remapping relative locations, for \
107 default uses the directory where the XSD or alternatively the XML document is located.
108 :param json_options: a dictionary with options for the JSON serializer.
109 :param kwargs: optional arguments of :meth:`XMLSchema.iter_decode` as keyword arguments \
110 to variate the decoding process.
111 :return: a string containing the JSON data if *fp* is `None`, otherwise doesn't return anything. \
112 If ``validation='lax'`` keyword argument is provided the validation errors are collected and \
113 returned, eventually coupled in a tuple with the JSON data.
114 :raises: :exc:`XMLSchemaValidationError` if the object is not decodable by \
115 the XSD component, or also if it's invalid when ``validation='strict'`` is provided.
116 """
117 cls = XMLSchema if cls is None else XMLSchema
118 if schema is None:
119 schema, locations = fetch_schema_locations(xml_document, locations, base_url=base_url)
120 schema = cls(schema, validation='strict', locations=locations)
121 elif not isinstance(schema, XMLSchemaBase):
122 schema = cls(schema, validation='strict', locations=locations, base_url=base_url)
123 if json_options is None:
124 json_options = {}
125
126 decimal_type = kwargs.pop('decimal_type', float)
127 dict_class = kwargs.pop('dict_class', ordered_dict_class)
128 obj = schema.to_dict(xml_document, path=path, decimal_type=decimal_type, dict_class=dict_class,
129 process_namespaces=process_namespaces, converter=converter, **kwargs)
130
131 if isinstance(obj, tuple):
132 if fp is not None:
133 json.dump(obj[0], fp, **kwargs)
134 return tuple(obj[1])
135 else:
136 return json.dumps(obj[0], **json_options), tuple(obj[1])
137 elif fp is not None:
138 json.dump(obj, fp, **json_options)
139 else:
140 return json.dumps(obj, **json_options)
141
142
143 -def from_json(source, schema, path=None, converter=None, json_options=None, **kwargs):
144 """
145 Deserialize JSON data to an XML Element.
146
147 :param source: can be a string or a :meth:`read()` supporting file-like object \
148 containing the JSON document.
149 :param schema: an :class:`XMLSchema` instance.
150 :param path: is an optional XPath expression for selecting the element of the schema \
151 that matches the data that has to be encoded. For default the first global element of \
152 the schema is used.
153 :param converter: an :class:`XMLSchemaConverter` subclass or instance to use for the encoding.
154 :param json_options: a dictionary with options for the JSON deserializer.
155 :param kwargs: Keyword arguments containing options for converter and encoding.
156 :return: An element tree's Element instance. If ``validation='lax'`` keyword argument is \
157 provided the validation errors are collected and returned coupled in a tuple with the \
158 Element instance.
159 :raises: :exc:`XMLSchemaValidationError` if the object is not encodable by the schema, \
160 or also if it's invalid when ``validation='strict'`` is provided.
161 """
162 if not isinstance(schema, XMLSchemaBase):
163 raise TypeError("An XMLSchema instance required for 'schema' argument: %r" % schema)
164 elif json_options is None:
165 json_options = {}
166
167 dict_class = kwargs.pop('dict_class', ordered_dict_class)
168 object_hook = json_options.pop('object_hook', ordered_dict_class)
169 object_pairs_hook = json_options.pop('object_pairs_hook', ordered_dict_class)
170 if hasattr(source, 'read'):
171 obj = json.load(source, object_hook=object_hook, object_pairs_hook=object_pairs_hook, **json_options)
172 else:
173 obj = json.loads(source, object_hook=object_hook, object_pairs_hook=object_pairs_hook, **json_options)
174
175 return schema.encode(obj, path=path, converter=converter, dict_class=dict_class, **kwargs)
176