1#!/usr/bin/python
2
3#
4# Copyright (C) 2012 The Android Open Source Project
5#
6# Licensed under the Apache License, Version 2.0 (the "License");
7# you may not use this file except in compliance with the License.
8# You may obtain a copy of the License at
9#
10#      http://www.apache.org/licenses/LICENSE-2.0
11#
12# Unless required by applicable law or agreed to in writing, software
13# distributed under the License is distributed on an "AS IS" BASIS,
14# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
15# See the License for the specific language governing permissions and
16# limitations under the License.
17#
18
19"""
20Usage:
21  metadata_validate.py <filename.xml>
22  - validates that the metadata properties defined in filename.xml are
23    semantically correct.
24  - does not do any XSD validation, use xmllint for that (in metadata-validate)
25
26Module:
27  A set of helpful functions for dealing with BeautifulSoup element trees.
28  Especially the find_* and fully_qualified_name functions.
29
30Dependencies:
31  BeautifulSoup - an HTML/XML parser available to download from
32                  http://www.crummy.com/software/BeautifulSoup/
33"""
34
35from bs4 import BeautifulSoup
36from bs4 import Tag
37import sys
38
39
40#####################
41#####################
42
43def fully_qualified_name(entry):
44  """
45  Calculates the fully qualified name for an entry by walking the path
46  to the root node.
47
48  Args:
49    entry: a BeautifulSoup Tag corresponding to an <entry ...> XML node,
50           or a <clone ...> XML node.
51
52  Raises:
53    ValueError: if entry does not correspond to one of the above XML nodes
54
55  Returns:
56    A string with the full name, e.g. "android.lens.info.availableApertureSizes"
57  """
58
59  filter_tags = ['namespace', 'section']
60  parents = [i['name'] for i in entry.parents if i.name in filter_tags]
61
62  if entry.name == 'entry':
63    name = entry['name']
64  elif entry.name == 'clone':
65    name = entry['entry'].split(".")[-1] # "a.b.c" => "c"
66  else:
67    raise ValueError("Unsupported tag type '%s' for element '%s'" \
68                        %(entry.name, entry))
69
70  parents.reverse()
71  parents.append(name)
72
73  fqn = ".".join(parents)
74
75  return fqn
76
77def find_parent_by_name(element, names):
78  """
79  Find the ancestor for an element whose name matches one of those
80  in names.
81
82  Args:
83    element: A BeautifulSoup Tag corresponding to an XML node
84
85  Returns:
86    A BeautifulSoup element corresponding to the matched parent, or None.
87
88    For example, assuming the following XML structure:
89      <static>
90        <anything>
91          <entry name="Hello" />   # this is in variable 'Hello'
92        </anything>
93      </static>
94
95      el = find_parent_by_name(Hello, ['static'])
96      # el is now a value pointing to the '<static>' element
97  """
98  matching_parents = [i.name for i in element.parents if i.name in names]
99
100  if matching_parents:
101    return matching_parents[0]
102  else:
103    return None
104
105def find_all_child_tags(element, tag):
106    """
107    Finds all the children that are a Tag (as opposed to a NavigableString),
108    with a name of tag. This is useful to filter out the NavigableString out
109    of the children.
110
111    Args:
112      element: A BeautifulSoup Tag corresponding to an XML node
113      tag: A string representing the name of the tag
114
115    Returns:
116      A list of Tag instances
117
118      For example, given the following XML structure:
119        <enum>                    # This is the variable el
120          Hello world             # NavigableString
121          <value>Apple</value>    # this is the variale apple (Tag)
122          <value>Orange</value>   # this is the variable orange (Tag)
123          Hello world again       # NavigableString
124        </enum>
125
126        lst = find_all_child_tags(el, 'value')
127        # lst is [apple, orange]
128
129    """
130    matching_tags = [i for i in element.children if isinstance(i, Tag) and i.name == tag]
131    return matching_tags
132
133def find_child_tag(element, tag):
134    """
135    Finds the first child that is a Tag with the matching name.
136
137    Args:
138      element: a BeautifulSoup Tag
139      tag: A String representing the name of the tag
140
141    Returns:
142      An instance of a Tag, or None if there was no matches.
143
144      For example, given the following XML structure:
145        <enum>                    # This is the variable el
146          Hello world             # NavigableString
147          <value>Apple</value>    # this is the variale apple (Tag)
148          <value>Orange</value>   # this is the variable orange (Tag)
149          Hello world again       # NavigableString
150        </enum>
151
152        res = find_child_tag(el, 'value')
153        # res is apple
154    """
155    matching_tags = find_all_child_tags(element, tag)
156    if matching_tags:
157        return matching_tags[0]
158    else:
159        return None
160
161def find_kind(element):
162  """
163  Finds the kind Tag ancestor for an element.
164
165  Args:
166    element: a BeautifulSoup Tag
167
168  Returns:
169    a BeautifulSoup tag, or None if there was no matches
170
171  Remarks:
172    This function only makes sense to be called for an Entry, Clone, or
173    InnerNamespace XML types. It will always return 'None' for other nodes.
174  """
175  kinds = ['dynamic', 'static', 'controls']
176  parent_kind = find_parent_by_name(element, kinds)
177  return parent_kind
178
179def validate_error(msg):
180  """
181  Print a validation error to stderr.
182
183  Args:
184    msg: a string you want to be printed
185  """
186  print >> sys.stderr, "ERROR: " + msg
187
188
189def validate_clones(soup):
190  """
191  Validate that all <clone> elements point to an existing <entry> element.
192
193  Args:
194    soup - an instance of BeautifulSoup
195
196  Returns:
197    True if the validation succeeds, False otherwise
198  """
199  success = True
200
201  for clone in soup.find_all("clone"):
202    clone_entry = clone['entry']
203    clone_kind = clone['kind']
204
205    parent_kind = find_kind(clone)
206
207    find_entry = lambda x: x.name == 'entry'                           \
208                       and find_kind(x) == clone_kind                  \
209                       and fully_qualified_name(x) == clone_entry
210    matching_entry = soup.find(find_entry)
211
212    if matching_entry is None:
213      error_msg = ("Did not find corresponding clone entry '%s' " +    \
214               "with kind '%s'") %(clone_entry, clone_kind)
215      validate_error(error_msg)
216      success = False
217
218    clone_name = fully_qualified_name(clone)
219    if clone_name != clone_entry:
220      error_msg = ("Clone entry target '%s' did not match fully qualified "  + \
221                   "name '%s'.") %(clone_entry, clone_name)
222      validate_error(error_msg)
223      success = False
224
225    if matching_entry is not None:
226      entry_hal_major_version = 3
227      entry_hal_minor_version = 2
228      entry_hal_version = matching_entry.get('hal_version')
229      if entry_hal_version is not None:
230        entry_hal_major_version = int(entry_hal_version.partition('.')[0])
231        entry_hal_minor_version = int(entry_hal_version.partition('.')[2])
232
233      clone_hal_major_version = entry_hal_major_version
234      clone_hal_minor_version = entry_hal_minor_version
235      clone_hal_version = clone.get('hal_version')
236      if clone_hal_version is not None:
237        clone_hal_major_version = int(clone_hal_version.partition('.')[0])
238        clone_hal_minor_version = int(clone_hal_version.partition('.')[2])
239
240      if clone_hal_major_version < entry_hal_major_version or \
241          (clone_hal_major_version == entry_hal_major_version and \
242           clone_hal_minor_version < entry_hal_minor_version):
243        error_msg = ("Clone '%s' HAL version '%d.%d' is older than entry target HAL version '%d.%d'" \
244                   % (clone_name, clone_hal_major_version, clone_hal_minor_version, entry_hal_major_version, entry_hal_minor_version))
245        validate_error(error_msg)
246        success = False
247
248  return success
249
250# All <entry> elements with container=$foo have a <$foo> child
251# If type="enum", <enum> tag is present
252# In <enum> for all <value id="$x">, $x is numeric
253def validate_entries(soup):
254  """
255  Validate all <entry> elements with the following rules:
256    * If there is a container="$foo" attribute, there is a <$foo> child
257    * If there is a type="enum" attribute, there is an <enum> child
258    * In the <enum> child, all <value id="$x"> have a numeric $x
259
260  Args:
261    soup - an instance of BeautifulSoup
262
263  Returns:
264    True if the validation succeeds, False otherwise
265  """
266  success = True
267  for entry in soup.find_all("entry"):
268    entry_container = entry.attrs.get('container')
269
270    if entry_container is not None:
271      container_tag = entry.find(entry_container)
272
273      if container_tag is None:
274        success = False
275        validate_error(("Entry '%s' in kind '%s' has type '%s' but " +  \
276                 "missing child element <%s>")                          \
277                 %(fully_qualified_name(entry), find_kind(entry),       \
278                 entry_container, entry_container))
279
280    enum = entry.attrs.get('enum')
281    if enum and enum == 'true':
282      if entry.enum is None:
283        validate_error(("Entry '%s' in kind '%s' is missing enum")     \
284                               % (fully_qualified_name(entry), find_kind(entry),
285                                  ))
286        success = False
287
288      else:
289        for value in entry.enum.find_all('value'):
290          value_id = value.attrs.get('id')
291
292          if value_id is not None:
293            try:
294              id_int = int(value_id, 0) #autoguess base
295            except ValueError:
296              validate_error(("Entry '%s' has id '%s', which is not" + \
297                                        " numeric.")                   \
298                             %(fully_qualified_name(entry), value_id))
299              success = False
300    else:
301      if entry.enum:
302        validate_error(("Entry '%s' kind '%s' has enum el, but no enum attr")  \
303                               % (fully_qualified_name(entry), find_kind(entry),
304                                  ))
305        success = False
306
307    deprecated = entry.attrs.get('deprecated')
308    if deprecated and deprecated == 'true':
309      if entry.deprecation_description is None:
310        validate_error(("Entry '%s' in kind '%s' is deprecated, but missing deprecation description") \
311                       % (fully_qualified_name(entry), find_kind(entry),
312                       ))
313        success = False
314    else:
315      if entry.deprecation_description is not None:
316        validate_error(("Entry '%s' in kind '%s' has deprecation description, but is not deprecated") \
317                       % (fully_qualified_name(entry), find_kind(entry),
318                       ))
319        success = False
320
321  return success
322
323def validate_xml(xml):
324  """
325  Validate all XML nodes according to the rules in validate_clones and
326  validate_entries.
327
328  Args:
329    xml - A string containing a block of XML to validate
330
331  Returns:
332    a BeautifulSoup instance if validation succeeds, None otherwise
333  """
334
335  soup = BeautifulSoup(xml, features='xml')
336
337  succ = validate_clones(soup)
338  succ = validate_entries(soup) and succ
339
340  if succ:
341    return soup
342  else:
343    return None
344
345#####################
346#####################
347
348if __name__ == "__main__":
349  if len(sys.argv) <= 1:
350    print >> sys.stderr, "Usage: %s <filename.xml>" % (sys.argv[0])
351    sys.exit(0)
352
353  file_name = sys.argv[1]
354  succ = validate_xml(file(file_name).read()) is not None
355
356  if succ:
357    print "%s: SUCCESS! Document validated" %(file_name)
358    sys.exit(0)
359  else:
360    print >> sys.stderr, "%s: ERRORS: Document failed to validate" %(file_name)
361    sys.exit(1)
362