summaryrefslogtreecommitdiffstats
path: root/scripts/qapi
Commit message (Collapse)AuthorAgeFilesLines
* qapi/visit.py: add type hint annotationsJohn Snow2020-10-102-22/+56
| | | | | | | | | | | | | Annotations do not change runtime behavior. This commit *only* adds annotations. Signed-off-by: John Snow <jsnow@redhat.com> Reviewed-by: Eduardo Habkost <ehabkost@redhat.com> Reviewed-by: Cleber Rosa <crosa@redhat.com> Tested-by: Cleber Rosa <crosa@redhat.com> Message-Id: <20201009161558.107041-37-jsnow@redhat.com> Reviewed-by: Markus Armbruster <armbru@redhat.com> Signed-off-by: Markus Armbruster <armbru@redhat.com>
* qapi/visit.py: remove unused parameters from gen_visit_objectJohn Snow2020-10-102-3/+2Star
| | | | | | | | | | | | | | And this fixes the pylint report for this file, so make sure we check this in the future, too. Signed-off-by: John Snow <jsnow@redhat.com> Reviewed-by: Eduardo Habkost <ehabkost@redhat.com> Reviewed-by: Cleber Rosa <crosa@redhat.com> Tested-by: Cleber Rosa <crosa@redhat.com> Reviewed-by: Philippe Mathieu-Daudé <philmd@redhat.com> Message-Id: <20201009161558.107041-36-jsnow@redhat.com> Reviewed-by: Markus Armbruster <armbru@redhat.com> Signed-off-by: Markus Armbruster <armbru@redhat.com>
* qapi/visit.py: assert tag_member contains a QAPISchemaEnumTypeJohn Snow2020-10-101-5/+7
| | | | | | | | | | | | This is true by design, but not presently able to be expressed in the type system. An assertion helps mypy understand our constraints. Signed-off-by: John Snow <jsnow@redhat.com> Reviewed-by: Eduardo Habkost <ehabkost@redhat.com> Reviewed-by: Cleber Rosa <crosa@redhat.com> Message-Id: <20201009161558.107041-35-jsnow@redhat.com> Reviewed-by: Markus Armbruster <armbru@redhat.com> Signed-off-by: Markus Armbruster <armbru@redhat.com>
* qapi/types.py: remove one-letter variablesJohn Snow2020-10-102-15/+15
| | | | | | | | | | | | | | "John, if pylint told you to jump off a bridge, would you?" Hey, if it looked like fun, I might. Now that this file is clean, enable pylint checks on this file. Signed-off-by: John Snow <jsnow@redhat.com> Reviewed-by: Eduardo Habkost <ehabkost@redhat.com> Reviewed-by: Cleber Rosa <crosa@redhat.com> Message-Id: <20201009161558.107041-34-jsnow@redhat.com> Reviewed-by: Markus Armbruster <armbru@redhat.com> Signed-off-by: Markus Armbruster <armbru@redhat.com>
* qapi/types.py: add type hint annotationsJohn Snow2020-10-102-27/+64
| | | | | | | | | | | | Annotations do not change runtime behavior. This commit *only* adds annotations. Signed-off-by: John Snow <jsnow@redhat.com> Reviewed-by: Eduardo Habkost <ehabkost@redhat.com> Reviewed-by: Cleber Rosa <crosa@redhat.com> Message-Id: <20201009161558.107041-33-jsnow@redhat.com> Reviewed-by: Markus Armbruster <armbru@redhat.com> Signed-off-by: Markus Armbruster <armbru@redhat.com>
* qapi/gen.py: delint with pylintJohn Snow2020-10-102-2/+5
| | | | | | | | | | | | | | | 'fp' and 'fd' are self-evident in context, add them to the list of OK names. _top and _bottom also need to stay standard methods because some users override the method and need to use `self`. Tell pylint to shush. Signed-off-by: John Snow <jsnow@redhat.com> Reviewed-by: Eduardo Habkost <ehabkost@redhat.com> Reviewed-by: Cleber Rosa <crosa@redhat.com> Message-Id: <20201009161558.107041-32-jsnow@redhat.com> Reviewed-by: Markus Armbruster <armbru@redhat.com> Signed-off-by: Markus Armbruster <armbru@redhat.com>
* qapi/gen.py: update write() to be more idiomaticJohn Snow2020-10-101-14/+11Star
| | | | | | | | | | | | | | | | Make the file handling here just a tiny bit more idiomatic. (I realize this is heavily subjective.) Use exist_ok=True for os.makedirs and remove the exception, use fdopen() to wrap the file descriptor in a File-like object, and use a context manager for managing the file pointer. Signed-off-by: John Snow <jsnow@redhat.com> Reviewed-by: Eduardo Habkost <ehabkost@redhat.com> Reviewed-by: Cleber Rosa <crosa@redhat.com> Reviewed-by: Markus Armbruster <armbru@redhat.com> Message-Id: <20201009161558.107041-31-jsnow@redhat.com> Signed-off-by: Markus Armbruster <armbru@redhat.com>
* qapi/gen.py: Remove unused parameterJohn Snow2020-10-101-2/+2
| | | | | | | | | | | _module_dirname doesn't use the 'what' argument, so remove it. Signed-off-by: John Snow <jsnow@redhat.com> Reviewed-by: Eduardo Habkost <ehabkost@redhat.com> Reviewed-by: Cleber Rosa <crosa@redhat.com> Message-Id: <20201009161558.107041-30-jsnow@redhat.com> Reviewed-by: Markus Armbruster <armbru@redhat.com> Signed-off-by: Markus Armbruster <armbru@redhat.com>
* qapi/gen.py: add type hint annotationsJohn Snow2020-10-102-52/+57
| | | | | | | | | | | | | | Annotations do not change runtime behavior. This commit *only* adds annotations. Signed-off-by: John Snow <jsnow@redhat.com> Reviewed-by: Eduardo Habkost <ehabkost@redhat.com> Reviewed-by: Cleber Rosa <crosa@redhat.com> Message-Id: <20201009161558.107041-28-jsnow@redhat.com> Message-Id: <20201009161558.107041-29-jsnow@redhat.com> [mypy.ini update squashed in] Reviewed-by: Markus Armbruster <armbru@redhat.com> Signed-off-by: Markus Armbruster <armbru@redhat.com>
* qapi/gen: Make _is_user_module() return boolJohn Snow2020-10-101-1/+1
| | | | | | | | | | | | | | _is_user_module() returns thruth values. The next commit wants it to return bool. Make it so. Signed-off-by: John Snow <jsnow@redhat.com> Reviewed-by: Cleber Rosa <crosa@redhat.com> Reviewed-by: Eduardo Habkost <ehabkost@redhat.com> Reviewed-by: Philippe Mathieu-Daudé <philmd@redhat.com> Message-Id: <20201009161558.107041-27-jsnow@redhat.com> Reviewed-by: Markus Armbruster <armbru@redhat.com> [Commit message rewritten] Signed-off-by: Markus Armbruster <armbru@redhat.com>
* qapi/source.py: delint with pylintJohn Snow2020-10-102-1/+3
| | | | | | | | | | | | | Shush an error and leave a hint for future cleanups when we're allowed to use Python 3.7+. Signed-off-by: John Snow <jsnow@redhat.com> Reviewed-by: Eduardo Habkost <ehabkost@redhat.com> Reviewed-by: Cleber Rosa <crosa@redhat.com> Tested-by: Cleber Rosa <crosa@redhat.com> Message-Id: <20201009161558.107041-26-jsnow@redhat.com> Reviewed-by: Markus Armbruster <armbru@redhat.com> Signed-off-by: Markus Armbruster <armbru@redhat.com>
* qapi/source.py: add type hint annotationsJohn Snow2020-10-102-18/+19
| | | | | | | | | | | | | | | | | | | | Annotations do not change runtime behavior. This commit *only* adds annotations. A note on typing of __init__: mypy requires init functions with no parameters to document a return type of None to be considered fully typed. In the case when there are input parameters, None may be omitted. Since __init__ may never return any value, it is preferred to omit the return annotation whenever possible. Signed-off-by: John Snow <jsnow@redhat.com> Reviewed-by: Eduardo Habkost <ehabkost@redhat.com> Reviewed-by: Cleber Rosa <crosa@redhat.com> Tested-by: Cleber Rosa <crosa@redhat.com> Message-Id: <20201009161558.107041-25-jsnow@redhat.com> Reviewed-by: Markus Armbruster <armbru@redhat.com> Signed-off-by: Markus Armbruster <armbru@redhat.com>
* qapi/commands.py: add type hint annotationsJohn Snow2020-10-102-23/+56
| | | | | | | | | | | | | | Annotations do not change runtime behavior. This commit *only* adds annotations. Signed-off-by: John Snow <jsnow@redhat.com> Reviewed-by: Eduardo Habkost <ehabkost@redhat.com> Reviewed-by: Cleber Rosa <crosa@redhat.com> Message-Id: <20201009161558.107041-23-jsnow@redhat.com> Message-Id: <20201009161558.107041-24-jsnow@redhat.com> [mypy.ini update squashed in] Reviewed-by: Markus Armbruster <armbru@redhat.com> Signed-off-by: Markus Armbruster <armbru@redhat.com>
* qapi/commands.py: Don't re-bind to variable of different typeJohn Snow2020-10-101-3/+1Star
| | | | | | | | | | | | Mypy isn't a fan of rebinding a variable with a new data type. It's easy enough to avoid. Signed-off-by: John Snow <jsnow@redhat.com> Reviewed-by: Eduardo Habkost <ehabkost@redhat.com> Reviewed-by: Cleber Rosa <crosa@redhat.com> Reviewed-by: Markus Armbruster <armbru@redhat.com> Message-Id: <20201009161558.107041-22-jsnow@redhat.com> Signed-off-by: Markus Armbruster <armbru@redhat.com>
* qapi/events.py: Move comments into docstringsJohn Snow2020-10-101-1/+5
| | | | | | | | | | | Clarify them while we're here. Signed-off-by: John Snow <jsnow@redhat.com> Reviewed-by: Eduardo Habkost <ehabkost@redhat.com> Reviewed-by: Cleber Rosa <crosa@redhat.com> Message-Id: <20201009161558.107041-21-jsnow@redhat.com> Reviewed-by: Markus Armbruster <armbru@redhat.com> Signed-off-by: Markus Armbruster <armbru@redhat.com>
* qapi/events.py: add type hint annotationsJohn Snow2020-10-102-16/+35
| | | | | | | | | | | | | | | Annotations do not change runtime behavior. This commit *only* adds annotations. Note: __init__ does not need its return type annotated, as it is special. https://mypy.readthedocs.io/en/stable/class_basics.html#annotating-init-methods Signed-off-by: John Snow <jsnow@redhat.com> Reviewed-by: Eduardo Habkost <ehabkost@redhat.com> Reviewed-by: Cleber Rosa <crosa@redhat.com> Message-Id: <20201009161558.107041-20-jsnow@redhat.com> Reviewed-by: Markus Armbruster <armbru@redhat.com> Signed-off-by: Markus Armbruster <armbru@redhat.com>
* qapi: establish mypy type-checking baselineJohn Snow2020-10-102-1/+62
| | | | | | | | | | | | | | | | | | | Fix a minor typing issue, and then establish a mypy type-checking baseline. Like pylint, this should be run from the folder above: > mypy --config-file=qapi/mypy.ini qapi/ This is designed and tested for mypy 0.770 or greater. Signed-off-by: John Snow <jsnow@redhat.com> Tested-by: Eduardo Habkost <ehabkost@redhat.com> Reviewed-by: Cleber Rosa <crosa@redhat.com> Tested-by: Cleber Rosa <crosa@redhat.com> Message-Id: <20201009161558.107041-19-jsnow@redhat.com> Reviewed-by: Markus Armbruster <armbru@redhat.com> Signed-off-by: Markus Armbruster <armbru@redhat.com>
* qapi/common.py: move build_params into gen.pyJohn Snow2020-10-104-34/+36
| | | | | | | | | | | | | | Including it in common.py creates a circular import dependency; schema relies on common, but common.build_params requires a type annotation from schema. To type this properly, it needs to be moved outside the cycle. Signed-off-by: John Snow <jsnow@redhat.com> Reviewed-by: Eduardo Habkost <ehabkost@redhat.com> Reviewed-by: Cleber Rosa <crosa@redhat.com> Message-Id: <20201009161558.107041-18-jsnow@redhat.com> Reviewed-by: Markus Armbruster <armbru@redhat.com> Signed-off-by: Markus Armbruster <armbru@redhat.com>
* qapi/common.py: Convert comments into docstrings, and elaborateJohn Snow2020-10-101-14/+40
| | | | | | | | | | | | | | | | | | | | | | | | | | | | As docstrings, they'll show up in documentation and IDE help. The docstring style being targeted is the Sphinx documentation style. Sphinx uses an extension of ReST with "domains". We use the (implicit) Python domain, which supports a number of custom "info fields". Those info fields are documented here: https://www.sphinx-doc.org/en/master/usage/restructuredtext/domains.html#info-field-lists Primarily, we use `:param X: descr`, `:return[s]: descr`, and `:raise[s] Z: when`. Everything else is the Sphinx dialect of ReST. (No, nothing checks or enforces this style that I am aware of. Sphinx either chokes or succeeds, but does not enforce a standard of what is otherwise inside the docstring. Pycharm does highlight when your param fields are not aligned with the actual fields present. It does not highlight missing return or exception statements. There is no existing style guide I am aware of that covers a standard for a minimally acceptable docstring. I am debating writing one.) Signed-off-by: John Snow <jsnow@redhat.com> Reviewed-by: Eduardo Habkost <ehabkost@redhat.com> Reviewed-by: Cleber Rosa <crosa@redhat.com> Message-Id: <20201009161558.107041-17-jsnow@redhat.com> Reviewed-by: Markus Armbruster <armbru@redhat.com> Signed-off-by: Markus Armbruster <armbru@redhat.com>
* qapi/common.py: add type hint annotationsJohn Snow2020-10-101-11/+16
| | | | | | | | | | | | | | | Annotations do not change runtime behavior. This commit *only* adds annotations. Note that build_params() cannot be fully annotated due to import dependency issues. The commit after next will take care of it. Signed-off-by: John Snow <jsnow@redhat.com> Reviewed-by: Eduardo Habkost <ehabkost@redhat.com> Reviewed-by: Cleber Rosa <crosa@redhat.com> Message-Id: <20201009161558.107041-16-jsnow@redhat.com> Reviewed-by: Markus Armbruster <armbru@redhat.com> Signed-off-by: Markus Armbruster <armbru@redhat.com>
* qapi/common.py: check with pylintJohn Snow2020-10-101-2/+1Star
| | | | | | | | | | | | Remove qapi/common.py from the pylintrc ignore list. Signed-off-by: John Snow <jsnow@redhat.com> Reviewed-by: Cleber Rosa <crosa@redhat.com> Tested-by: Cleber Rosa <crosa@redhat.com> Tested-by: Eduardo Habkost <ehabkost@redhat.com> Message-Id: <20201009161558.107041-15-jsnow@redhat.com> Reviewed-by: Markus Armbruster <armbru@redhat.com> Signed-off-by: Markus Armbruster <armbru@redhat.com>
* qapi/common.py: Replace one-letter 'c' variableJohn Snow2020-10-101-4/+4
| | | | | | | | | | Signed-off-by: John Snow <jsnow@redhat.com> Reviewed-by: Cleber Rosa <crosa@redhat.com> Reviewed-by: Eduardo Habkost <ehabkost@redhat.com> Reviewed-by: Philippe Mathieu-Daudé <philmd@redhat.com> Message-Id: <20201009161558.107041-14-jsnow@redhat.com> Reviewed-by: Markus Armbruster <armbru@redhat.com> Signed-off-by: Markus Armbruster <armbru@redhat.com>
* qapi/common.py: delint with pylintJohn Snow2020-10-102-17/+15Star
| | | | | | | | | | | | | | | | At this point, that just means using a consistent strategy for constant names. constants get UPPER_CASE and names not used externally get a leading underscore. As a preference, while renaming constants to be UPPERCASE, move them to the head of the file. Generally, it's nice to be able to audit the code that runs on import in one central place. Signed-off-by: John Snow <jsnow@redhat.com> Reviewed-by: Eduardo Habkost <ehabkost@redhat.com> Reviewed-by: Cleber Rosa <crosa@redhat.com> Message-Id: <20201009161558.107041-13-jsnow@redhat.com> Reviewed-by: Markus Armbruster <armbru@redhat.com> Signed-off-by: Markus Armbruster <armbru@redhat.com>
* qapi/common.py: Add indent managerJohn Snow2020-10-102-20/+36
| | | | | | | | | | | | | | | | Code style tools really dislike the use of global keywords, because it generally involves re-binding the name at runtime which can have strange effects depending on when and how that global name is referenced in other modules. Make a little indent level manager instead. Signed-off-by: John Snow <jsnow@redhat.com> Reviewed-by: Eduardo Habkost <ehabkost@redhat.com> Reviewed-by: Cleber Rosa <crosa@redhat.com> Message-Id: <20201009161558.107041-12-jsnow@redhat.com> Reviewed-by: Markus Armbruster <armbru@redhat.com> Signed-off-by: Markus Armbruster <armbru@redhat.com>
* qapi/common.py: Remove python compatibility workaroundJohn Snow2020-10-101-4/+1Star
| | | | | | | | | Signed-off-by: John Snow <jsnow@redhat.com> Reviewed-by: Eduardo Habkost <ehabkost@redhat.com> Reviewed-by: Cleber Rosa <crosa@redhat.com> Message-Id: <20201009161558.107041-11-jsnow@redhat.com> Reviewed-by: Markus Armbruster <armbru@redhat.com> Signed-off-by: Markus Armbruster <armbru@redhat.com>
* qapi: add pylintrcJohn Snow2020-10-101-0/+73
| | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | Using `pylint --generate-rcfile > pylintrc`, generate a skeleton pylintrc file. Sections that are not presently relevant (by the end of this series) are removed leaving just the empty section as a search engine / documentation hint to future authors. I am targeting pylint 2.6.0. In the future (and hopefully before 5.2 is released), I aim to have gitlab CI running the specific targeted versions of pylint, mypy, flake8, etc in a job. 2.5.x will work if you additionally pass --disable=bad-whitespace. This warning was removed from 2.6.x, for lack of consistent support. Right now, quite a few modules are ignored as they are known to fail as of this commit. modules will be removed from the known-bad list throughout this and following series as they are repaired. Note: Normally, pylintrc would go in the folder above the module, but as that folder is shared by many things, it is going inside the module folder (for now). Due to a bug in pylint 2.5+, pylint does not correctly recognize when it is being run from "inside" a package, and must be run *outside* of the package. Therefore, to run it, you must: > pylint scripts/qapi/ --rcfile=scripts/qapi/pylintrc Signed-off-by: John Snow <jsnow@redhat.com> Tested-by: Eduardo Habkost <ehabkost@redhat.com> Reviewed-by: Cleber Rosa <crosa@redhat.com> Tested-by: Cleber Rosa <crosa@redhat.com> Message-Id: <20201009161558.107041-10-jsnow@redhat.com> Reviewed-by: Markus Armbruster <armbru@redhat.com> Signed-off-by: Markus Armbruster <armbru@redhat.com>
* qapi: delint using flake8John Snow2020-10-104-9/+20
| | | | | | | | | | | | | | | | | Petty style guide fixes and line length enforcement. Not a big win, not a big loss, but flake8 passes 100% on the qapi module, which gives us an easy baseline to enforce hereafter. A note on the flake8 exception: flake8 will warn on *any* bare except, but pylint's is context-aware and will suppress the warning if you re-raise the exception. Signed-off-by: John Snow <jsnow@redhat.com> Reviewed-by: Eduardo Habkost <ehabkost@redhat.com> Reviewed-by: Cleber Rosa <crosa@redhat.com> Message-Id: <20201009161558.107041-9-jsnow@redhat.com> Reviewed-by: Markus Armbruster <armbru@redhat.com> Signed-off-by: Markus Armbruster <armbru@redhat.com>
* qapi: enforce import order/styling with isortJohn Snow2020-10-105-5/+16
| | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | While we're mucking around with imports, we might as well formalize the style we use. Let's use isort to do it for us. lines_after_imports=2: Use two lines after imports, to match PEP8's desire to have "two lines before and after" class definitions, which are likely to start immediately after imports. force_sort_within_sections: Intermingles "from x" and "import x" style statements, such that sorting is always performed strictly on the module name itself. force_grid_wrap=4: Four or more imports from a single module will force the one-per-line style that's more git-friendly. This will generally happen for 'typing' imports. multi_line_output=3: Uses the one-per-line indented style for long imports. include_trailing_comma: Adds a comma to the last import in a group, which makes git conflicts nicer to deal with, generally. line_length: 72 is chosen to match PEP8's "docstrings and comments" line length limit. If you have a single line import that exceeds 72 characters, your names are too long! Suggested-by: Cleber Rosa <crosa@redhat.com> Signed-off-by: John Snow <jsnow@redhat.com> Reviewed-by: Cleber Rosa <crosa@redhat.com> Tested-by: Cleber Rosa <crosa@redhat.com> Reviewed-by: Markus Armbruster <armbru@redhat.com> Message-Id: <20201009161558.107041-8-jsnow@redhat.com> Signed-off-by: Markus Armbruster <armbru@redhat.com>
* qapi: Remove wildcard includesJohn Snow2020-10-106-8/+38
| | | | | | | | | | | | | | | | | | Wildcard includes become hard to manage when refactoring and dealing with circular dependencies with strictly typed mypy. flake8 also flags each one as a warning, as it is not smart enough to know which names exist in the imported file. Remove them and include things explicitly by name instead. Signed-off-by: John Snow <jsnow@redhat.com> Reviewed-by: Eduardo Habkost <ehabkost@redhat.com> Reviewed-by: Cleber Rosa <crosa@redhat.com> Reviewed-by: Philippe Mathieu-Daudé <philmd@redhat.com> Message-Id: <20201009161558.107041-7-jsnow@redhat.com> Reviewed-by: Markus Armbruster <armbru@redhat.com> Signed-off-by: Markus Armbruster <armbru@redhat.com>
* qapi: Prefer explicit relative importsJohn Snow2020-10-1010-33/+33
| | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | All of the QAPI include statements are changed to be package-aware, as explicit relative imports. A quirk of Python packages is that the name of the package exists only *outside* of the package. This means that to a module inside of the qapi folder, there is inherently no such thing as the "qapi" package. The reason these imports work is because the "qapi" package exists in the context of the caller -- the execution shim, where sys.path includes a directory that has a 'qapi' folder in it. When we write "from qapi import sibling", we are NOT referencing the folder 'qapi', but rather "any package named qapi in sys.path". If you should so happen to have a 'qapi' package in your path, it will use *that* package. When we write "from .sibling import foo", we always reference explicitly our sibling module; guaranteeing consistency in *where* we are importing these modules from. This can be useful when working with virtual environments and packages in development mode. In development mode, a package is installed as a series of symlinks that forwards to your same source files. The problem arises because code quality checkers will follow "import qapi.x" to the "installed" version instead of the sibling file and -- even though they are the same file -- they have different module paths, and this causes cyclic import problems, false positive type mismatch errors, and more. It can also be useful when dealing with hierarchical packages, e.g. if we allow qemu.core.qmp, qemu.qapi.parser, etc. Signed-off-by: John Snow <jsnow@redhat.com> Reviewed-by: Eduardo Habkost <ehabkost@redhat.com> Reviewed-by: Cleber Rosa <crosa@redhat.com> Reviewed-by: Philippe Mathieu-Daudé <philmd@redhat.com> Message-Id: <20201009161558.107041-6-jsnow@redhat.com> Reviewed-by: Markus Armbruster <armbru@redhat.com> Signed-off-by: Markus Armbruster <armbru@redhat.com>
* qapi: move generator entrypoint into packageJohn Snow2020-10-101-0/+95
| | | | | | | | | | | | | | | As part of delinting and adding type hints to the QAPI generator, it's helpful for the entrypoint to be part of the package, only leaving a very tiny entrypoint shim outside of the package. Signed-off-by: John Snow <jsnow@redhat.com> Reviewed-by: Eduardo Habkost <ehabkost@redhat.com> Reviewed-by: Cleber Rosa <crosa@redhat.com> Tested-by: Cleber Rosa <crosa@redhat.com> Message-Id: <20201009161558.107041-5-jsnow@redhat.com> Reviewed-by: Markus Armbruster <armbru@redhat.com> [invalid_char() renamed to invalid_prefix_char()] Signed-off-by: Markus Armbruster <armbru@redhat.com>
* qapi: modify docstrings to be sphinx-compatibleJohn Snow2020-10-101-2/+4
| | | | | | | | | | | | | | | | | | A precise style guide and a package-wide overhaul is forthcoming pending further discussion and consensus. For now, merely avoid obvious errors that cause Sphinx documentation build problems, using a style loosely based on PEP 257 and Sphinx Autodoc. It is chosen for interoperability with our existing Sphinx framework, and because it has loose recognition in the Pycharm IDE. See also: https://www.python.org/dev/peps/pep-0257/ https://www.sphinx-doc.org/en/master/usage/restructuredtext/domains.html#info-field-lists Signed-off-by: John Snow <jsnow@redhat.com> Message-Id: <20201009161558.107041-3-jsnow@redhat.com> Reviewed-by: Markus Armbruster <armbru@redhat.com> Signed-off-by: Markus Armbruster <armbru@redhat.com>
* qapi: Add a 'coroutine' flag for commandsKevin Wolf2020-10-094-10/+26
| | | | | | | | | | | | | | | | This patch adds a new 'coroutine' flag to QMP command definitions that tells the QMP dispatcher that the command handler is safe to be run in a coroutine. The documentation of the new flag pretends that this flag is already used as intended, which it isn't yet after this patch. We'll implement this in another patch in this series. Signed-off-by: Kevin Wolf <kwolf@redhat.com> Message-Id: <20201005155855.256490-9-kwolf@redhat.com> Reviewed-by: Markus Armbruster <armbru@redhat.com> Reviewed-by: Stefan Hajnoczi <stefanha@redhat.com> Signed-off-by: Markus Armbruster <armbru@redhat.com>
* scripts/qapi: Remove texinfo generation supportPeter Maydell2020-09-292-309/+0Star
| | | | | | | | | | | | We no longer use the generated texinfo format documentation, so delete the code that generates it, and the test case for the generation. Reviewed-by: Richard Henderson <richard.henderson@linaro.org> Signed-off-by: Peter Maydell <peter.maydell@linaro.org> Message-Id: <20200925162316.21205-17-peter.maydell@linaro.org> Reviewed-by: Markus Armbruster <armbru@redhat.com> Signed-off-by: Markus Armbruster <armbru@redhat.com>
* scripts/qapi/parser.py: improve doc comment indent handlingPeter Maydell2020-09-291-19/+74
| | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | Make the handling of indentation in doc comments more sophisticated, so that when we see a section like: Notes: some text some more text indented line 3 we save it for the doc-comment processing code as: some text some more text indented line 3 and when we see a section with the heading on its own line: Notes: some text some more text indented text we also accept that and save it in the same form. If we detect that the comment document text is not indented as much as we expect it to be, we throw a parse error. (We don't complain about over-indented sections, because for rST this can be legitimate markup.) The golden reference for the doc comment text is updated to remove the two 'wrong' indents; these now form a test case that we correctly stripped leading whitespace from an indented multi-line argument definition. We update the documentation in docs/devel/qapi-code-gen.txt to describe the new indentation rules. Signed-off-by: Peter Maydell <peter.maydell@linaro.org> Message-Id: <20200925162316.21205-6-peter.maydell@linaro.org> Reviewed-by: Markus Armbruster <armbru@redhat.com> [Whitespace between sentences tweaked] Signed-off-by: Markus Armbruster <armbru@redhat.com>
* scripts/qapi: Move doc-comment whitespace stripping to doc.pyPeter Maydell2020-09-292-8/+5Star
| | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | As we accumulate lines from doc comments when parsing the JSON, the QAPIDoc class generally strips leading and trailing whitespace using line.strip() when it calls _append_freeform(). This is fine for Texinfo, but for rST leading whitespace is significant. We'd like to move to having the text in doc comments be rST format rather than a custom syntax, so move the removal of leading whitespace from the QAPIDoc class to the texinfo-specific processing code in texi_format() in qapi/doc.py. (Trailing whitespace will always be stripped by the rstrip() in Section::append regardless.) In a followup commit we will make the whitespace in the lines of doc comment sections more consistently follow the input source. There is no change to the generated .texi files before and after this commit. Because the qapi-schema test checks the exact values of the documentation comments against a reference, we need to update that reference to match the new whitespace. In the first four places this is now correctly checking that we did put in the amount of whitespace to pass a rST-formatted list to the backend; in the last two places the extra whitespace is 'wrong' and will go away again in the following commit. Reviewed-by: Richard Henderson <richard.henderson@linaro.org> Reviewed-by: Markus Armbruster <armbru@redhat.com> Signed-off-by: Peter Maydell <peter.maydell@linaro.org> Message-Id: <20200925162316.21205-5-peter.maydell@linaro.org> Signed-off-by: Markus Armbruster <armbru@redhat.com>
* qapi: Make section headings start a new doc comment blockMarkus Armbruster2020-09-071-8/+13
| | | | | | | | | | | | | | | | | | | Our current QAPI doc-comment markup allows section headers (introduced with a leading '=' or '==') anywhere in a free-form documentation comment. This works for Texinfo because the generator simply prints a Texinfo section command at that point in the output stream. For rST generation, since we're assembling a tree of docutils nodes, this is awkward because a new section implies starting a new section node at the top level of the tree and generating text into there. Make section headers start a new free-form documentation block, so the future rST document generator doesn't have to look at every line in free-form blocks and handle headings in odd places. This change makes no difference to the generated Texinfo. Signed-off-by: Markus Armbruster <armbru@redhat.com> Message-Id: <20200320091805.5585-3-armbru@redhat.com>
* qapi: Reject section markup in definition documentationMarkus Armbruster2020-09-071-0/+5
| | | | | | | | | Section markup in definition documentation makes no sense and can produce invalid Texinfo. Reject. Signed-off-by: Markus Armbruster <armbru@redhat.com> Message-Id: <20200320091805.5585-2-armbru@redhat.com> Reviewed-by: Eric Blake <eblake@redhat.com>
* qapi: enable use of g_autoptr with QAPI typesDaniel P. Berrangé2020-09-031-0/+1
| | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | Currently QAPI generates a type and function for free'ing it: typedef struct QCryptoBlockCreateOptions QCryptoBlockCreateOptions; void qapi_free_QCryptoBlockCreateOptions(QCryptoBlockCreateOptions *obj); This is used in the traditional manner: QCryptoBlockCreateOptions *opts = NULL; opts = g_new0(QCryptoBlockCreateOptions, 1); ....do stuff with opts... qapi_free_QCryptoBlockCreateOptions(opts); Since bumping the min glib to 2.48, QEMU has incrementally adopted the use of g_auto/g_autoptr. This allows the compiler to run a function to free a variable when it goes out of scope, the benefit being the compiler can guarantee it is freed in all possible code ptahs. This benefit is applicable to QAPI types too, and given the seriously long method names for some qapi_free_XXXX() functions, is much less typing. This change thus makes the code generator emit: G_DEFINE_AUTOPTR_CLEANUP_FUNC(QCryptoBlockCreateOptions, qapi_free_QCryptoBlockCreateOptions) The above code example now becomes g_autoptr(QCryptoBlockCreateOptions) opts = NULL; opts = g_new0(QCryptoBlockCreateOptions, 1); ....do stuff with opts... Note, if the local pointer needs to live beyond the scope holding the variable, then g_steal_pointer can be used. This is useful to return the pointer to the caller in the success codepath, while letting it be freed in all error codepaths. return g_steal_pointer(&opts); The crypto/block.h header needs updating to avoid symbol clash now that the g_autoptr support is a standard QAPI feature. Signed-off-by: Daniel P. Berrangé <berrange@redhat.com> Message-Id: <20200723153845.2934357-1-berrange@redhat.com> Reviewed-by: Markus Armbruster <armbru@redhat.com> Reviewed-by: Eric Blake <eblake@redhat.com> Signed-off-by: Markus Armbruster <armbru@redhat.com>
* qapi: Fix visit_type_STRUCT() not to fail for null objectMarkus Armbruster2020-07-211-0/+1
| | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | To make deallocating partially constructed objects work, the visit_type_STRUCT() need to succeed without doing anything when passed a null object. Commit cdd2b228b9 "qapi: Smooth visitor error checking in generated code" broke that. To reproduce, run tests/test-qobject-input-visitor with AddressSanitizer: ==4353==ERROR: LeakSanitizer: detected memory leaks Direct leak of 16 byte(s) in 1 object(s) allocated from: #0 0x7f192d0c5d28 in __interceptor_calloc (/usr/lib/x86_64-linux-gnu/libasan.so.4+0xded28) #1 0x7f192cd21b10 in g_malloc0 (/usr/lib/x86_64-linux-gnu/libglib-2.0.so.0+0x51b10) #2 0x556725f6bbee in visit_next_list qapi/qapi-visit-core.c:86 #3 0x556725f49e15 in visit_type_UserDefOneList tests/test-qapi-visit.c:474 #4 0x556725f4489b in test_visitor_in_fail_struct_in_list tests/test-qobject-input-visitor.c:1086 #5 0x7f192cd42f29 (/usr/lib/x86_64-linux-gnu/libglib-2.0.so.0+0x72f29) SUMMARY: AddressSanitizer: 16 byte(s) leaked in 1 allocation(s). Test case /visitor/input/fail/struct-in-list feeds a list with a bad element to the QObject input visitor. Visiting that element duly fails, and aborts the visit with the list only partially constructed: the faulty object is null. Cleaning up the partially constructed list visits that null object, fails, and aborts the visit before the list node gets freed. Fix the the generated visit_type_STRUCT() to succeed for null objects. Fixes: cdd2b228b973d2a29edf7696ef6e8b08ec329019 Reported-by: Li Qiang <liq3ea@163.com> Signed-off-by: Markus Armbruster <armbru@redhat.com> Message-Id: <20200716150617.4027356-1-armbru@redhat.com> Tested-by: Li Qiang <liq3ea@gmail.com> Reviewed-by: Li Qiang <liq3ea@gmail.com>
* qapi: Smooth visitor error checking in generated codeMarkus Armbruster2020-07-102-47/+32Star
| | | | | | | | | | Use visitor functions' return values to check for failure. Eliminate error_propagate() that are now unnecessary. Delete @err that are now unused. Signed-off-by: Markus Armbruster <armbru@redhat.com> Reviewed-by: Eric Blake <eblake@redhat.com> Message-Id: <20200707160613.848843-41-armbru@redhat.com>
* qapi: Make visitor functions taking Error ** return bool, not voidMarkus Armbruster2020-07-101-34/+24Star
| | | | | | | | | | See recent commit "error: Document Error API usage rules" for rationale. Signed-off-by: Markus Armbruster <armbru@redhat.com> Reviewed-by: Eric Blake <eblake@redhat.com> Reviewed-by: Vladimir Sementsov-Ogievskiy <vsementsov@virtuozzo.com> Message-Id: <20200707160613.848843-18-armbru@redhat.com>
* qapi: Generate simpler marshalling code when no argumentsMarkus Armbruster2020-04-301-16/+24
| | | | | | | | | | | | | | | | | | | | | | | When command FOO has no arguments, its generated qmp_marshal_FOO() is a bit confusing. Make it simpler: visit_start_struct(v, NULL, NULL, 0, &err); if (err) { goto out; } - - if (!err) { - visit_check_struct(v, &err); - } + visit_check_struct(v, &err); visit_end_struct(v, NULL); if (err) { goto out; } Signed-off-by: Markus Armbruster <armbru@redhat.com> Message-Id: <20200424084338.26803-16-armbru@redhat.com> Reviewed-by: Eric Blake <eblake@redhat.com>
* qapi: Disallow qmp_marshal_FOO(NULL, ...)Markus Armbruster2020-04-301-24/+2Star
| | | | | | | | | | | For QMP commands without arguments, gen_marshal() laboriously generates a qmp_marshal_FOO() that copes with null @args. Turns there's just one caller that passes null instead of an empty QDict. Adjust that caller, and simplify gen_marshal(). Signed-off-by: Markus Armbruster <armbru@redhat.com> Message-Id: <20200424084338.26803-15-armbru@redhat.com> Reviewed-by: Eric Blake <eblake@redhat.com>
* qapi: Assert non-input visitors see only valid alternate tagsMarkus Armbruster2020-04-301-0/+1
| | | | | | | | | | | | | | | | | An alternate type's visit_type_FOO() fails when it runs into an invalid ->type. This is appropriate with an input visitor: visit_start_alternate() sets ->type according to the input, and bad input can lead to bad ->type. It should never happen with an output, clone or dealloc visitor: if it did, the alternate being output, cloned or deallocated would be messed up beyond repair. Assert that. Signed-off-by: Markus Armbruster <armbru@redhat.com> Reviewed-by: Eric Blake <eblake@redhat.com> Message-Id: <20200424084338.26803-12-armbru@redhat.com>
* qapi: Clean up visitor's recovery from input with invalid typeMarkus Armbruster2020-04-301-0/+3
| | | | | | | | | | | | | | | | | | An alternate type's visit_type_FOO() fails when it runs into an invalid ->type. If it's an input visit, we then need to free the the object we got from visit_start_alternate(). We do that with qapi_free_FOO(), which uses the dealloc visitor. Trouble is that object is in a bad state: its ->type is invalid. So the dealloc visitor will run into the same error again, and the error recovery skips deallocating the alternate's (invalid) alternative. Works, because qapi_free_FOO() ignores the error. Avoid it instead: free the messed up object with by g_free(). Signed-off-by: Markus Armbruster <armbru@redhat.com> Message-Id: <20200424084338.26803-11-armbru@redhat.com> Reviewed-by: Eric Blake <eblake@redhat.com>
* qapi: Assert incomplete object occurs only in dealloc visitorMarkus Armbruster2020-04-301-0/+4
| | | | | | Signed-off-by: Markus Armbruster <armbru@redhat.com> Reviewed-by: Eric Blake <eblake@redhat.com> Message-Id: <20200424084338.26803-7-armbru@redhat.com>
* qapi: New special feature flag "deprecated"Markus Armbruster2020-03-171-0/+6
| | | | | | | | | | | | Unlike regular feature flags, the new special feature flag "deprecated" is recognized by the QAPI generator. For now, it's only permitted with commands, events, and struct members. It will be put to use shortly. Signed-off-by: Markus Armbruster <armbru@redhat.com> Message-Id: <20200317115459.31821-26-armbru@redhat.com> Reviewed-by: Eric Blake <eblake@redhat.com> [Doc typo fixed]
* qapi: Add feature flags to struct membersMarkus Armbruster2020-03-173-7/+23
| | | | | | Signed-off-by: Markus Armbruster <armbru@redhat.com> Reviewed-by: Marc-André Lureau <marcandre.lureau@redhat.com> Message-Id: <20200317115459.31821-21-armbru@redhat.com>
* qapi/schema: Call QAPIDoc.connect_member() in just one placeMarkus Armbruster2020-03-171-11/+12
| | | | | | | | | | | The .connect_doc() of classes that have QAPISchemaMember connect them to their documentation. Change them to delegate the actual work to new QAPISchemaMember.connect_doc(). Matches the .connect_doc() that already exist. Signed-off-by: Markus Armbruster <armbru@redhat.com> Reviewed-by: Marc-André Lureau <marcandre.lureau@redhat.com> Message-Id: <20200317115459.31821-20-armbru@redhat.com>
generated by cgit v1.2.3-55-g7522 (git 2.39.0) at 2024-12-18 11:02:56 +0100