feat: add --json output flag to auditwheel show

.pre-commit-config.yaml

@@ -42,6 +42,7 @@ repos:
       - pytest
       - types-docker
       - types-requests
+      - types-jsonschema
 
 - repo: https://github.com/zizmorcore/zizmor-pre-commit
   rev: v1.23.1

src/auditwheel/main_show.py

@@ -7,6 +7,8 @@
 if TYPE_CHECKING:
     import argparse
 
+    from auditwheel.wheel_abi import WheelAbIInfo
+
 logger = logging.getLogger(__name__)
 
 
@@ -28,6 +30,13 @@ def configure_parser(sub_parsers: Any) -> None:  # noqa: ANN401
         help="Allow processing of pure Python wheels (no platform-specific binaries) without error",
         default=False,
     )
+    p.add_argument(
+        "--json",
+        dest="JSON",
+        action="store_true",
+        default=False,
+        help="Output results in JSON format",
+    )
     p.set_defaults(func=execute)
 
 
@@ -38,6 +47,42 @@ def printp(text: str) -> None:
     print("\n".join(wrap(text, break_long_words=False, break_on_hyphens=False)))
 
 
+def _output_json(fn: str, winfo: WheelAbIInfo) -> None:
+    from auditwheel import json
+
+    policies = winfo.policies
+    libs = winfo.external_refs[policies.lowest.name].libs
+
+    policy_upgrades: dict[str, dict[str, Any]] = {}
+    for p in policies:
+        if p > winfo.overall_policy:
+            entry: dict[str, Any] = {}
+            p_libs = winfo.external_refs[p.name].libs
+            if len(p_libs):
+                entry["libs_to_eliminate"] = sorted(p_libs.keys())
+            blacklist = winfo.external_refs[p.name].blacklist
+            if len(blacklist):
+                entry["blacklisted_symbols"] = {k: sorted(v) for k, v in sorted(blacklist.items())}
+            if entry:
+                policy_upgrades[p.name] = entry
+
+    result: dict[str, Any] = {
+        "version": 1,
+        "wheel": fn,
+        "pure": False,
+        "overall_tag": winfo.overall_policy.name,
+        "sym_tag": winfo.sym_policy.name,
+        "pyfpe": winfo.pyfpe_policy == policies.linux,
+        "ucs2": winfo.ucs_policy == policies.linux,
+        "unsupported_isa": winfo.machine_policy == policies.linux,
+        "versioned_symbols": {k: sorted(v) for k, v in sorted(winfo.versioned_symbols.items())},
+        "external_libs": {str(k): str(v) if v else None for k, v in sorted(libs.items())},
+        "policy_upgrades": policy_upgrades,
+    }
+
+    print(json.dumps(result))
+
+
 def execute(args: argparse.Namespace, parser: argparse.ArgumentParser) -> int:
     from auditwheel import json
     from auditwheel.error import NonPlatformWheelError, WheelToolsError
@@ -77,9 +122,17 @@ def execute(args: argparse.Namespace, parser: argparse.ArgumentParser) -> int:
     except NonPlatformWheelError as e:
         logger.info("%s", e.message)
         if is_pure_python and args.ALLOW_PURE_PY_WHEEL:
+            if args.JSON:
+                print(json.dumps({"version": 1, "wheel": fn, "pure": True}))
             return 0
+        if args.JSON:
+            print(json.dumps({"version": 1, "wheel": fn, "error": e.message}))
         return 1
 
+    if args.JSON:
+        _output_json(fn, winfo)
+        return 0
+
     policies = winfo.policies
 
     libs_with_versions = [f"{k} with versions {v}" for k, v in winfo.versioned_symbols.items()]

src/auditwheel/show-schema.json

@@ -0,0 +1,137 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "title": "auditwheel show",
+  "description": "Output schema for `auditwheel show --json`.",
+  "oneOf": [
+    { "$ref": "#/$defs/result_pure" },
+    { "$ref": "#/$defs/result_platform" },
+    { "$ref": "#/$defs/error" }
+  ],
+  "$defs": {
+    "result_pure": {
+      "type": "object",
+      "properties": {
+        "version": {
+          "const": 1,
+          "description": "Schema version."
+        },
+        "wheel": {
+          "type": "string",
+          "description": "Wheel filename."
+        },
+        "pure": {
+          "const": true,
+          "description": "Indicates a pure Python wheel."
+        }
+      },
+      "required": ["version", "wheel", "pure"],
+      "additionalProperties": false
+    },
+    "result_platform": {
+      "type": "object",
+      "properties": {
+        "version": {
+          "const": 1,
+          "description": "Schema version."
+        },
+        "wheel": {
+          "type": "string",
+          "description": "Wheel filename."
+        },
+        "pure": {
+          "const": false,
+          "description": "Indicates a platform wheel."
+        },
+        "overall_tag": {
+          "type": "string",
+          "description": "The highest compatible platform tag for the wheel."
+        },
+        "sym_tag": {
+          "type": "string",
+          "description": "Platform tag constrained by symbol versioning."
+        },
+        "pyfpe": {
+          "type": "boolean",
+          "description": "Whether the wheel uses PyFPE_jbuf (incompatible with manylinux/musllinux)."
+        },
+        "ucs2": {
+          "type": "boolean",
+          "description": "Whether the wheel is compiled against narrow unicode (UCS2)."
+        },
+        "unsupported_isa": {
+          "type": "boolean",
+          "description": "Whether the wheel depends on unsupported ISA extensions."
+        },
+        "versioned_symbols": {
+          "type": "object",
+          "additionalProperties": {
+            "type": "array",
+            "items": { "type": "string" }
+          },
+          "description": "Mapping of shared library names to their referenced symbol versions."
+        },
+        "external_libs": {
+          "type": "object",
+          "additionalProperties": {
+            "type": ["string", "null"]
+          },
+          "description": "Mapping of external shared library names to their resolved paths (or null)."
+        },
+        "policy_upgrades": {
+          "type": "object",
+          "additionalProperties": {
+            "type": "object",
+            "properties": {
+              "libs_to_eliminate": {
+                "type": "array",
+                "items": { "type": "string" }
+              },
+              "blacklisted_symbols": {
+                "type": "object",
+                "additionalProperties": {
+                  "type": "array",
+                  "items": { "type": "string" }
+                }
+              }
+            },
+            "additionalProperties": false
+          },
+          "description": "Per-policy info on what must be eliminated to achieve a higher tag."
+        }
+      },
+      "required": [
+        "version",
+        "wheel",
+        "pure",
+        "overall_tag",
+        "sym_tag",
+        "pyfpe",
+        "ucs2",
+        "unsupported_isa",
+        "versioned_symbols",
+        "external_libs",
+        "policy_upgrades"
+      ],
+      "additionalProperties": false
+    },
+    "error": {
+      "type": "object",
+      "properties": {
+        "version": {
+          "const": 1,
+          "description": "Schema version."
+        },
+        "wheel": {
+          "type": "string",
+          "description": "Wheel filename."
+        },
+        "error": {
+          "type": "string",
+          "description": "Error message."
+        }
+      },
+      "required": ["version", "wheel", "error"],
+      "additionalProperties": false
+    }
+  }
+}