qapi/parser: make remaining subsection members "private"
These fields are used to provide error checking and internal logistics and should not be used by a user of the library to directly access documentation sections, so make them private. The "since" field alone is left public, as the qapidoc generator does use this field to pull that section out of the regular flow of the document. Signed-off-by: John Snow <jsnow@redhat.com> Message-ID: <20260611042332.482979-6-jsnow@redhat.com> Reviewed-by: Markus Armbruster <armbru@redhat.com> [Commit message tweaked] Signed-off-by: Markus Armbruster <armbru@redhat.com>
John Snow committed
Jun 11, 2026 at 00:23 UTC
18fb1e1a79069a1befa37421748a6ff08d4575d6
1 file changed
+24
-24
scripts/qapi/parser.py
+24
-24
@@ -733,17 +733,17 @@ class QAPIDoc:
733
QAPIDoc.Section(info, QAPIDoc.Kind.PLAIN)
734
]
735
# dicts mapping parameter/feature names to their description
736
- self.args: Dict[str, QAPIDoc.ArgSection] = {}
737
- self.features: Dict[str, QAPIDoc.ArgSection] = {}
736
+ self._args: Dict[str, QAPIDoc.ArgSection] = {}
737
+ self._features: Dict[str, QAPIDoc.ArgSection] = {}
738
# a command's "Returns" and "Errors" section
739
- self.returns: Optional[QAPIDoc.Section] = None
740
- self.errors: Optional[QAPIDoc.Section] = None
739
+ self._returns: Optional[QAPIDoc.Section] = None
740
+ self._errors: Optional[QAPIDoc.Section] = None
741
# "Since" section
742
self.since: Optional[QAPIDoc.Section] = None
743
744
@property
745
def has_features(self) -> bool:
746
- return bool(self.features)
746
+ return bool(self._features)
747
748
def end(self) -> None:
749
for section in self.all_sections:
@@ -775,15 +775,15 @@ class QAPIDoc:
775
) -> None:
776
section = self.Section(info, kind)
777
if kind == QAPIDoc.Kind.RETURNS:
778
- if self.returns:
778
+ if self._returns:
779
raise QAPISemError(
780
info, "duplicated '%s' section" % kind)
781
- self.returns = section
781
+ self._returns = section
782
elif kind == QAPIDoc.Kind.ERRORS:
783
- if self.errors:
783
+ if self._errors:
784
raise QAPISemError(
785
info, "duplicated '%s' section" % kind)
786
- self.errors = section
786
+ self._errors = section
787
elif kind == QAPIDoc.Kind.SINCE:
788
if self.since:
789
raise QAPISemError(
@@ -807,16 +807,16 @@ class QAPIDoc:
807
desc[name] = section
808
809
def new_argument(self, info: QAPISourceInfo, name: str) -> None:
810
- self._new_description(info, name, QAPIDoc.Kind.MEMBER, self.args)
810
+ self._new_description(info, name, QAPIDoc.Kind.MEMBER, self._args)
811
812
def new_feature(self, info: QAPISourceInfo, name: str) -> None:
813
- self._new_description(info, name, QAPIDoc.Kind.FEATURE, self.features)
813
+ self._new_description(info, name, QAPIDoc.Kind.FEATURE, self._features)
814
815
def append_line(self, line: str) -> None:
816
self.all_sections[-1].append_line(line)
817
818
def connect_member(self, member: 'QAPISchemaMember') -> None:
819
- if member.name not in self.args:
819
+ if member.name not in self._args:
820
assert member.info
821
if self.symbol not in member.info.pragma.documentation_exceptions:
822
raise QAPISemError(member.info,
@@ -827,7 +827,7 @@ class QAPIDoc:
827
828
section = QAPIDoc.ArgSection(
829
self.info, QAPIDoc.Kind.MEMBER, member.name)
830
- self.args[member.name] = section
830
+ self._args[member.name] = section
831
832
# Determine where to insert stub doc - it should go at the
833
# end of the members section(s), if any. Note that index 0
@@ -839,14 +839,14 @@ class QAPIDoc:
839
index += 1
840
self.all_sections.insert(index, section)
841
842
- self.args[member.name].connect(member)
842
+ self._args[member.name].connect(member)
843
844
def connect_feature(self, feature: 'QAPISchemaFeature') -> None:
845
- if feature.name not in self.features:
845
+ if feature.name not in self._features:
846
raise QAPISemError(feature.info,
847
"feature '%s' lacks documentation"
848
% feature.name)
849
- self.features[feature.name].connect(feature)
849
+ self._features[feature.name].connect(feature)
850
851
def ensure_returns(self, info: QAPISourceInfo) -> None:
852
@@ -887,18 +887,18 @@ class QAPIDoc:
887
888
def check_expr(self, expr: QAPIExpression) -> None:
889
if 'command' in expr:
890
- if self.returns and 'returns' not in expr:
890
+ if self._returns and 'returns' not in expr:
891
raise QAPISemError(
892
- self.returns.info,
892
+ self._returns.info,
893
"'Returns' section, but command doesn't return anything")
894
else:
895
- if self.returns:
895
+ if self._returns:
896
raise QAPISemError(
897
- self.returns.info,
897
+ self._returns.info,
898
"'Returns' section is only valid for commands")
899
- if self.errors:
899
+ if self._errors:
900
raise QAPISemError(
901
- self.errors.info,
901
+ self._errors.info,
902
"'Errors' section is only valid for commands")
903
904
def check(self) -> None:
@@ -918,5 +918,5 @@ class QAPIDoc:
918
"do" if len(bogus) > 1 else "does"
919
))
920
921
- check_args_section(self.args, 'member')
922
- check_args_section(self.features, 'feature')
921
+ check_args_section(self._args, 'member')
922
+ check_args_section(self._features, 'feature')