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
+7 -4
View File
@@ -1,5 +1,6 @@
#!/usr/bin/env python3
"""Verify that public API entries have documentation links.
"""
Verify that public API entries have documentation links.
Consumes an API snapshot from extract_api.py and checks:
1. Every public callable/type-tier entry has an @sa comment (with exceptions)
@@ -11,7 +12,8 @@ import argparse
import json
import os
import re
import subprocess
# subprocess is only called with fixed argument lists, never through a shell.
import subprocess # nosec B404
import sys
from urllib.parse import unquote
@@ -26,7 +28,7 @@ STL_EXEMPT = {'value_type', 'reference', 'const_reference', 'pointer', 'const_po
def get_repo_root():
"""Find the repository root via git, so this script works regardless of invoking CWD."""
try:
result = subprocess.run(
result = subprocess.run( # nosec B603 B607
['git', 'rev-parse', '--show-toplevel'],
capture_output=True, text=True, check=True, timeout=10
)
@@ -40,7 +42,8 @@ MKDOCS_YML = os.path.join(REPO_ROOT, 'docs', 'mkdocs', 'mkdocs.yml')
def load_redirect_map() -> dict:
"""Parse the redirect_maps block of docs/mkdocs/mkdocs.yml: {old_relative_path: new_relative_path}.
"""
Parse the redirect_maps block of docs/mkdocs/mkdocs.yml: {old_relative_path: new_relative_path}.
mkdocs' redirect plugin lets a doc page move without breaking existing @sa URLs -- e.g.
'api/basic_json/operator_ltlt.md' redirects to the real file at 'api/operator_ltlt.md'.