Protobuf Schema Parser

Protobuf Schema Parser is a pure-Python library that parses and writes Protobuf schemas to and from an abstract syntax tree (AST).

The library uses proto_schema_parser.parser.Parser to parse the CST into an AST. The proto_schema_parser.generator.Generator class converts the AST back into a CST (a Protobuf schema string).

The lexer and parser are autogenerated from Buf's ANTLR lexer and parser grammar files.

Features

✅ proto2 and proto3 support
✅ protobuf editions support (edition 2023, edition 2024)
✅ message, field, enum, optional, required, repeated
✅ import, package, oneof, map, and option
✅ group and extend (in proto2)
✅ service, rpc, and stream
✅ line and block comment preservation

Installation

Install the package via pip:

pip install proto-schema-parser

Usage

To parse a protobuf schema, create a Parser object and call the parse method:

from proto_schema_parser.parser import Parser

text = """
syntax = "proto3";

message SearchRequest {
  string query = 1;
  int32 page_number = 2;
  int32 result_per_page = 3;
}
"""

result = Parser().parse(text)

This will return an AST object (ast.File) representing the parsed protobuf schema.

File(
  syntax='proto3',
  file_elements=[
    Message(
      name='SearchRequest',
      elements=[
        Field(
          name='query',
          number=1,
          type='string',
          cardinality=None,
          options=[]),
        Field(
          name='page_number',
          number=2,
          type='int32',
          cardinality=None,
          options=[]),
        Field(
          name='result_per_page',
          number=3,
          type='int32',
          cardinality=None,
          options=[])])])

To write the AST back to a protobuf schema, create a Generator object and call the generate method:

from proto_schema_parser.generator import Generator

proto = Generator().generate(result)

The proto variable now contains the string:

syntax = "proto3";
message SearchRequest {
  string query = 1;
  int32 page_number = 2;
  int32 result_per_page = 3;
}

Using Protobuf Editions

The library also supports protobuf editions, which provide more flexibility than proto2/proto3 syntax:

from proto_schema_parser.parser import Parser
from proto_schema_parser.generator import Generator

# Parse a protobuf file using edition syntax
text = """
edition = "2023";

message SearchRequest {
  string query = 1;
  int32 page_number = 2;
}
"""

result = Parser().parse(text)
# result.edition will be "2023"
# result.syntax will be None

# Generate back to protobuf format
proto = Generator().generate(result)

Supported editions:

edition = "2023"; - Edition 2023 spec
edition = "2024"; - Edition 2024 spec

Contributing

I welcome contributions!

Submit a PR and I'll review it as soon as I can.
Open an issue if you find a bug or have a feature request.

License

Protobuf Schema Parser is licensed under the MIT license.

Metadata

Release files for proto-schema-parser 2.1.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for proto-schema-parser 2.1.0
File	Size	Uploaded
proto_schema_parser-2.1.0.tar.gz	77.9 kB	Nov 5, 2025	Details

Built distribution (wheel)

Table of built distributions (wheels) for proto-schema-parser 2.1.0
File	Interpreter	ABI	Platform	Reset
proto_schema_parser-2.1.0-py3-none-any.whl 66.3 kB Nov 5, 2025	Python 3	none	any	Details

Total release size: 144.2 kB

Release files / proto_schema_parser-2.1.0.tar.gz

Download URL	proto_schema_parser-2.1.0.tar.gz
Size	77.9 kB
Tags	Source
SHA-256 checksum How to use checksums	`6fb9575588a819fec370613d7381d7962cd41718a572f4f4b824226c2eab4a25`
BLAKE2b-256 checksum How to use checksums	`e5323981b82fff36b133612be03d6ab029fc82ea9578833ed93404e3665df535`
Upload date	Nov 5, 2025
Uploaded using Trusted Publishing? What is trusted publishing?	Yes
Uploaded via	`pdm/2.26.1 CPython/3.12.3 Linux/6.11.0-1018-azure`

Release files / proto_schema_parser-2.1.0-py3-none-any.whl

Download URL	proto_schema_parser-2.1.0-py3-none-any.whl
Size	66.3 kB
Tags	Python 3
SHA-256 checksum How to use checksums	`c9c9febec427e77a12e65d041c6fb46d3dfdd473312e713cc9db82f50a9b0574`
BLAKE2b-256 checksum How to use checksums	`2b029bcd5329004262d25f18beb5fde95f188d0b9944512a621c93e422b50805`
Upload date	Nov 5, 2025
Uploaded using Trusted Publishing? What is trusted publishing?	Yes
Uploaded via	`pdm/2.26.1 CPython/3.12.3 Linux/6.11.0-1018-azure`