3 # Copyright 2007 Google Inc.
5 # Licensed under the Apache License, Version 2.0 (the "License");
6 # you may not use this file except in compliance with the License.
7 # You may obtain a copy of the License at
9 # http://www.apache.org/licenses/LICENSE-2.0
11 # Unless required by applicable law or agreed to in writing, software
12 # distributed under the License is distributed on an "AS IS" BASIS,
13 # WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
14 # See the License for the specific language governing permissions and
15 # limitations under the License.
17 """Directly processes text of datastore-indexes.xml.
19 IndexesXmlParser is called with an XML string to produce an IndexXml object
20 containing the data from the XML.
22 IndexesXmlParser: converts XML to Index object.
23 Index: describes a single index specified in datastore-indexes.xml
26 from collections
import OrderedDict
27 from xml
.etree
import ElementTree
29 from google
.appengine
.tools
.app_engine_config_exception
import AppEngineConfigException
31 MISSING_KIND
= '<datastore-index> node has missing attribute "kind".'
32 BAD_DIRECTION
= ('<property> tag attribute "direction" must have value "asc"'
33 ' or "desc", given "%s"')
34 NAME_MISSING
= ('<datastore-index> node with kind "%s" needs to have a name'
35 ' attribute specified for its <property> node')
38 def MakeIndexesListIntoYaml(indexes_list
):
39 """Converts a list of parsed <datastore-index> clauses into YAML."""
40 statements
= ['indexes:']
41 for index
in indexes_list
:
42 statements
+= index
.ToYaml()
43 return '\n'.join(statements
) + '\n'
46 class IndexesXmlParser(object):
47 """Provides logic for walking down XML tree and pulling data."""
49 def ProcessXml(self
, xml_str
):
50 """Parses XML string and returns object representation of relevant info.
53 xml_str: The XML string.
55 A list of Index objects containing information about datastore indexes
58 AppEngineConfigException: In case of malformed XML or illegal inputs.
64 xml_root
= ElementTree
.fromstring(xml_str
)
65 if xml_root
.tag
!= 'datastore-indexes':
66 raise AppEngineConfigException('Root tag must be <datastore-indexes>')
68 for child
in xml_root
.getchildren():
69 self
.ProcessIndexNode(child
)
72 raise AppEngineConfigException('\n'.join(self
.errors
))
75 except ElementTree
.ParseError
as e
:
76 raise AppEngineConfigException('Bad input -- not valid XML: %s' % e
)
78 def ProcessIndexNode(self
, node
):
79 """Processes XML <datastore-index> nodes into Index objects.
81 The following information is parsed out:
82 kind: specifies the kind of entities to index.
83 ancestor: true if the index supports queries that filter by
84 ancestor-key to constraint results to a single entity group.
85 property: represents the entity properties to index, with a name
86 and direction attribute.
89 node: <datastore-index> XML node in datastore-indexes.xml.
91 if node
.tag
!= 'datastore-index':
92 self
.errors
.append('Unrecognized node: <%s>' % node
.tag
)
96 index
.kind
= node
.attrib
.get('kind', '')
98 self
.errors
.append(MISSING_KIND
)
99 ancestor
= node
.attrib
.get('ancestor', 'false')
100 index
.ancestor
= self
._BooleanAttribute
(ancestor
)
101 if index
.ancestor
is None:
103 'Value for ancestor should be true or false, not "%s"' % ancestor
)
104 index
.properties
= OrderedDict()
105 property_nodes
= [n
for n
in node
.getchildren() if n
.tag
== 'property']
106 for property_node
in property_nodes
:
107 name
= property_node
.attrib
.get('name', '')
109 self
.errors
.append(NAME_MISSING
% index
.kind
)
112 direction
= property_node
.attrib
.get('direction', 'asc')
113 if direction
not in ('asc', 'desc'):
114 self
.errors
.append(BAD_DIRECTION
% direction
)
116 index
.properties
[name
] = direction
117 self
.indexes
.append(index
)
120 def _BooleanAttribute(value
):
121 """Parse the given attribute value as a Boolean value.
123 This follows the specification here:
124 http://www.w3.org/TR/2012/REC-xmlschema11-2-20120405/datatypes.html#boolean
127 value: the value to parse.
130 True if the value parses as true, False if it parses as false, None if it
133 if value
in ['true', '1']:
135 elif value
in ['false', '0']:
144 statements
= ['- kind: "%s"' % self
.kind
]
146 statements
.append(' ancestor: yes')
148 statements
.append(' properties:')
149 for name
in self
.properties
:
150 statements
+= [' - name: "%s"' % name
,
151 ' direction: %s' % self
.properties
[name
]]