On Mon, Jan 15, 2024 at 8:16 AM Markus Armbruster <arm...@redhat.com> wrote:
>
> John Snow <js...@redhat.com> writes:
>
> > Include entities don't have names, but we generally expect "entities" to
> > have names. Reclassify all entities with names as *definitions*, leaving
> > the nameless include entities as QAPISchemaEntity instances.
> >
> > This is primarily to help simplify typing around expectations of what
> > callers expect for properties of an "entity".
> >
> > Suggested-by: Markus Armbruster <arm...@redhat.com>
> > Signed-off-by: John Snow <js...@redhat.com>
> > ---
> > scripts/qapi/schema.py | 117 ++++++++++++++++++++++++-----------------
> > 1 file changed, 70 insertions(+), 47 deletions(-)
> >
> > diff --git a/scripts/qapi/schema.py b/scripts/qapi/schema.py
> > index b7830672e57..e39ed972a80 100644
> > --- a/scripts/qapi/schema.py
> > +++ b/scripts/qapi/schema.py
> > @@ -55,14 +55,14 @@ def is_present(self):
> >
> >
> > class QAPISchemaEntity:
> > - meta: Optional[str] = None
> > + """
> > + QAPISchemaEntity represents all schema entities.
> >
> > - def __init__(self, name: str, info, doc, ifcond=None, features=None):
> > - assert name is None or isinstance(name, str)
> > - for f in features or []:
> > - assert isinstance(f, QAPISchemaFeature)
> > - f.set_defined_in(name)
> > - self.name = name
> > + Notably, this includes both named and un-named entities, such as
> > + include directives. Entities with names are represented by the
> > + more specific sub-class `QAPISchemaDefinition` instead.
> > + """
>
> Hmm. What about:
>
> """
> A schema entity.
>
> This is either a directive, such as include, or a definition.
> The latter use sub-class `QAPISchemaDefinition`.
> """
>
Sure. Key point was just the cookie crumb to the sub-class.
> > + def __init__(self, info):
> > self._module = None
> > # For explicitly defined entities, info points to the (explicit)
> > # definition. For builtins (and their arrays), info is None.
> > @@ -70,14 +70,50 @@ def __init__(self, name: str, info, doc, ifcond=None,
> > features=None):
> > # triggered the implicit definition (there may be more than one
> > # such place).
> > self.info = info
> > + self._checked = False
> > +
> > + def __repr__(self):
> > + return "<%s at 0x%x>" % (type(self).__name__, id(self))
> > +
> > + def check(self, schema):
> > + # pylint: disable=unused-argument
> > + self._checked = True
> > +
> > + def connect_doc(self, doc=None):
> > + pass
> > +
> > + def check_doc(self):
> > + pass
> > +
> > + def _set_module(self, schema, info):
> > + assert self._checked
> > + fname = info.fname if info else
> > QAPISchemaModule.BUILTIN_MODULE_NAME
> > + self._module = schema.module_by_fname(fname)
> > + self._module.add_entity(self)
> > +
> > + def set_module(self, schema):
> > + self._set_module(schema, self.info)
> > +
> > + def visit(self, visitor):
> > + # pylint: disable=unused-argument
> > + assert self._checked
> > +
> > +
> > +class QAPISchemaDefinition(QAPISchemaEntity):
> > + meta: Optional[str] = None
> > +
> > + def __init__(self, name: str, info, doc, ifcond=None, features=None):
> > + assert isinstance(name, str)
> > + super().__init__(info)
> > + for f in features or []:
> > + assert isinstance(f, QAPISchemaFeature)
> > + f.set_defined_in(name)
> > + self.name = name
> > self.doc = doc
> > self._ifcond = ifcond or QAPISchemaIfCond()
> > self.features = features or []
> > - self._checked = False
> >
> > def __repr__(self):
> > - if self.name is None:
> > - return "<%s at 0x%x>" % (type(self).__name__, id(self))
> > return "<%s:%s at 0x%x>" % (type(self).__name__, self.name,
> > id(self))
> >
> > @@ -102,15 +138,6 @@ def check_doc(self):
> def check(self, schema):
> # pylint: disable=unused-argument
> assert not self._checked
> seen = {}
> for f in self.features:
> f.check_clash(self.info, seen)
> self._checked = True
>
> def connect_doc(self, doc=None):
> doc = doc or self.doc
> if doc:
> for f in self.features:
> doc.connect_feature(f)
>
> def check_doc(self):
> > if self.doc:
> > self.doc.check()
>
> No super().FOO()?
>
Ah, just an oversight. It worked out because the super method doesn't
do anything anyway. check() and connect_doc() should also use the
super call, probably.
> >
> > - def _set_module(self, schema, info):
> > - assert self._checked
> > - fname = info.fname if info else
> > QAPISchemaModule.BUILTIN_MODULE_NAME
> > - self._module = schema.module_by_fname(fname)
> > - self._module.add_entity(self)
> > -
> > - def set_module(self, schema):
> > - self._set_module(schema, self.info)
> > -
> > @property
> > def ifcond(self):
> > assert self._checked
> > @@ -119,10 +146,6 @@ def ifcond(self):
> > def is_implicit(self):
> > return not self.info
> >
> > - def visit(self, visitor):
> > - # pylint: disable=unused-argument
> > - assert self._checked
> > -
> > def describe(self):
> > assert self.meta
> > return "%s '%s'" % (self.meta, self.name)
> > @@ -222,7 +245,7 @@ def visit(self, visitor):
> >
> > class QAPISchemaInclude(QAPISchemaEntity):
> > def __init__(self, sub_module, info):
> > - super().__init__(None, info, None)
> > + super().__init__(info)
> > self._sub_module = sub_module
> >
> > def visit(self, visitor):
> > @@ -230,7 +253,7 @@ def visit(self, visitor):
> > visitor.visit_include(self._sub_module.name, self.info)
> >
> >
> > -class QAPISchemaType(QAPISchemaEntity):
> > +class QAPISchemaType(QAPISchemaDefinition):
> > # Return the C type for common use.
> > # For the types we commonly box, this is a pointer type.
> > def c_type(self):
> > @@ -801,7 +824,7 @@ def __init__(self, name, info, typ, ifcond=None):
> > super().__init__(name, info, typ, False, ifcond)
> >
> >
> > -class QAPISchemaCommand(QAPISchemaEntity):
> > +class QAPISchemaCommand(QAPISchemaDefinition):
> > meta = 'command'
> >
> > def __init__(self, name, info, doc, ifcond, features,
> > @@ -872,7 +895,7 @@ def visit(self, visitor):
> > self.coroutine)
> >
> >
> > -class QAPISchemaEvent(QAPISchemaEntity):
> > +class QAPISchemaEvent(QAPISchemaDefinition):
> > meta = 'event'
> >
> > def __init__(self, name, info, doc, ifcond, features, arg_type, boxed):
> > @@ -943,11 +966,12 @@ def __init__(self, fname):
> > self.check()
> >
> > def _def_entity(self, ent):
> > + self._entity_list.append(ent)
> > +
> > + def _def_definition(self, ent):
>
> Name the argument @defn instead of @ent?
>
OK. (Was aiming for less diffstat, but yes.)
> > # Only the predefined types are allowed to not have info
> > assert ent.info or self._predefining
> > - self._entity_list.append(ent)
> > - if ent.name is None:
> > - return
> > + self._def_entity(ent)
> > # TODO reject names that differ only in '_' vs. '.' vs. '-',
> > # because they're liable to clash in generated C.
> > other_ent = self._entity_dict.get(ent.name)
> > @@ -1001,7 +1025,7 @@ def _def_include(self, expr: QAPIExpression):
> > QAPISchemaInclude(self._make_module(include), expr.info))
> >
> > def _def_builtin_type(self, name, json_type, c_type):
> > - self._def_entity(QAPISchemaBuiltinType(name, json_type, c_type))
> > + self._def_definition(QAPISchemaBuiltinType(name, json_type,
> > c_type))
> > # Instantiating only the arrays that are actually used would
> > # be nice, but we can't as long as their generated code
> > # (qapi-builtin-types.[ch]) may be shared by some other
> > @@ -1027,15 +1051,15 @@ def _def_predefineds(self):
> > self._def_builtin_type(*t)
> > self.the_empty_object_type = QAPISchemaObjectType(
> > 'q_empty', None, None, None, None, None, [], None)
> > - self._def_entity(self.the_empty_object_type)
> > + self._def_definition(self.the_empty_object_type)
> >
> > qtypes = ['none', 'qnull', 'qnum', 'qstring', 'qdict', 'qlist',
> > 'qbool']
> > qtype_values = self._make_enum_members(
> > [{'name': n} for n in qtypes], None)
> >
> > - self._def_entity(QAPISchemaEnumType('QType', None, None, None,
> > None,
> > - qtype_values, 'QTYPE'))
> > + self._def_definition(QAPISchemaEnumType('QType', None, None, None,
> > + None, qtype_values,
> > 'QTYPE'))
>
> The long identifiers squeeze the (also long) argument list against the
> right margin. What about:
>
> self._def_definition(QAPISchemaEnumType(
> 'QType', None, None, None, None, qtype_values, 'QTYPE'))
This is fine to my eyes.
>
> or
>
> self._def_definition(
> QAPISchemaEnumType('QType', None, None, None, None,
> qtype_values, 'QTYPE'))
>
> We already use the former style elsewhere, visible below.
>
> You add one in the latter style in the second to last hunk.
>
> Pick one style and stick ot it?
Yeah. I might try to run the black formatter in the end and just stick
to that, if you don't mind a bit of churn in exchange for having it be
a bit more mindless. It would be a big hassle to run it at the
beginning of the series now, though... but I'll fix this instance for
now.
>
> >
> > def _make_features(self, features, info):
> > if features is None:
> > @@ -1057,7 +1081,7 @@ def _make_enum_members(self, values, info):
> > def _make_array_type(self, element_type, info):
> > name = element_type + 'List' # reserved by check_defn_name_str()
> > if not self.lookup_type(name):
> > - self._def_entity(QAPISchemaArrayType(name, info, element_type))
> > + self._def_definition(QAPISchemaArrayType(name, info,
> > element_type))
>
> self._def_definition(QAPISchemaArrayType(
> name, info, element_type))
>
> or
>
> self._def_definition(
> QAPISchemaArrayType(name, info, element_type))
>
OK. (79 columns too long for ya?)
> > return name
> >
> > def _make_implicit_object_type(self, name, info, ifcond, role,
> > members):
> > @@ -1072,7 +1096,7 @@ def _make_implicit_object_type(self, name, info,
> > ifcond, role, members):
> > # later.
> > pass
> > else:
> > - self._def_entity(QAPISchemaObjectType(
> > + self._def_definition(QAPISchemaObjectType(
> > name, info, None, ifcond, None, None, members, None))
> > return name
> >
> > @@ -1083,7 +1107,7 @@ def _def_enum_type(self, expr: QAPIExpression):
> > ifcond = QAPISchemaIfCond(expr.get('if'))
> > info = expr.info
> > features = self._make_features(expr.get('features'), info)
> > - self._def_entity(QAPISchemaEnumType(
> > + self._def_definition(QAPISchemaEnumType(
> > name, info, expr.doc, ifcond, features,
> > self._make_enum_members(data, info), prefix))
> >
> > @@ -1111,7 +1135,7 @@ def _def_struct_type(self, expr: QAPIExpression):
> > info = expr.info
> > ifcond = QAPISchemaIfCond(expr.get('if'))
> > features = self._make_features(expr.get('features'), info)
> > - self._def_entity(QAPISchemaObjectType(
> > + self._def_definition(QAPISchemaObjectType(
> > name, info, expr.doc, ifcond, features, base,
> > self._make_members(data, info),
> > None))
> > @@ -1141,7 +1165,7 @@ def _def_union_type(self, expr: QAPIExpression):
> > info)
> > for (key, value) in data.items()]
> > members: List[QAPISchemaObjectTypeMember] = []
> > - self._def_entity(
> > + self._def_definition(
> > QAPISchemaObjectType(name, info, expr.doc, ifcond, features,
> > base, members,
> > QAPISchemaVariants(
> > @@ -1160,7 +1184,7 @@ def _def_alternate_type(self, expr: QAPIExpression):
> > info)
> > for (key, value) in data.items()]
> > tag_member = QAPISchemaObjectTypeMember('type', info, 'QType',
> > False)
> > - self._def_entity(
> > + self._def_definition(
> > QAPISchemaAlternateType(
> > name, info, expr.doc, ifcond, features,
> > QAPISchemaVariants(None, info, tag_member, variants)))
> > @@ -1185,11 +1209,10 @@ def _def_command(self, expr: QAPIExpression):
> > if isinstance(rets, list):
> > assert len(rets) == 1
> > rets = self._make_array_type(rets[0], info)
> > - self._def_entity(QAPISchemaCommand(name, info, expr.doc, ifcond,
> > - features, data, rets,
> > - gen, success_response,
> > - boxed, allow_oob,
> > allow_preconfig,
> > - coroutine))
> > + self._def_definition(
> > + QAPISchemaCommand(name, info, expr.doc, ifcond, features, data,
> > + rets, gen, success_response, boxed,
> > allow_oob,
> > + allow_preconfig, coroutine))
> >
> > def _def_event(self, expr: QAPIExpression):
> > name = expr['event']
> > @@ -1202,8 +1225,8 @@ def _def_event(self, expr: QAPIExpression):
> > data = self._make_implicit_object_type(
> > name, info, ifcond,
> > 'arg', self._make_members(data, info))
> > - self._def_entity(QAPISchemaEvent(name, info, expr.doc, ifcond,
> > - features, data, boxed))
> > + self._def_definition(QAPISchemaEvent(name, info, expr.doc, ifcond,
> > + features, data, boxed))
> >
> > def _def_exprs(self, exprs):
> > for expr in exprs:
>
> Slightly more code, but with slightly fewer conditionals. Feels a bit
> cleaner.
>
Probably a few more asserts and things that can come out, too. It's
nicer for static types at the expense of more OO boilerplate.
