7a783ce5b5
Casts are instructions to the type checker only, they aren't "safe" and should probably be avoided in general. In this case, when we perform type checking on a nested structure, the type of each field does not "stick". (See PEP 647 for an example of "type narrowing" that does "stick". It is available in Python 3.10, so we can't use it yet.) We don't need to assert that something is a str if we've already checked or asserted that it is -- use a cast instead for these cases. Signed-off-by: John Snow <jsnow@redhat.com> Message-Id: <20210421182032.3521476-9-jsnow@redhat.com> Reviewed-by: Markus Armbruster <armbru@redhat.com> Signed-off-by: Markus Armbruster <armbru@redhat.com>
427 lines
14 KiB
Python
427 lines
14 KiB
Python
# -*- coding: utf-8 -*-
|
|
#
|
|
# Check (context-free) QAPI schema expression structure
|
|
#
|
|
# Copyright IBM, Corp. 2011
|
|
# Copyright (c) 2013-2019 Red Hat Inc.
|
|
#
|
|
# Authors:
|
|
# Anthony Liguori <aliguori@us.ibm.com>
|
|
# Markus Armbruster <armbru@redhat.com>
|
|
# Eric Blake <eblake@redhat.com>
|
|
# Marc-André Lureau <marcandre.lureau@redhat.com>
|
|
#
|
|
# This work is licensed under the terms of the GNU GPL, version 2.
|
|
# See the COPYING file in the top-level directory.
|
|
|
|
import re
|
|
from typing import Dict, Optional, cast
|
|
|
|
from .common import c_name
|
|
from .error import QAPISemError
|
|
from .parser import QAPIDoc
|
|
from .source import QAPISourceInfo
|
|
|
|
|
|
# Deserialized JSON objects as returned by the parser.
|
|
# The values of this mapping are not necessary to exhaustively type
|
|
# here (and also not practical as long as mypy lacks recursive
|
|
# types), because the purpose of this module is to interrogate that
|
|
# type.
|
|
_JSONObject = Dict[str, object]
|
|
|
|
|
|
# Names consist of letters, digits, -, and _, starting with a letter.
|
|
# An experimental name is prefixed with x-. A name of a downstream
|
|
# extension is prefixed with __RFQDN_. The latter prefix goes first.
|
|
valid_name = re.compile(r'(__[a-z0-9.-]+_)?'
|
|
r'(x-)?'
|
|
r'([a-z][a-z0-9_-]*)$', re.IGNORECASE)
|
|
|
|
|
|
def check_name_is_str(name, info, source):
|
|
if not isinstance(name, str):
|
|
raise QAPISemError(info, "%s requires a string name" % source)
|
|
|
|
|
|
def check_name_str(name, info, source):
|
|
# Reserve the entire 'q_' namespace for c_name(), and for 'q_empty'
|
|
# and 'q_obj_*' implicit type names.
|
|
match = valid_name.match(name)
|
|
if not match or c_name(name, False).startswith('q_'):
|
|
raise QAPISemError(info, "%s has an invalid name" % source)
|
|
return match.group(3)
|
|
|
|
|
|
def check_name_upper(name, info, source):
|
|
stem = check_name_str(name, info, source)
|
|
if re.search(r'[a-z-]', stem):
|
|
raise QAPISemError(
|
|
info, "name of %s must not use lowercase or '-'" % source)
|
|
|
|
|
|
def check_name_lower(name, info, source,
|
|
permit_upper=False,
|
|
permit_underscore=False):
|
|
stem = check_name_str(name, info, source)
|
|
if ((not permit_upper and re.search(r'[A-Z]', stem))
|
|
or (not permit_underscore and '_' in stem)):
|
|
raise QAPISemError(
|
|
info, "name of %s must not use uppercase or '_'" % source)
|
|
|
|
|
|
def check_name_camel(name, info, source):
|
|
stem = check_name_str(name, info, source)
|
|
if not re.match(r'[A-Z][A-Za-z0-9]*[a-z][A-Za-z0-9]*$', stem):
|
|
raise QAPISemError(info, "name of %s must use CamelCase" % source)
|
|
|
|
|
|
def check_defn_name_str(name, info, meta):
|
|
if meta == 'event':
|
|
check_name_upper(name, info, meta)
|
|
elif meta == 'command':
|
|
check_name_lower(
|
|
name, info, meta,
|
|
permit_underscore=name in info.pragma.command_name_exceptions)
|
|
else:
|
|
check_name_camel(name, info, meta)
|
|
if name.endswith('Kind') or name.endswith('List'):
|
|
raise QAPISemError(
|
|
info, "%s name should not end in '%s'" % (meta, name[-4:]))
|
|
|
|
|
|
def check_keys(value, info, source, required, optional):
|
|
|
|
def pprint(elems):
|
|
return ', '.join("'" + e + "'" for e in sorted(elems))
|
|
|
|
missing = set(required) - set(value)
|
|
if missing:
|
|
raise QAPISemError(
|
|
info,
|
|
"%s misses key%s %s"
|
|
% (source, 's' if len(missing) > 1 else '',
|
|
pprint(missing)))
|
|
allowed = set(required + optional)
|
|
unknown = set(value) - allowed
|
|
if unknown:
|
|
raise QAPISemError(
|
|
info,
|
|
"%s has unknown key%s %s\nValid keys are %s."
|
|
% (source, 's' if len(unknown) > 1 else '',
|
|
pprint(unknown), pprint(allowed)))
|
|
|
|
|
|
def check_flags(expr, info):
|
|
for key in ['gen', 'success-response']:
|
|
if key in expr and expr[key] is not False:
|
|
raise QAPISemError(
|
|
info, "flag '%s' may only use false value" % key)
|
|
for key in ['boxed', 'allow-oob', 'allow-preconfig', 'coroutine']:
|
|
if key in expr and expr[key] is not True:
|
|
raise QAPISemError(
|
|
info, "flag '%s' may only use true value" % key)
|
|
if 'allow-oob' in expr and 'coroutine' in expr:
|
|
# This is not necessarily a fundamental incompatibility, but
|
|
# we don't have a use case and the desired semantics isn't
|
|
# obvious. The simplest solution is to forbid it until we get
|
|
# a use case for it.
|
|
raise QAPISemError(info, "flags 'allow-oob' and 'coroutine' "
|
|
"are incompatible")
|
|
|
|
|
|
def check_if(expr, info, source):
|
|
|
|
def check_if_str(ifcond):
|
|
if not isinstance(ifcond, str):
|
|
raise QAPISemError(
|
|
info,
|
|
"'if' condition of %s must be a string or a list of strings"
|
|
% source)
|
|
if ifcond.strip() == '':
|
|
raise QAPISemError(
|
|
info,
|
|
"'if' condition '%s' of %s makes no sense"
|
|
% (ifcond, source))
|
|
|
|
ifcond = expr.get('if')
|
|
if ifcond is None:
|
|
return
|
|
if isinstance(ifcond, list):
|
|
if ifcond == []:
|
|
raise QAPISemError(
|
|
info, "'if' condition [] of %s is useless" % source)
|
|
for elt in ifcond:
|
|
check_if_str(elt)
|
|
else:
|
|
check_if_str(ifcond)
|
|
expr['if'] = [ifcond]
|
|
|
|
|
|
def normalize_members(members):
|
|
if isinstance(members, dict):
|
|
for key, arg in members.items():
|
|
if isinstance(arg, dict):
|
|
continue
|
|
members[key] = {'type': arg}
|
|
|
|
|
|
def check_type(value, info, source,
|
|
allow_array=False, allow_dict=False):
|
|
if value is None:
|
|
return
|
|
|
|
# Type name
|
|
if isinstance(value, str):
|
|
return
|
|
|
|
# Array type
|
|
if isinstance(value, list):
|
|
if not allow_array:
|
|
raise QAPISemError(info, "%s cannot be an array" % source)
|
|
if len(value) != 1 or not isinstance(value[0], str):
|
|
raise QAPISemError(info,
|
|
"%s: array type must contain single type name" %
|
|
source)
|
|
return
|
|
|
|
# Anonymous type
|
|
|
|
if not allow_dict:
|
|
raise QAPISemError(info, "%s should be a type name" % source)
|
|
|
|
if not isinstance(value, dict):
|
|
raise QAPISemError(info,
|
|
"%s should be an object or type name" % source)
|
|
|
|
permissive = False
|
|
if isinstance(allow_dict, str):
|
|
permissive = allow_dict in info.pragma.member_name_exceptions
|
|
|
|
# value is a dictionary, check that each member is okay
|
|
for (key, arg) in value.items():
|
|
key_source = "%s member '%s'" % (source, key)
|
|
if key.startswith('*'):
|
|
key = key[1:]
|
|
check_name_lower(key, info, key_source,
|
|
permit_upper=permissive,
|
|
permit_underscore=permissive)
|
|
if c_name(key, False) == 'u' or c_name(key, False).startswith('has_'):
|
|
raise QAPISemError(info, "%s uses reserved name" % key_source)
|
|
check_keys(arg, info, key_source, ['type'], ['if', 'features'])
|
|
check_if(arg, info, key_source)
|
|
check_features(arg.get('features'), info)
|
|
check_type(arg['type'], info, key_source, allow_array=True)
|
|
|
|
|
|
def check_features(features, info):
|
|
if features is None:
|
|
return
|
|
if not isinstance(features, list):
|
|
raise QAPISemError(info, "'features' must be an array")
|
|
features[:] = [f if isinstance(f, dict) else {'name': f}
|
|
for f in features]
|
|
for f in features:
|
|
source = "'features' member"
|
|
assert isinstance(f, dict)
|
|
check_keys(f, info, source, ['name'], ['if'])
|
|
check_name_is_str(f['name'], info, source)
|
|
source = "%s '%s'" % (source, f['name'])
|
|
check_name_lower(f['name'], info, source)
|
|
check_if(f, info, source)
|
|
|
|
|
|
def check_enum(expr, info):
|
|
name = expr['enum']
|
|
members = expr['data']
|
|
prefix = expr.get('prefix')
|
|
|
|
if not isinstance(members, list):
|
|
raise QAPISemError(info, "'data' must be an array")
|
|
if prefix is not None and not isinstance(prefix, str):
|
|
raise QAPISemError(info, "'prefix' must be a string")
|
|
|
|
permissive = name in info.pragma.member_name_exceptions
|
|
|
|
members[:] = [m if isinstance(m, dict) else {'name': m}
|
|
for m in members]
|
|
for member in members:
|
|
source = "'data' member"
|
|
member_name = member['name']
|
|
check_keys(member, info, source, ['name'], ['if'])
|
|
check_name_is_str(member_name, info, source)
|
|
source = "%s '%s'" % (source, member_name)
|
|
# Enum members may start with a digit
|
|
if member_name[0].isdigit():
|
|
member_name = 'd' + member_name # Hack: hide the digit
|
|
check_name_lower(member_name, info, source,
|
|
permit_upper=permissive,
|
|
permit_underscore=permissive)
|
|
check_if(member, info, source)
|
|
|
|
|
|
def check_struct(expr, info):
|
|
name = cast(str, expr['struct']) # Checked in check_exprs
|
|
members = expr['data']
|
|
|
|
check_type(members, info, "'data'", allow_dict=name)
|
|
check_type(expr.get('base'), info, "'base'")
|
|
|
|
|
|
def check_union(expr, info):
|
|
name = cast(str, expr['union']) # Checked in check_exprs
|
|
base = expr.get('base')
|
|
discriminator = expr.get('discriminator')
|
|
members = expr['data']
|
|
|
|
if discriminator is None: # simple union
|
|
if base is not None:
|
|
raise QAPISemError(info, "'base' requires 'discriminator'")
|
|
else: # flat union
|
|
check_type(base, info, "'base'", allow_dict=name)
|
|
if not base:
|
|
raise QAPISemError(info, "'discriminator' requires 'base'")
|
|
check_name_is_str(discriminator, info, "'discriminator'")
|
|
|
|
if not isinstance(members, dict):
|
|
raise QAPISemError(info, "'data' must be an object")
|
|
|
|
for (key, value) in members.items():
|
|
source = "'data' member '%s'" % key
|
|
if discriminator is None:
|
|
check_name_lower(key, info, source)
|
|
# else: name is in discriminator enum, which gets checked
|
|
check_keys(value, info, source, ['type'], ['if'])
|
|
check_if(value, info, source)
|
|
check_type(value['type'], info, source, allow_array=not base)
|
|
|
|
|
|
def check_alternate(expr, info):
|
|
members = expr['data']
|
|
|
|
if not members:
|
|
raise QAPISemError(info, "'data' must not be empty")
|
|
|
|
if not isinstance(members, dict):
|
|
raise QAPISemError(info, "'data' must be an object")
|
|
|
|
for (key, value) in members.items():
|
|
source = "'data' member '%s'" % key
|
|
check_name_lower(key, info, source)
|
|
check_keys(value, info, source, ['type'], ['if'])
|
|
check_if(value, info, source)
|
|
check_type(value['type'], info, source)
|
|
|
|
|
|
def check_command(expr, info):
|
|
args = expr.get('data')
|
|
rets = expr.get('returns')
|
|
boxed = expr.get('boxed', False)
|
|
|
|
if boxed and args is None:
|
|
raise QAPISemError(info, "'boxed': true requires 'data'")
|
|
check_type(args, info, "'data'", allow_dict=not boxed)
|
|
check_type(rets, info, "'returns'", allow_array=True)
|
|
|
|
|
|
def check_event(expr, info):
|
|
args = expr.get('data')
|
|
boxed = expr.get('boxed', False)
|
|
|
|
if boxed and args is None:
|
|
raise QAPISemError(info, "'boxed': true requires 'data'")
|
|
check_type(args, info, "'data'", allow_dict=not boxed)
|
|
|
|
|
|
def check_exprs(exprs):
|
|
for expr_elem in exprs:
|
|
# Expression
|
|
assert isinstance(expr_elem['expr'], dict)
|
|
for key in expr_elem['expr'].keys():
|
|
assert isinstance(key, str)
|
|
expr: _JSONObject = expr_elem['expr']
|
|
|
|
# QAPISourceInfo
|
|
assert isinstance(expr_elem['info'], QAPISourceInfo)
|
|
info: QAPISourceInfo = expr_elem['info']
|
|
|
|
# Optional[QAPIDoc]
|
|
tmp = expr_elem.get('doc')
|
|
assert tmp is None or isinstance(tmp, QAPIDoc)
|
|
doc: Optional[QAPIDoc] = tmp
|
|
|
|
if 'include' in expr:
|
|
continue
|
|
|
|
if 'enum' in expr:
|
|
meta = 'enum'
|
|
elif 'union' in expr:
|
|
meta = 'union'
|
|
elif 'alternate' in expr:
|
|
meta = 'alternate'
|
|
elif 'struct' in expr:
|
|
meta = 'struct'
|
|
elif 'command' in expr:
|
|
meta = 'command'
|
|
elif 'event' in expr:
|
|
meta = 'event'
|
|
else:
|
|
raise QAPISemError(info, "expression is missing metatype")
|
|
|
|
check_name_is_str(expr[meta], info, "'%s'" % meta)
|
|
name = cast(str, expr[meta])
|
|
info.set_defn(meta, name)
|
|
check_defn_name_str(name, info, meta)
|
|
|
|
if doc:
|
|
if doc.symbol != name:
|
|
raise QAPISemError(
|
|
info, "documentation comment is for '%s'" % doc.symbol)
|
|
doc.check_expr(expr)
|
|
elif info.pragma.doc_required:
|
|
raise QAPISemError(info,
|
|
"documentation comment required")
|
|
|
|
if meta == 'enum':
|
|
check_keys(expr, info, meta,
|
|
['enum', 'data'], ['if', 'features', 'prefix'])
|
|
check_enum(expr, info)
|
|
elif meta == 'union':
|
|
check_keys(expr, info, meta,
|
|
['union', 'data'],
|
|
['base', 'discriminator', 'if', 'features'])
|
|
normalize_members(expr.get('base'))
|
|
normalize_members(expr['data'])
|
|
check_union(expr, info)
|
|
elif meta == 'alternate':
|
|
check_keys(expr, info, meta,
|
|
['alternate', 'data'], ['if', 'features'])
|
|
normalize_members(expr['data'])
|
|
check_alternate(expr, info)
|
|
elif meta == 'struct':
|
|
check_keys(expr, info, meta,
|
|
['struct', 'data'], ['base', 'if', 'features'])
|
|
normalize_members(expr['data'])
|
|
check_struct(expr, info)
|
|
elif meta == 'command':
|
|
check_keys(expr, info, meta,
|
|
['command'],
|
|
['data', 'returns', 'boxed', 'if', 'features',
|
|
'gen', 'success-response', 'allow-oob',
|
|
'allow-preconfig', 'coroutine'])
|
|
normalize_members(expr.get('data'))
|
|
check_command(expr, info)
|
|
elif meta == 'event':
|
|
check_keys(expr, info, meta,
|
|
['event'], ['data', 'boxed', 'if', 'features'])
|
|
normalize_members(expr.get('data'))
|
|
check_event(expr, info)
|
|
else:
|
|
assert False, 'unexpected meta type'
|
|
|
|
check_if(expr, info, meta)
|
|
check_features(expr.get('features'), info)
|
|
check_flags(expr, info)
|
|
|
|
return exprs
|