Compares the Python API of onnx and onnx_light.onnx

This example walks the public Python API exposed by the upstream onnx package and by onnx_light.onnx and reports the discrepancies between the two.

It relies on onnx_light.compatibility, a small sub-package dedicated to checking whether a Python package is compatible with onnx_light. The same helpers are used by the unit test unittests/main/test_plot_api_compare.py.

For every common sub-module (helper, numpy_helper, checker, defs, parser, shape_inference, version_converter, compose, utils, inliner) the script lists:

• the sub-modules that are exposed by one package but not the other,

• the public functions that are exposed by one package but not the other,

• the public functions that exist in both packages but whose signatures differ (positional/keyword parameter names).

It also compares the top-level public functions of both packages (onnx.load / onnx.save vs onnx_light.onnx.load / onnx_light.onnx.save).

from __future__ import annotations

import onnx
import onnx.inliner  # noqa: F401  -- ensure the inliner sub-module is bound on ``onnx``
import onnx_light.onnx as onnxl

from onnx_light.compatibility import DEFAULT_SUBMODULES, compare_packages

Run the comparison

report = compare_packages(onnx, onnxl, submodules=DEFAULT_SUBMODULES)

Sub-module overview

submods = report["submodules"]
print(f"common sub-modules                : {len(submods['common'])}")
print(f"sub-modules only in onnx          : {len(submods['missing_in_onnxl'])}")
print(f"sub-modules only in onnx_light    : {len(submods['extra_in_onnxl'])}")
print()
print("Sub-modules only in onnx:")
for name in submods["missing_in_onnxl"]:
    print(f"  - {name}")
print()
print("Sub-modules only in onnx_light.onnx:")
for name in submods["extra_in_onnxl"]:
    print(f"  - {name}")

common sub-modules                : 10
sub-modules only in onnx          : 19
sub-modules only in onnx_light    : 2

Sub-modules only in onnx:
  - backend
  - bin
  - external_data_helper
  - frontend
  - gen_proto
  - model_container
  - onnx
  - onnx_cpp2py_export
  - onnx_data_pb
  - onnx_data_pb2
  - onnx_ml_pb2
  - onnx_operators_ml_pb2
  - onnx_operators_pb
  - onnx_pb
  - printer
  - reference
  - serialization
  - tools
  - version

Sub-modules only in onnx_light.onnx:
  - io_helper
  - onnx_lib

Top-level functions

onnx.load / onnx.save and their onnx_light counterparts live directly on the package (no sub-module), so they are reported separately here.

top = report["top_level"]
print()
print("=== top-level ===")
print(f"  common functions          : {len(top['common'])}")
print(f"  missing in onnx_light.onnx: {len(top['missing_in_onnxl'])}")
print(f"  extra in onnx_light.onnx  : {len(top['extra_in_onnxl'])}")
print(f"  signature mismatches      : {len(top['signature_diffs'])}")
if top["missing_in_onnxl"]:
    print("  - missing in onnx_light.onnx:")
    for name in top["missing_in_onnxl"]:
        print(f"      * {name}")
if top["extra_in_onnxl"]:
    print("  - extra in onnx_light.onnx:")
    for name in top["extra_in_onnxl"]:
        print(f"      * {name}")
if top["signature_diffs"]:
    print("  - signature mismatches:")
    for diff in top["signature_diffs"]:
        print(f"      * {diff.name}")
        print(f"          onnx       : {diff.onnx_params}")
        print(f"          onnx_light : {diff.onnxl_params}")

=== top-level ===
  common functions          : 2
  missing in onnx_light.onnx: 10
  extra in onnx_light.onnx  : 4
  signature mismatches      : 2
  - missing in onnx_light.onnx:
      * convert_model_to_external_data
      * load_external_data_for_model
      * load_from_string
      * load_model
      * load_model_from_string
      * load_tensor
      * load_tensor_from_string
      * save_model
      * save_tensor
      * write_external_data_tensors
  - extra in onnx_light.onnx:
      * load_encrypted
      * load_encrypted_string
      * save_encrypted
      * save_encrypted_string
  - signature mismatches:
      * load
          onnx       : ('f', 'format', 'load_external_data')
          onnx_light : ('f', 'skip_raw_data', 'raw_data_threshold', 'load_external_data', 'num_threads', 'location', 'min_block_size', 'no_copy', 'touch_raw_data_pages', 'file_load_mode')
      * save
          onnx       : ('proto', 'f', 'format', 'save_as_external_data', 'all_tensors_to_one_file', 'location', 'size_threshold', 'convert_attribute')
          onnx_light : ('proto', 'f', 'format', 'save_as_external_data', 'all_tensors_to_one_file', 'location', 'size_threshold', 'convert_attribute', 'num_threads', 'min_block_size', 'max_external_file_size')

Function-level comparison

for submod_name in DEFAULT_SUBMODULES:
    sub = report["per_submodule"][submod_name]
    print()
    print(f"=== {submod_name} ===")
    print(f"  common functions          : {len(sub['common'])}")
    print(f"  missing in onnx_light.onnx: {len(sub['missing_in_onnxl'])}")
    print(f"  extra in onnx_light.onnx  : {len(sub['extra_in_onnxl'])}")
    print(f"  signature mismatches      : {len(sub['signature_diffs'])}")
    if sub["missing_in_onnxl"]:
        print("  - missing in onnx_light.onnx:")
        for name in sub["missing_in_onnxl"]:
            print(f"      * {name}")
    if sub["extra_in_onnxl"]:
        print("  - extra in onnx_light.onnx:")
        for name in sub["extra_in_onnxl"]:
            print(f"      * {name}")
    if sub["signature_diffs"]:
        print("  - signature mismatches:")
        for diff in sub["signature_diffs"]:
            print(f"      * {diff.name}")
            print(f"          onnx       : {diff.onnx_params}")
            print(f"          onnx_light : {diff.onnxl_params}")

