1 # -*- coding: utf-8 -*-
3 # Copyright IBM, Corp. 2011
4 # Copyright (c) 2013-2021 Red Hat Inc.
7 # Anthony Liguori <aliguori@us.ibm.com>
8 # Markus Armbruster <armbru@redhat.com>
9 # Eric Blake <eblake@redhat.com>
10 # Marc-André Lureau <marcandre.lureau@redhat.com>
11 # John Snow <jsnow@redhat.com>
13 # This work is licensed under the terms of the GNU GPL, version 2.
14 # See the COPYING file in the top-level directory.
17 Normalize and validate (context-free) QAPI schema expression structures.
19 `QAPISchemaParser` parses a QAPI schema into abstract syntax trees
20 consisting of dict, list, str, bool, and int nodes. This module ensures
21 that these nested structures have the correct type(s) and key(s) where
22 appropriate for the QAPI context-free grammar.
24 The QAPI schema expression language allows for certain syntactic sugar;
25 this module also handles the normalization process of these nested
28 See `check_exprs` for the main entry point.
30 See `schema.QAPISchema` for processing into native Python data
31 structures and contextual semantic validation.
45 from .common
import c_name
46 from .error
import QAPISemError
47 from .parser
import QAPIDoc
48 from .source
import QAPISourceInfo
51 # Deserialized JSON objects as returned by the parser.
52 # The values of this mapping are not necessary to exhaustively type
53 # here (and also not practical as long as mypy lacks recursive
54 # types), because the purpose of this module is to interrogate that
56 _JSONObject
= Dict
[str, object]
59 # See check_name_str(), below.
60 valid_name
= re
.compile(r
'(__[a-z0-9.-]+_)?'
62 r
'([a-z][a-z0-9_-]*)$', re
.IGNORECASE
)
65 def check_name_is_str(name
: object,
69 Ensure that ``name`` is a ``str``.
71 :raise QAPISemError: When ``name`` fails validation.
73 if not isinstance(name
, str):
74 raise QAPISemError(info
, "%s requires a string name" % source
)
77 def check_name_str(name
: str, info
: QAPISourceInfo
, source
: str) -> str:
79 Ensure that ``name`` is a valid QAPI name.
81 A valid name consists of ASCII letters, digits, ``-``, and ``_``,
82 starting with a letter. It may be prefixed by a downstream prefix
83 of the form __RFQDN_, or the experimental prefix ``x-``. If both
84 prefixes are present, the __RFDQN_ prefix goes first.
86 A valid name cannot start with ``q_``, which is reserved.
88 :param name: Name to check.
89 :param info: QAPI schema source file information.
90 :param source: Error string describing what ``name`` belongs to.
92 :raise QAPISemError: When ``name`` fails validation.
93 :return: The stem of the valid name, with no prefixes.
95 # Reserve the entire 'q_' namespace for c_name(), and for 'q_empty'
96 # and 'q_obj_*' implicit type names.
97 match
= valid_name
.match(name
)
98 if not match
or c_name(name
, False).startswith('q_'):
99 raise QAPISemError(info
, "%s has an invalid name" % source
)
100 return match
.group(3)
103 def check_name_upper(name
: str, info
: QAPISourceInfo
, source
: str) -> None:
105 Ensure that ``name`` is a valid event name.
107 This means it must be a valid QAPI name as checked by
108 `check_name_str()`, but where the stem prohibits lowercase
109 characters and ``-``.
111 :param name: Name to check.
112 :param info: QAPI schema source file information.
113 :param source: Error string describing what ``name`` belongs to.
115 :raise QAPISemError: When ``name`` fails validation.
117 stem
= check_name_str(name
, info
, source
)
118 if re
.search(r
'[a-z-]', stem
):
120 info
, "name of %s must not use lowercase or '-'" % source
)
123 def check_name_lower(name
: str, info
: QAPISourceInfo
, source
: str,
124 permit_upper
: bool = False,
125 permit_underscore
: bool = False) -> None:
127 Ensure that ``name`` is a valid command or member name.
129 This means it must be a valid QAPI name as checked by
130 `check_name_str()`, but where the stem prohibits uppercase
131 characters and ``_``.
133 :param name: Name to check.
134 :param info: QAPI schema source file information.
135 :param source: Error string describing what ``name`` belongs to.
136 :param permit_upper: Additionally permit uppercase.
137 :param permit_underscore: Additionally permit ``_``.
139 :raise QAPISemError: When ``name`` fails validation.
141 stem
= check_name_str(name
, info
, source
)
142 if ((not permit_upper
and re
.search(r
'[A-Z]', stem
))
143 or (not permit_underscore
and '_' in stem
)):
145 info
, "name of %s must not use uppercase or '_'" % source
)
148 def check_name_camel(name
: str, info
: QAPISourceInfo
, source
: str) -> None:
150 Ensure that ``name`` is a valid user-defined type name.
152 This means it must be a valid QAPI name as checked by
153 `check_name_str()`, but where the stem must be in CamelCase.
155 :param name: Name to check.
156 :param info: QAPI schema source file information.
157 :param source: Error string describing what ``name`` belongs to.
159 :raise QAPISemError: When ``name`` fails validation.
161 stem
= check_name_str(name
, info
, source
)
162 if not re
.match(r
'[A-Z][A-Za-z0-9]*[a-z][A-Za-z0-9]*$', stem
):
163 raise QAPISemError(info
, "name of %s must use CamelCase" % source
)
166 def check_defn_name_str(name
: str, info
: QAPISourceInfo
, meta
: str) -> None:
168 Ensure that ``name`` is a valid definition name.
170 Based on the value of ``meta``, this means that:
171 - 'event' names adhere to `check_name_upper()`.
172 - 'command' names adhere to `check_name_lower()`.
173 - Else, meta is a type, and must pass `check_name_camel()`.
174 These names must not end with ``Kind`` nor ``List``.
176 :param name: Name to check.
177 :param info: QAPI schema source file information.
178 :param meta: Meta-type name of the QAPI expression.
180 :raise QAPISemError: When ``name`` fails validation.
183 check_name_upper(name
, info
, meta
)
184 elif meta
== 'command':
187 permit_underscore
=name
in info
.pragma
.command_name_exceptions
)
189 check_name_camel(name
, info
, meta
)
190 if name
.endswith('Kind') or name
.endswith('List'):
192 info
, "%s name should not end in '%s'" % (meta
, name
[-4:]))
195 def check_keys(value
: _JSONObject
,
196 info
: QAPISourceInfo
,
198 required
: Collection
[str],
199 optional
: Collection
[str]) -> None:
201 Ensure that a dict has a specific set of keys.
203 :param value: The dict to check.
204 :param info: QAPI schema source file information.
205 :param source: Error string describing this ``value``.
206 :param required: Keys that *must* be present.
207 :param optional: Keys that *may* be present.
209 :raise QAPISemError: When unknown keys are present.
212 def pprint(elems
: Iterable
[str]) -> str:
213 return ', '.join("'" + e
+ "'" for e
in sorted(elems
))
215 missing
= set(required
) - set(value
)
220 % (source
, 's' if len(missing
) > 1 else '',
222 allowed
= set(required
) |
set(optional
)
223 unknown
= set(value
) - allowed
227 "%s has unknown key%s %s\nValid keys are %s."
228 % (source
, 's' if len(unknown
) > 1 else '',
229 pprint(unknown
), pprint(allowed
)))
232 def check_flags(expr
: _JSONObject
, info
: QAPISourceInfo
) -> None:
234 Ensure flag members (if present) have valid values.
236 :param expr: The expression to validate.
237 :param info: QAPI schema source file information.
240 When certain flags have an invalid value, or when
241 incompatible flags are present.
243 for key
in ('gen', 'success-response'):
244 if key
in expr
and expr
[key
] is not False:
246 info
, "flag '%s' may only use false value" % key
)
247 for key
in ('boxed', 'allow-oob', 'allow-preconfig', 'coroutine'):
248 if key
in expr
and expr
[key
] is not True:
250 info
, "flag '%s' may only use true value" % key
)
251 if 'allow-oob' in expr
and 'coroutine' in expr
:
252 # This is not necessarily a fundamental incompatibility, but
253 # we don't have a use case and the desired semantics isn't
254 # obvious. The simplest solution is to forbid it until we get
256 raise QAPISemError(info
, "flags 'allow-oob' and 'coroutine' "
260 def check_if(expr
: _JSONObject
, info
: QAPISourceInfo
, source
: str) -> None:
262 Validate the ``if`` member of an object.
264 The ``if`` member may be either a ``str`` or a dict.
266 :param expr: The expression containing the ``if`` member to validate.
267 :param info: QAPI schema source file information.
268 :param source: Error string describing ``expr``.
271 When the "if" member fails validation, or when there are no
272 non-empty conditions.
276 def _check_if(cond
: Union
[str, object]) -> None:
277 if isinstance(cond
, str):
278 if not re
.match(r
'^[A-Z][A-Z0-9_]*$', cond
):
281 "'if' condition '%s' of %s is not a valid identifier"
285 if not isinstance(cond
, dict):
288 "'if' condition of %s must be a string or an object" % source
)
292 "'if' condition dict of %s must have one key: "
293 "'all', 'any' or 'not'" % source
)
294 check_keys(cond
, info
, "'if' condition", [],
295 ["all", "any", "not"])
297 oper
, operands
= next(iter(cond
.items()))
300 info
, "'if' condition [] of %s is useless" % source
)
305 if oper
in ("all", "any") and not isinstance(operands
, list):
307 info
, "'%s' condition of %s must be an array" % (oper
, source
))
308 for operand
in operands
:
311 ifcond
= expr
.get('if')
318 def normalize_members(members
: object) -> None:
320 Normalize a "members" value.
322 If ``members`` is a dict, for every value in that dict, if that
323 value is not itself already a dict, normalize it to
327 :sugared: ``Dict[str, Union[str, TypeRef]]``
328 :canonical: ``Dict[str, TypeRef]``
330 :param members: The members value to normalize.
332 :return: None, ``members`` is normalized in-place as needed.
334 if isinstance(members
, dict):
335 for key
, arg
in members
.items():
336 if isinstance(arg
, dict):
338 members
[key
] = {'type': arg
}
341 def check_type(value
: Optional
[object],
342 info
: QAPISourceInfo
,
344 allow_array
: bool = False,
345 allow_dict
: Union
[bool, str] = False) -> None:
347 Normalize and validate the QAPI type of ``value``.
349 Python types of ``str`` or ``None`` are always allowed.
351 :param value: The value to check.
352 :param info: QAPI schema source file information.
353 :param source: Error string describing this ``value``.
355 Allow a ``List[str]`` of length 1, which indicates an array of
356 the type named by the list element.
358 Allow a dict. Its members can be struct type members or union
359 branches. When the value of ``allow_dict`` is in pragma
360 ``member-name-exceptions``, the dict's keys may violate the
361 member naming rules. The dict members are normalized in place.
363 :raise QAPISemError: When ``value`` fails validation.
364 :return: None, ``value`` is normalized in-place as needed.
370 if isinstance(value
, str):
374 if isinstance(value
, list):
376 raise QAPISemError(info
, "%s cannot be an array" % source
)
377 if len(value
) != 1 or not isinstance(value
[0], str):
378 raise QAPISemError(info
,
379 "%s: array type must contain single type name" %
386 raise QAPISemError(info
, "%s should be a type name" % source
)
388 if not isinstance(value
, dict):
389 raise QAPISemError(info
,
390 "%s should be an object or type name" % source
)
393 if isinstance(allow_dict
, str):
394 permissive
= allow_dict
in info
.pragma
.member_name_exceptions
396 # value is a dictionary, check that each member is okay
397 for (key
, arg
) in value
.items():
398 key_source
= "%s member '%s'" % (source
, key
)
399 if key
.startswith('*'):
401 check_name_lower(key
, info
, key_source
,
402 permit_upper
=permissive
,
403 permit_underscore
=permissive
)
404 if c_name(key
, False) == 'u' or c_name(key
, False).startswith('has_'):
405 raise QAPISemError(info
, "%s uses reserved name" % key_source
)
406 check_keys(arg
, info
, key_source
, ['type'], ['if', 'features'])
407 check_if(arg
, info
, key_source
)
408 check_features(arg
.get('features'), info
)
409 check_type(arg
['type'], info
, key_source
, allow_array
=True)
412 def check_features(features
: Optional
[object],
413 info
: QAPISourceInfo
) -> None:
415 Normalize and validate the ``features`` member.
417 ``features`` may be a ``list`` of either ``str`` or ``dict``.
418 Any ``str`` element will be normalized to ``{'name': element}``.
421 :sugared: ``List[Union[str, Feature]]``
422 :canonical: ``List[Feature]``
424 :param features: The features member value to validate.
425 :param info: QAPI schema source file information.
427 :raise QAPISemError: When ``features`` fails validation.
428 :return: None, ``features`` is normalized in-place as needed.
432 if not isinstance(features
, list):
433 raise QAPISemError(info
, "'features' must be an array")
434 features
[:] = [f
if isinstance(f
, dict) else {'name': f
}
436 for feat
in features
:
437 source
= "'features' member"
438 assert isinstance(feat
, dict)
439 check_keys(feat
, info
, source
, ['name'], ['if'])
440 check_name_is_str(feat
['name'], info
, source
)
441 source
= "%s '%s'" % (source
, feat
['name'])
442 check_name_str(feat
['name'], info
, source
)
443 check_if(feat
, info
, source
)
446 def check_enum(expr
: _JSONObject
, info
: QAPISourceInfo
) -> None:
448 Normalize and validate this expression as an ``enum`` definition.
450 :param expr: The expression to validate.
451 :param info: QAPI schema source file information.
453 :raise QAPISemError: When ``expr`` is not a valid ``enum``.
454 :return: None, ``expr`` is normalized in-place as needed.
457 members
= expr
['data']
458 prefix
= expr
.get('prefix')
460 if not isinstance(members
, list):
461 raise QAPISemError(info
, "'data' must be an array")
462 if prefix
is not None and not isinstance(prefix
, str):
463 raise QAPISemError(info
, "'prefix' must be a string")
465 permissive
= name
in info
.pragma
.member_name_exceptions
467 members
[:] = [m
if isinstance(m
, dict) else {'name': m
}
469 for member
in members
:
470 source
= "'data' member"
471 check_keys(member
, info
, source
, ['name'], ['if'])
472 member_name
= member
['name']
473 check_name_is_str(member_name
, info
, source
)
474 source
= "%s '%s'" % (source
, member_name
)
475 # Enum members may start with a digit
476 if member_name
[0].isdigit():
477 member_name
= 'd' + member_name
# Hack: hide the digit
478 check_name_lower(member_name
, info
, source
,
479 permit_upper
=permissive
,
480 permit_underscore
=permissive
)
481 check_if(member
, info
, source
)
484 def check_struct(expr
: _JSONObject
, info
: QAPISourceInfo
) -> None:
486 Normalize and validate this expression as a ``struct`` definition.
488 :param expr: The expression to validate.
489 :param info: QAPI schema source file information.
491 :raise QAPISemError: When ``expr`` is not a valid ``struct``.
492 :return: None, ``expr`` is normalized in-place as needed.
494 name
= cast(str, expr
['struct']) # Checked in check_exprs
495 members
= expr
['data']
497 check_type(members
, info
, "'data'", allow_dict
=name
)
498 check_type(expr
.get('base'), info
, "'base'")
501 def check_union(expr
: _JSONObject
, info
: QAPISourceInfo
) -> None:
503 Normalize and validate this expression as a ``union`` definition.
505 :param expr: The expression to validate.
506 :param info: QAPI schema source file information.
508 :raise QAPISemError: when ``expr`` is not a valid ``union``.
509 :return: None, ``expr`` is normalized in-place as needed.
511 name
= cast(str, expr
['union']) # Checked in check_exprs
512 base
= expr
.get('base')
513 discriminator
= expr
.get('discriminator')
514 members
= expr
['data']
516 if discriminator
is None: # simple union
518 raise QAPISemError(info
, "'base' requires 'discriminator'")
520 check_type(base
, info
, "'base'", allow_dict
=name
)
522 raise QAPISemError(info
, "'discriminator' requires 'base'")
523 check_name_is_str(discriminator
, info
, "'discriminator'")
525 if not isinstance(members
, dict):
526 raise QAPISemError(info
, "'data' must be an object")
528 for (key
, value
) in members
.items():
529 source
= "'data' member '%s'" % key
530 if discriminator
is None:
531 check_name_lower(key
, info
, source
)
532 # else: name is in discriminator enum, which gets checked
533 check_keys(value
, info
, source
, ['type'], ['if'])
534 check_if(value
, info
, source
)
535 check_type(value
['type'], info
, source
, allow_array
=not base
)
538 def check_alternate(expr
: _JSONObject
, info
: QAPISourceInfo
) -> None:
540 Normalize and validate this expression as an ``alternate`` definition.
542 :param expr: The expression to validate.
543 :param info: QAPI schema source file information.
545 :raise QAPISemError: When ``expr`` is not a valid ``alternate``.
546 :return: None, ``expr`` is normalized in-place as needed.
548 members
= expr
['data']
551 raise QAPISemError(info
, "'data' must not be empty")
553 if not isinstance(members
, dict):
554 raise QAPISemError(info
, "'data' must be an object")
556 for (key
, value
) in members
.items():
557 source
= "'data' member '%s'" % key
558 check_name_lower(key
, info
, source
)
559 check_keys(value
, info
, source
, ['type'], ['if'])
560 check_if(value
, info
, source
)
561 check_type(value
['type'], info
, source
)
564 def check_command(expr
: _JSONObject
, info
: QAPISourceInfo
) -> None:
566 Normalize and validate this expression as a ``command`` definition.
568 :param expr: The expression to validate.
569 :param info: QAPI schema source file information.
571 :raise QAPISemError: When ``expr`` is not a valid ``command``.
572 :return: None, ``expr`` is normalized in-place as needed.
574 args
= expr
.get('data')
575 rets
= expr
.get('returns')
576 boxed
= expr
.get('boxed', False)
578 if boxed
and args
is None:
579 raise QAPISemError(info
, "'boxed': true requires 'data'")
580 check_type(args
, info
, "'data'", allow_dict
=not boxed
)
581 check_type(rets
, info
, "'returns'", allow_array
=True)
584 def check_event(expr
: _JSONObject
, info
: QAPISourceInfo
) -> None:
586 Normalize and validate this expression as an ``event`` definition.
588 :param expr: The expression to validate.
589 :param info: QAPI schema source file information.
591 :raise QAPISemError: When ``expr`` is not a valid ``event``.
592 :return: None, ``expr`` is normalized in-place as needed.
594 args
= expr
.get('data')
595 boxed
= expr
.get('boxed', False)
597 if boxed
and args
is None:
598 raise QAPISemError(info
, "'boxed': true requires 'data'")
599 check_type(args
, info
, "'data'", allow_dict
=not boxed
)
602 def check_exprs(exprs
: List
[_JSONObject
]) -> List
[_JSONObject
]:
604 Validate and normalize a list of parsed QAPI schema expressions.
606 This function accepts a list of expressions and metadata as returned
607 by the parser. It destructively normalizes the expressions in-place.
609 :param exprs: The list of expressions to normalize and validate.
611 :raise QAPISemError: When any expression fails validation.
612 :return: The same list of expressions (now modified).
614 for expr_elem
in exprs
:
616 assert isinstance(expr_elem
['expr'], dict)
617 for key
in expr_elem
['expr'].keys():
618 assert isinstance(key
, str)
619 expr
: _JSONObject
= expr_elem
['expr']
622 assert isinstance(expr_elem
['info'], QAPISourceInfo
)
623 info
: QAPISourceInfo
= expr_elem
['info']
626 tmp
= expr_elem
.get('doc')
627 assert tmp
is None or isinstance(tmp
, QAPIDoc
)
628 doc
: Optional
[QAPIDoc
] = tmp
630 if 'include' in expr
:
635 elif 'union' in expr
:
637 elif 'alternate' in expr
:
639 elif 'struct' in expr
:
641 elif 'command' in expr
:
643 elif 'event' in expr
:
646 raise QAPISemError(info
, "expression is missing metatype")
648 check_name_is_str(expr
[meta
], info
, "'%s'" % meta
)
649 name
= cast(str, expr
[meta
])
650 info
.set_defn(meta
, name
)
651 check_defn_name_str(name
, info
, meta
)
654 if doc
.symbol
!= name
:
656 info
, "documentation comment is for '%s'" % doc
.symbol
)
658 elif info
.pragma
.doc_required
:
659 raise QAPISemError(info
,
660 "documentation comment required")
663 check_keys(expr
, info
, meta
,
664 ['enum', 'data'], ['if', 'features', 'prefix'])
665 check_enum(expr
, info
)
666 elif meta
== 'union':
667 check_keys(expr
, info
, meta
,
669 ['base', 'discriminator', 'if', 'features'])
670 normalize_members(expr
.get('base'))
671 normalize_members(expr
['data'])
672 check_union(expr
, info
)
673 elif meta
== 'alternate':
674 check_keys(expr
, info
, meta
,
675 ['alternate', 'data'], ['if', 'features'])
676 normalize_members(expr
['data'])
677 check_alternate(expr
, info
)
678 elif meta
== 'struct':
679 check_keys(expr
, info
, meta
,
680 ['struct', 'data'], ['base', 'if', 'features'])
681 normalize_members(expr
['data'])
682 check_struct(expr
, info
)
683 elif meta
== 'command':
684 check_keys(expr
, info
, meta
,
686 ['data', 'returns', 'boxed', 'if', 'features',
687 'gen', 'success-response', 'allow-oob',
688 'allow-preconfig', 'coroutine'])
689 normalize_members(expr
.get('data'))
690 check_command(expr
, info
)
691 elif meta
== 'event':
692 check_keys(expr
, info
, meta
,
693 ['event'], ['data', 'boxed', 'if', 'features'])
694 normalize_members(expr
.get('data'))
695 check_event(expr
, info
)
697 assert False, 'unexpected meta type'
699 check_if(expr
, info
, meta
)
700 check_features(expr
.get('features'), info
)
701 check_flags(expr
, info
)