[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
[PATCH v4 08/13] qapi/parser: add import cycle workaround
From: |
John Snow |
Subject: |
[PATCH v4 08/13] qapi/parser: add import cycle workaround |
Date: |
Thu, 30 Sep 2021 16:57:11 -0400 |
Adding static types causes a cycle in the QAPI generator:
[schema -> expr -> parser -> schema]. It exists because the QAPIDoc
class needs the names of types defined by the schema module, but the
schema module needs to import both expr.py/parser.py to do its actual
parsing.
Ultimately, the layering violation is that parser.py should not have any
knowledge of specifics of the Schema. QAPIDoc performs double-duty here
both as a parser *and* as a finalized object that is part of the schema.
In this patch, add the offending type hints alongside the workaround to
avoid the cycle becoming a problem at runtime. See
https://mypy.readthedocs.io/en/latest/runtime_troubles.html#import-cycles
for more information on this workaround technique.
I see three ultimate resolutions here:
(1) Just keep this patch and use the TYPE_CHECKING trick to eliminate
the cycle which is only present during static analysis.
(2) Don't bother to annotate connect_member() et al, give them 'object'
or 'Any'. I don't particularly like this, because it diminishes the
usefulness of type hints for documentation purposes. Still, it's an
extremely quick fix.
(3) Reimplement doc <--> definition correlation directly in schema.py,
integrating doc fields directly into QAPISchemaMember and relieving
the QAPIDoc class of the responsibility. Users of the information
would instead visit the members first and retrieve their
documentation instead of the inverse operation -- visiting the
documentation and retrieving their members.
My preference is (3), but in the short-term (1) is the easiest way to
have my cake (strong type hints) and eat it too (Not have import
cycles). Do (1) for now, but plan for (3).
Signed-off-by: John Snow <jsnow@redhat.com>
---
scripts/qapi/parser.py | 15 +++++++++++----
1 file changed, 11 insertions(+), 4 deletions(-)
diff --git a/scripts/qapi/parser.py b/scripts/qapi/parser.py
index 40c5da4b172..75582ddb003 100644
--- a/scripts/qapi/parser.py
+++ b/scripts/qapi/parser.py
@@ -18,6 +18,7 @@
import os
import re
from typing import (
+ TYPE_CHECKING,
Dict,
List,
Optional,
@@ -30,6 +31,12 @@
from .source import QAPISourceInfo
+if TYPE_CHECKING:
+ # pylint: disable=cyclic-import
+ # TODO: Remove cycle. [schema -> expr -> parser -> schema]
+ from .schema import QAPISchemaFeature, QAPISchemaMember
+
+
# Return value alias for get_expr().
_ExprValue = Union[List[object], Dict[str, object], str, bool]
@@ -473,9 +480,9 @@ def append(self, line):
class ArgSection(Section):
def __init__(self, parser, name, indent=0):
super().__init__(parser, name, indent)
- self.member = None
+ self.member: Optional['QAPISchemaMember'] = None
- def connect(self, member):
+ def connect(self, member: 'QAPISchemaMember') -> None:
self.member = member
class NullSection(Section):
@@ -747,14 +754,14 @@ def _append_freeform(self, line):
% match.group(1))
self._section.append(line)
- def connect_member(self, member):
+ def connect_member(self, member: 'QAPISchemaMember') -> None:
if member.name not in self.args:
# Undocumented TODO outlaw
self.args[member.name] = QAPIDoc.ArgSection(self._parser,
member.name)
self.args[member.name].connect(member)
- def connect_feature(self, feature):
+ def connect_feature(self, feature: 'QAPISchemaFeature') -> None:
if feature.name not in self.features:
raise QAPISemError(feature.info,
"feature '%s' lacks documentation"
--
2.31.1
- [PATCH v4 00/13] qapi: static typing conversion, pt5b, John Snow, 2021/09/30
- [PATCH v4 01/13] qapi/pylintrc: ignore 'consider-using-f-string' warning, John Snow, 2021/09/30
- [PATCH v4 02/13] qapi/gen: use dict.items() to iterate over _modules, John Snow, 2021/09/30
- [PATCH v4 04/13] qapi: Add spaces after symbol declaration for consistency, John Snow, 2021/09/30
- [PATCH v4 05/13] qapi/parser: remove FIXME comment from _append_body_line, John Snow, 2021/09/30
- [PATCH v4 03/13] qapi/parser: fix unused check_args_section arguments, John Snow, 2021/09/30
- [PATCH v4 06/13] qapi/parser: clarify _end_section() logic, John Snow, 2021/09/30
- [PATCH v4 07/13] qapi/parser: Introduce NullSection, John Snow, 2021/09/30
- [PATCH v4 08/13] qapi/parser: add import cycle workaround,
John Snow <=
- [PATCH v4 11/13] qapi/parser: enable mypy checks, John Snow, 2021/09/30
- [PATCH v4 10/13] qapi/parser: Add FIXME for consolidating JSON-related types, John Snow, 2021/09/30
- [PATCH v4 12/13] qapi/parser: Silence too-few-public-methods warning, John Snow, 2021/09/30
- [PATCH v4 13/13] qapi/parser: enable pylint checks, John Snow, 2021/09/30
- [PATCH v4 09/13] qapi/parser: add type hint annotations (QAPIDoc), John Snow, 2021/09/30