=== helper ===
  common functions          : 28
  missing in onnx_light.onnx: 14
  extra in onnx_light.onnx  : 1
  signature mismatches      : 2
  - missing in onnx_light.onnx:
      * find_min_ir_version_for
      * get_all_tensor_dtypes
      * get_node_attr_value
      * make_model_gen_version
      * make_training_info
      * printable_attribute
      * printable_dim
      * printable_graph
      * printable_node
      * printable_tensor_proto
      * printable_type
      * printable_value_info
      * strip_doc_string
      * tensor_dtype_to_string
  - extra in onnx_light.onnx:
      * np_dtype_to_tensor_dtype
  - signature mismatches:
      * make_model
          onnx       : ('graph', 'kwargs')
          onnx_light : ('graph', 'ir_version', 'opset_imports', 'functions', 'metadata_props', 'doc_string', 'producer_name', 'producer_version')
      * make_tensor
          onnx       : ('name', 'data_type', 'dims', 'vals', 'raw')
          onnx_light : ('name', 'data_type', 'dims', 'vals', 'raw', 'external_data')

=== numpy_helper ===
  common functions          : 12
  missing in onnx_light.onnx: 0
  extra in onnx_light.onnx  : 0
  signature mismatches      : 0

=== checker ===
  common functions          : 4
  missing in onnx_light.onnx: 4
  extra in onnx_light.onnx  : 1
  signature mismatches      : 4
  - missing in onnx_light.onnx:
      * check_function
      * check_node
      * check_tensor
      * check_value_info
  - extra in onnx_light.onnx:
      * check_function_call_cycles
  - signature mismatches:
      * check_attribute
          onnx       : ('attr', 'ctx', 'lexical_scope_ctx')
          onnx_light : ('attribute',)
      * check_graph
          onnx       : ('graph', 'ctx', 'lexical_scope_ctx')
          onnx_light : ('graph',)
      * check_model
          onnx       : ('model', 'full_check', 'skip_opset_compatibility_check', 'check_custom_domain')
          onnx_light : ('model',)
      * check_sparse_tensor
          onnx       : ('sparse', 'ctx')
          onnx_light : ('sparse_tensor',)

=== defs ===
  common functions          : 3
  missing in onnx_light.onnx: 1
  extra in onnx_light.onnx  : 2
  signature mismatches      : 0
  - missing in onnx_light.onnx:
      * get_function_ops
  - extra in onnx_light.onnx:
      * onnx_ir_version
      * register_onnx_operator_set_schema

=== parser ===
  common functions          : 4
  missing in onnx_light.onnx: 0
  extra in onnx_light.onnx  : 0
  signature mismatches      : 4
  - signature mismatches:
      * parse_function
          onnx       : ('function_text',)
          onnx_light : ('text',)
      * parse_graph
          onnx       : ('graph_text',)
          onnx_light : ('text',)
      * parse_model
          onnx       : ('model_text',)
          onnx_light : ('text',)
      * parse_node
          onnx       : ('node_text',)
          onnx_light : ('text',)

=== shape_inference ===
  common functions          : 3
  missing in onnx_light.onnx: 1
  extra in onnx_light.onnx  : 0
  signature mismatches      : 1
  - missing in onnx_light.onnx:
      * infer_shapes_path
  - signature mismatches:
      * infer_shapes
          onnx       : ('model', 'check_type', 'strict_mode', 'data_prop')
          onnx_light : ('model',)

=== version_converter ===
  common functions          : 1
  missing in onnx_light.onnx: 0
  extra in onnx_light.onnx  : 0
  signature mismatches      : 0

=== compose ===
  common functions          : 7
  missing in onnx_light.onnx: 0
  extra in onnx_light.onnx  : 0
  signature mismatches      : 0

=== utils ===
  common functions          : 1
  missing in onnx_light.onnx: 0
  extra in onnx_light.onnx  : 2
  signature mismatches      : 0
  - extra in onnx_light.onnx:
      * load
      * save

=== inliner ===
  common functions          : 2
  missing in onnx_light.onnx: 0
  extra in onnx_light.onnx  : 0
  signature mismatches      : 1
  - signature mismatches:
      * inline_selected_functions
          onnx       : ('model', 'function_ids', 'exclude', 'inline_schema_functions')
          onnx_light : ('model', 'functions', 'exclude', 'inline_schema_functions')

Aggregate summary

total_missing = len(top["missing_in_onnxl"])
total_extra = len(top["extra_in_onnxl"])
total_diffs = len(top["signature_diffs"])
total_common = len(top["common"])
for submod_name in DEFAULT_SUBMODULES:
    sub = report["per_submodule"][submod_name]
    total_missing += len(sub["missing_in_onnxl"])
    total_extra += len(sub["extra_in_onnxl"])
    total_diffs += len(sub["signature_diffs"])
    total_common += len(sub["common"])

print()
print("Summary")
print("-------")
print(f"  total common functions     : {total_common}")
print(f"  total missing in onnx_light: {total_missing}")
print(f"  total extra in onnx_light  : {total_extra}")
print(f"  total signature mismatches : {total_diffs}")

Summary
-------
  total common functions     : 67
  total missing in onnx_light: 30
  total extra in onnx_light  : 10
  total signature mismatches : 14