Address Codacy findings in the API checker scripts

Put multi-line docstring summaries on their own line, as a single
sentence followed by a blank line (pydocstyle D205, D209, D213, D415).

Annotate the subprocess import and calls with nosec: they only run
fixed argument lists, never through a shell (Bandit B404, B603, B607).
Do the same for the three broad except clauses in extract_api.py,
which deliberately fall through to the next libclang candidate or skip
an unresolvable alias (Bandit B110, B112).

Signed-off-by: Niels Lohmann <mail@nlohmann.me>
This commit is contained in:
Niels Lohmann
2026-09-27 18:09:03 +02:00
parent 9a0d1c0c47
commit 2319f6e6f9
5 changed files with 77 additions and 41 deletions
+8 -4
View File
@@ -1,5 +1,6 @@
#!/usr/bin/env python3
"""Advisory-only cross-check between documented macros and their #define sites.
"""
Advisory-only cross-check between documented macros and their #define sites.
Macros have no C++ access-specifier concept, so the AST-based public/private test that
extract_api.py uses for classes doesn't transfer -- see tools/api_checker/POLICY.md's "Known
@@ -29,7 +30,8 @@ def report(location: str, description: str):
def extract_macro_names(md_path: str) -> list:
"""Extract macro name(s) from a doc page's H1 heading.
"""
Extract macro name(s) from a doc page's H1 heading.
Most pages use a single-line markdown heading ('# JSON_ASSERT'). A few document a family of
related macros under one page using a multi-line HTML heading listing comma-separated names
@@ -62,8 +64,10 @@ def extract_macro_names(md_path: str) -> list:
def macro_is_referenced(macro_name: str, include_dir: str) -> bool:
"""Check whether macro_name is defined OR referenced (#ifdef/#ifndef/defined()) anywhere
under include_dir.
"""
Check whether macro_name is defined or referenced anywhere under include_dir.
A reference is any #ifdef, #ifndef, or defined() check.
Some documented macros (e.g. JSON_NOEXCEPTION, JSON_THROW_USER) are user-supplied overrides:
the library only checks whether they're defined, it never #defines them itself. Requiring a