Implementation:Onnx Onnx Gen Proto

Knowledge Sources	Onnx_Onnx
Domains	Build Infrastructure, Code Generation
Last Updated	2026-02-10 00:00 GMT

Overview

Concrete tool for generating ONNX protocol buffer definition files (.proto, .proto3) from template files (.in.proto), provided by the ONNX library.

Description

The gen_proto.py script is a build-time code generation tool that processes ONNX protocol buffer template files and produces multiple output variants. It serves as a critical part of the ONNX build infrastructure, enabling single-source maintenance of protocol buffer definitions while supporting multiple configurations.

The script operates through a pipeline of text transformation stages:

process_ifs evaluates conditional directives (// #if ONNX-ML, // #else, // #endif) to generate ONNX and ONNX-ML variants from a single source file. Lines within conditional blocks are included or excluded based on the onnx_ml flag.

process_package_name handles package name customization by substituting {PACKAGE_NAME} placeholders and rewriting import statements when a non-default package name is used.

convert_to_proto3 transforms proto2 syntax to proto3 by changing the syntax declaration, removing optional keywords, and rewriting import paths to use .proto3 extensions.

The convert function orchestrates the full process: it reads the template file, applies the translation pipeline to generate both proto2 (.proto) and proto3 (.proto3) output files, optionally invokes protoc for proto3 validation and code generation, creates convenience C++ header files for renamed packages, and generates Python import wrapper modules.

The main function provides a command-line interface with options for package name (-p), ML mode (-m), lite protobuf support (-l), output directory (-o), protoc path, and input stem names (defaulting to "onnx", "onnx-operators", "onnx-data").

Usage

Run this script during the ONNX build process to generate protocol buffer definition files from the .in.proto templates. It is typically invoked by the build system (CMake or setup.py) rather than by end users directly. Use the -m flag to generate ONNX-ML variants, -l for protobuf-lite compatibility, and -p for custom package names in embedded or namespace-isolated builds.

Code Reference

Source Location

• Repository: Onnx_Onnx
• File: onnx/gen_proto.py

Signature

def process_ifs(lines: Iterable[str], onnx_ml: bool) -> Iterable[str]

def process_package_name(lines: Iterable[str], package_name: str) -> Iterable[str]

def convert_to_proto3(lines: Iterable[str]) -> Iterable[str]

def gen_proto3_code(
    protoc_path: str, proto3_path: str, include_path: str, cpp_out: str, python_out: str
) -> None

def translate(source: str, proto: int, onnx_ml: bool, package_name: str) -> str

def qualify(f: str, pardir: str | None = None) -> str

def convert(
    stem: str, package_name: str, output: str,
    do_onnx_ml: bool = False, lite: bool = False, protoc_path: str = ""
) -> None

def main() -> None

Import

# This is a standalone build script, typically invoked from the command line:
python onnx/gen_proto.py [options] [stems]

I/O Contract

Inputs (convert)

Name	Type	Required	Description
stem	str	Yes	The base name of the .in.proto template file (e.g., "onnx", "onnx-operators", "onnx-data")
package_name	str	Yes	The protobuf package name (default: "onnx")
output	str	Yes	Output directory for generated files
do_onnx_ml	bool	No	Whether to generate ONNX-ML variant (default: False)
lite	bool	No	Whether to add protobuf-lite optimization option (default: False)
protoc_path	str	No	Path to protoc compiler for proto3 validation (default: "")

Outputs

Name	Type	Description
.proto file	file	Generated proto2 protocol buffer definition file
.proto3 file	file	Generated proto3 protocol buffer definition file
.pb.h file	file	Convenience C++ header (only when using custom package names)
_pb.py file	file	Python import wrapper module

Command-Line Interface

# Generate default ONNX proto files
python onnx/gen_proto.py

# Generate ONNX-ML variant with lite proto support
python onnx/gen_proto.py -m -l

# Generate with custom package name and output directory
python onnx/gen_proto.py -p mypackage -o /path/to/output

# Generate with protoc validation
python onnx/gen_proto.py --protoc_path /usr/bin/protoc

# Process specific template files
python onnx/gen_proto.py onnx onnx-operators

Usage Examples

from onnx.gen_proto import convert, translate

# Programmatic usage: convert a single template
convert(
    stem="onnx",
    package_name="onnx",
    output="/path/to/output",
    do_onnx_ml=True,
    lite=False,
)

# Translate source text directly
source = open("onnx.in.proto").read()
proto2_output = translate(source, proto=2, onnx_ml=True, package_name="onnx")
proto3_output = translate(source, proto=3, onnx_ml=True, package_name="onnx")

Related Pages

• Environment:Onnx_Onnx_Python_Runtime_Environment