From f31d51cf3c1a25c2b3eac883012924c8c9a74dfb Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Anton=C3=ADn=20=C5=98=C3=ADha?= <43958476+anriha@users.noreply.github.com> Date: Wed, 3 Aug 2022 12:05:13 +0200 Subject: [PATCH] Added support for @generated marker (#382) --- .../lib/google/protobuf/__init__.py | 1162 +++++++++++------ .../lib/google/protobuf/compiler/__init__.py | 170 +-- src/betterproto/templates/template.py.j2 | 1 + 3 files changed, 843 insertions(+), 490 deletions(-) diff --git a/src/betterproto/lib/google/protobuf/__init__.py b/src/betterproto/lib/google/protobuf/__init__.py index 822b870..f59e4a1 100644 --- a/src/betterproto/lib/google/protobuf/__init__.py +++ b/src/betterproto/lib/google/protobuf/__init__.py @@ -1,6 +1,7 @@ # Generated by the protocol buffer compiler. DO NOT EDIT! # sources: google/protobuf/any.proto, google/protobuf/api.proto, google/protobuf/descriptor.proto, google/protobuf/duration.proto, google/protobuf/empty.proto, google/protobuf/field_mask.proto, google/protobuf/source_context.proto, google/protobuf/struct.proto, google/protobuf/timestamp.proto, google/protobuf/type.proto, google/protobuf/wrappers.proto # plugin: python-betterproto +# This file has been @generated import warnings from dataclasses import dataclass from typing import ( @@ -9,60 +10,128 @@ from typing import ( ) import betterproto -from betterproto.grpc.grpclib_server import ServiceBase class Syntax(betterproto.Enum): """The syntax in which a protocol buffer element is defined.""" - # Syntax `proto2`. SYNTAX_PROTO2 = 0 - # Syntax `proto3`. + """Syntax `proto2`.""" + SYNTAX_PROTO3 = 1 + """Syntax `proto3`.""" class FieldKind(betterproto.Enum): + """Basic field types.""" + TYPE_UNKNOWN = 0 + """Field type unknown.""" + TYPE_DOUBLE = 1 + """Field type double.""" + TYPE_FLOAT = 2 + """Field type float.""" + TYPE_INT64 = 3 + """Field type int64.""" + TYPE_UINT64 = 4 + """Field type uint64.""" + TYPE_INT32 = 5 + """Field type int32.""" + TYPE_FIXED64 = 6 + """Field type fixed64.""" + TYPE_FIXED32 = 7 + """Field type fixed32.""" + TYPE_BOOL = 8 + """Field type bool.""" + TYPE_STRING = 9 + """Field type string.""" + TYPE_GROUP = 10 + """Field type group. Proto2 syntax only, and deprecated.""" + TYPE_MESSAGE = 11 + """Field type message.""" + TYPE_BYTES = 12 + """Field type bytes.""" + TYPE_UINT32 = 13 + """Field type uint32.""" + TYPE_ENUM = 14 + """Field type enum.""" + TYPE_SFIXED32 = 15 + """Field type sfixed32.""" + TYPE_SFIXED64 = 16 + """Field type sfixed64.""" + TYPE_SINT32 = 17 + """Field type sint32.""" + TYPE_SINT64 = 18 + """Field type sint64.""" class FieldCardinality(betterproto.Enum): + """Whether a field is optional, required, or repeated.""" + CARDINALITY_UNKNOWN = 0 + """For fields with unknown cardinality.""" + CARDINALITY_OPTIONAL = 1 + """For optional fields.""" + CARDINALITY_REQUIRED = 2 + """For required fields. Proto2 syntax only.""" + CARDINALITY_REPEATED = 3 + """For repeated fields.""" class FieldDescriptorProtoType(betterproto.Enum): TYPE_DOUBLE = 1 + """0 is reserved for errors. Order is weird for historical reasons.""" + TYPE_FLOAT = 2 TYPE_INT64 = 3 + """ + Not ZigZag encoded. Negative numbers take 10 bytes. Use TYPE_SINT64 if + negative values are likely. + """ + TYPE_UINT64 = 4 TYPE_INT32 = 5 + """ + Not ZigZag encoded. Negative numbers take 10 bytes. Use TYPE_SINT32 if + negative values are likely. + """ + TYPE_FIXED64 = 6 TYPE_FIXED32 = 7 TYPE_BOOL = 8 TYPE_STRING = 9 TYPE_GROUP = 10 + """ + Tag-delimited aggregate. Group type is deprecated and not supported in + proto3. However, Proto3 implementations should still be able to parse the + group wire format and treat group fields as unknown fields. + """ + TYPE_MESSAGE = 11 TYPE_BYTES = 12 + """New in version 2.""" + TYPE_UINT32 = 13 TYPE_ENUM = 14 TYPE_SFIXED32 = 15 @@ -73,29 +142,48 @@ class FieldDescriptorProtoType(betterproto.Enum): class FieldDescriptorProtoLabel(betterproto.Enum): LABEL_OPTIONAL = 1 + """0 is reserved for errors""" + LABEL_REQUIRED = 2 LABEL_REPEATED = 3 class FileOptionsOptimizeMode(betterproto.Enum): + """Generated classes can be optimized for speed or code size.""" + SPEED = 1 CODE_SIZE = 2 + """etc.""" + LITE_RUNTIME = 3 class FieldOptionsCType(betterproto.Enum): STRING = 0 + """Default mode.""" + CORD = 1 STRING_PIECE = 2 class FieldOptionsJsType(betterproto.Enum): JS_NORMAL = 0 + """Use the default type.""" + JS_STRING = 1 + """Use JavaScript strings.""" + JS_NUMBER = 2 + """Use JavaScript numbers.""" class MethodOptionsIdempotencyLevel(betterproto.Enum): + """ + Is this method side-effect-free (or safe in HTTP parlance), or idempotent, + or neither? HTTP based RPC implementation may choose GET verb for safe + methods, and PUT verb for idempotent methods instead of the default POST. + """ + IDEMPOTENCY_UNKNOWN = 0 NO_SIDE_EFFECTS = 1 IDEMPOTENT = 2 @@ -108,8 +196,8 @@ class NullValue(betterproto.Enum): `null`. """ - # Null value. NULL_VALUE = 0 + """Null value.""" @dataclass(eq=False, repr=False) @@ -125,16 +213,16 @@ class Any(betterproto.Message): ... if (any.is(Foo.class)) { foo = any.unpack(Foo.class); } Example 3: Pack and unpack a message in Python. foo = Foo(...) any = Any() any.Pack(foo) ... if any.Is(Foo.DESCRIPTOR): - any.Unpack(foo) ... Example 4: Pack and unpack a message in Go + any.Unpack(foo) ... Example 4: Pack and unpack a message in Go foo := &pb.Foo{...} any, err := anypb.New(foo) if err != nil { ... } ... foo := &pb.Foo{} if err := any.UnmarshalTo(foo); err != nil { ... } The pack methods provided by protobuf library will by default use 'type.googleapis.com/full.type.name' as the type URL and the unpack methods only use the fully qualified type name after the last '/' in the type URL, - for example "foo.bar.com/x/y.z" will yield type name "y.z". JSON ==== The - JSON representation of an `Any` value uses the regular representation of - the deserialized, embedded message, with an additional field `@type` which + for example "foo.bar.com/x/y.z" will yield type name "y.z". JSON The JSON + representation of an `Any` value uses the regular representation of the + deserialized, embedded message, with an additional field `@type` which contains the type URL. Example: package google.profile; message Person { string first_name = 1; string last_name = 2; } { "@type": "type.googleapis.com/google.profile.Person", @@ -147,28 +235,33 @@ class Any(betterproto.Message): } """ - # A URL/resource name that uniquely identifies the type of the serialized - # protocol buffer message. This string must contain at least one "/" - # character. The last segment of the URL's path must represent the fully - # qualified name of the type (as in `path/google.protobuf.Duration`). The - # name should be in a canonical form (e.g., leading "." is not accepted). In - # practice, teams usually precompile into the binary all types that they - # expect it to use in the context of Any. However, for URLs which use the - # scheme `http`, `https`, or no scheme, one can optionally set up a type - # server that maps type URLs to message definitions as follows: * If no - # scheme is provided, `https` is assumed. * An HTTP GET on the URL must yield - # a [google.protobuf.Type][] value in binary format, or produce an error. * - # Applications are allowed to cache lookup results based on the URL, or - # have them precompiled into a binary to avoid any lookup. Therefore, - # binary compatibility needs to be preserved on changes to types. (Use - # versioned type names to manage breaking changes.) Note: this - # functionality is not currently available in the official protobuf release, - # and it is not used for type URLs beginning with type.googleapis.com. - # Schemes other than `http`, `https` (or the empty scheme) might be used with - # implementation specific semantics. type_url: str = betterproto.string_field(1) - # Must be a valid serialized protocol buffer of the above specified type. + """ + A URL/resource name that uniquely identifies the type of the serialized + protocol buffer message. This string must contain at least one "/" + character. The last segment of the URL's path must represent the fully + qualified name of the type (as in `path/google.protobuf.Duration`). The + name should be in a canonical form (e.g., leading "." is not accepted). In + practice, teams usually precompile into the binary all types that they + expect it to use in the context of Any. However, for URLs which use the + scheme `http`, `https`, or no scheme, one can optionally set up a type + server that maps type URLs to message definitions as follows: * If no + scheme is provided, `https` is assumed. * An HTTP GET on the URL must yield + a [google.protobuf.Type][] value in binary format, or produce an error. * + Applications are allowed to cache lookup results based on the URL, or + have them precompiled into a binary to avoid any lookup. Therefore, + binary compatibility needs to be preserved on changes to types. (Use + versioned type names to manage breaking changes.) Note: this + functionality is not currently available in the official protobuf release, + and it is not used for type URLs beginning with type.googleapis.com. + Schemes other than `http`, `https` (or the empty scheme) might be used with + implementation specific semantics. + """ + value: bytes = betterproto.bytes_field(2) + """ + Must be a valid serialized protocol buffer of the above specified type. + """ @dataclass(eq=False, repr=False) @@ -178,85 +271,113 @@ class SourceContext(betterproto.Message): element, like the file in which it is defined. """ - # The path-qualified name of the .proto file that contained the associated - # protobuf element. For example: `"google/protobuf/source_context.proto"`. file_name: str = betterproto.string_field(1) + """ + The path-qualified name of the .proto file that contained the associated + protobuf element. For example: `"google/protobuf/source_context.proto"`. + """ @dataclass(eq=False, repr=False) class Type(betterproto.Message): """A protocol buffer message type.""" - # The fully qualified message name. name: str = betterproto.string_field(1) - # The list of fields. + """The fully qualified message name.""" + fields: List["Field"] = betterproto.message_field(2) - # The list of types appearing in `oneof` definitions in this type. + """The list of fields.""" + oneofs: List[str] = betterproto.string_field(3) - # The protocol buffer options. + """The list of types appearing in `oneof` definitions in this type.""" + options: List["Option"] = betterproto.message_field(4) - # The source context. + """The protocol buffer options.""" + source_context: "SourceContext" = betterproto.message_field(5) - # The source syntax. + """The source context.""" + syntax: "Syntax" = betterproto.enum_field(6) + """The source syntax.""" @dataclass(eq=False, repr=False) class Field(betterproto.Message): """A single field of a message type.""" - # The field type. kind: "FieldKind" = betterproto.enum_field(1) - # The field cardinality. + """The field type.""" + cardinality: "FieldCardinality" = betterproto.enum_field(2) - # The field number. + """The field cardinality.""" + number: int = betterproto.int32_field(3) - # The field name. + """The field number.""" + name: str = betterproto.string_field(4) - # The field type URL, without the scheme, for message or enumeration types. - # Example: `"type.googleapis.com/google.protobuf.Timestamp"`. + """The field name.""" + type_url: str = betterproto.string_field(6) - # The index of the field type in `Type.oneofs`, for message or enumeration - # types. The first type has index 1; zero means the type is not in the list. + """ + The field type URL, without the scheme, for message or enumeration types. + Example: `"type.googleapis.com/google.protobuf.Timestamp"`. + """ + oneof_index: int = betterproto.int32_field(7) - # Whether to use alternative packed wire representation. + """ + The index of the field type in `Type.oneofs`, for message or enumeration + types. The first type has index 1; zero means the type is not in the list. + """ + packed: bool = betterproto.bool_field(8) - # The protocol buffer options. + """Whether to use alternative packed wire representation.""" + options: List["Option"] = betterproto.message_field(9) - # The field JSON name. + """The protocol buffer options.""" + json_name: str = betterproto.string_field(10) - # The string value of the default value of this field. Proto2 syntax only. + """The field JSON name.""" + default_value: str = betterproto.string_field(11) + """ + The string value of the default value of this field. Proto2 syntax only. + """ @dataclass(eq=False, repr=False) class Enum(betterproto.Message): """Enum type definition.""" - # Enum type name. name: str = betterproto.string_field(1) - # Enum value definitions. + """Enum type name.""" + enumvalue: List["EnumValue"] = betterproto.message_field( 2, wraps=betterproto.TYPE_ENUM ) - # Protocol buffer options. + """Enum value definitions.""" + options: List["Option"] = betterproto.message_field(3) - # The source context. + """Protocol buffer options.""" + source_context: "SourceContext" = betterproto.message_field(4) - # The source syntax. + """The source context.""" + syntax: "Syntax" = betterproto.enum_field(5) + """The source syntax.""" @dataclass(eq=False, repr=False) class EnumValue(betterproto.Message): """Enum value definition.""" - # Enum value name. name: str = betterproto.string_field(1) - # Enum value number. + """Enum value name.""" + number: int = betterproto.int32_field(2) - # Protocol buffer options. + """Enum value number.""" + options: List["Option"] = betterproto.message_field(3) + """Protocol buffer options.""" @dataclass(eq=False, repr=False) @@ -266,16 +387,21 @@ class Option(betterproto.Message): enumeration, etc. """ - # The option's name. For protobuf built-in options (options defined in - # descriptor.proto), this is the short name. For example, `"map_entry"`. For - # custom options, it should be the fully-qualified name. For example, - # `"google.api.http"`. name: str = betterproto.string_field(1) - # The option's value packed in an Any message. If the value is a primitive, - # the corresponding wrapper type defined in google/protobuf/wrappers.proto - # should be used. If the value is an enum, it should be stored as an int32 - # value using the google.protobuf.Int32Value type. + """ + The option's name. For protobuf built-in options (options defined in + descriptor.proto), this is the short name. For example, `"map_entry"`. For + custom options, it should be the fully-qualified name. For example, + `"google.api.http"`. + """ + value: "Any" = betterproto.message_field(2) + """ + The option's value packed in an Any message. If the value is a primitive, + the corresponding wrapper type defined in google/protobuf/wrappers.proto + should be used. If the value is an enum, it should be stored as an int32 + value using the google.protobuf.Int32Value type. + """ @dataclass(eq=False, repr=False) @@ -291,54 +417,72 @@ class Api(betterproto.Message): for detailed terminology. """ - # The fully qualified name of this interface, including package name followed - # by the interface's simple name. name: str = betterproto.string_field(1) - # The methods of this interface, in unspecified order. + """ + The fully qualified name of this interface, including package name followed + by the interface's simple name. + """ + methods: List["Method"] = betterproto.message_field(2) - # Any metadata attached to the interface. + """The methods of this interface, in unspecified order.""" + options: List["Option"] = betterproto.message_field(3) - # A version string for this interface. If specified, must have the form - # `major-version.minor-version`, as in `1.10`. If the minor version is - # omitted, it defaults to zero. If the entire version field is empty, the - # major version is derived from the package name, as outlined below. If the - # field is not empty, the version in the package name will be verified to be - # consistent with what is provided here. The versioning schema uses [semantic - # versioning](http://semver.org) where the major version number indicates a - # breaking change and the minor version an additive, non-breaking change. - # Both version numbers are signals to users what to expect from different - # versions, and should be carefully chosen based on the product plan. The - # major version is also reflected in the package name of the interface, which - # must end in `v`, as in `google.feature.v1`. For major - # versions 0 and 1, the suffix can be omitted. Zero major versions must only - # be used for experimental, non-GA interfaces. + """Any metadata attached to the interface.""" + version: str = betterproto.string_field(4) - # Source context for the protocol buffer service represented by this message. + """ + A version string for this interface. If specified, must have the form + `major-version.minor-version`, as in `1.10`. If the minor version is + omitted, it defaults to zero. If the entire version field is empty, the + major version is derived from the package name, as outlined below. If the + field is not empty, the version in the package name will be verified to be + consistent with what is provided here. The versioning schema uses [semantic + versioning](http://semver.org) where the major version number indicates a + breaking change and the minor version an additive, non-breaking change. + Both version numbers are signals to users what to expect from different + versions, and should be carefully chosen based on the product plan. The + major version is also reflected in the package name of the interface, which + must end in `v`, as in `google.feature.v1`. For major + versions 0 and 1, the suffix can be omitted. Zero major versions must only + be used for experimental, non-GA interfaces. + """ + source_context: "SourceContext" = betterproto.message_field(5) - # Included interfaces. See [Mixin][]. + """ + Source context for the protocol buffer service represented by this message. + """ + mixins: List["Mixin"] = betterproto.message_field(6) - # The source syntax of the service. + """Included interfaces. See [Mixin][].""" + syntax: "Syntax" = betterproto.enum_field(7) + """The source syntax of the service.""" @dataclass(eq=False, repr=False) class Method(betterproto.Message): """Method represents a method of an API interface.""" - # The simple name of this method. name: str = betterproto.string_field(1) - # A URL of the input message type. + """The simple name of this method.""" + request_type_url: str = betterproto.string_field(2) - # If true, the request is streamed. + """A URL of the input message type.""" + request_streaming: bool = betterproto.bool_field(3) - # The URL of the output message type. + """If true, the request is streamed.""" + response_type_url: str = betterproto.string_field(4) - # If true, the response is streamed. + """The URL of the output message type.""" + response_streaming: bool = betterproto.bool_field(5) - # Any metadata attached to the method. + """If true, the response is streamed.""" + options: List["Option"] = betterproto.message_field(6) - # The source syntax of this method. + """Any metadata attached to the method.""" + syntax: "Syntax" = betterproto.enum_field(7) + """The source syntax of this method.""" @dataclass(eq=False, repr=False) @@ -380,10 +524,13 @@ class Mixin(betterproto.Message): ... } """ - # The fully qualified name of the interface which is included. name: str = betterproto.string_field(1) - # If non-empty specifies a path under which inherited HTTP paths are rooted. + """The fully qualified name of the interface which is included.""" + root: str = betterproto.string_field(2) + """ + If non-empty specifies a path under which inherited HTTP paths are rooted. + """ @dataclass(eq=False, repr=False) @@ -402,27 +549,38 @@ class FileDescriptorProto(betterproto.Message): name: str = betterproto.string_field(1) package: str = betterproto.string_field(2) - # Names of files imported by this file. dependency: List[str] = betterproto.string_field(3) - # Indexes of the public imported files in the dependency list above. + """Names of files imported by this file.""" + public_dependency: List[int] = betterproto.int32_field(10) - # Indexes of the weak imported files in the dependency list. For Google- - # internal migration only. Do not use. + """Indexes of the public imported files in the dependency list above.""" + weak_dependency: List[int] = betterproto.int32_field(11) - # All top-level definitions in this file. + """ + Indexes of the weak imported files in the dependency list. For Google- + internal migration only. Do not use. + """ + message_type: List["DescriptorProto"] = betterproto.message_field(4) + """All top-level definitions in this file.""" + enum_type: List["EnumDescriptorProto"] = betterproto.message_field(5) service: List["ServiceDescriptorProto"] = betterproto.message_field(6) extension: List["FieldDescriptorProto"] = betterproto.message_field(7) options: "FileOptions" = betterproto.message_field(8) - # This field contains optional information about the original source code. - # You may safely remove this entire field without harming runtime - # functionality of the descriptors -- the information is needed only by - # development tools. source_code_info: "SourceCodeInfo" = betterproto.message_field(9) - # The syntax of the proto file. The supported values are "proto2" and - # "proto3". + """ + This field contains optional information about the original source code. + You may safely remove this entire field without harming runtime + functionality of the descriptors -- the information is needed only by + development tools. + """ + syntax: str = betterproto.string_field(12) + """ + The syntax of the proto file. The supported values are "proto2" and + "proto3". + """ @dataclass(eq=False, repr=False) @@ -440,9 +598,11 @@ class DescriptorProto(betterproto.Message): oneof_decl: List["OneofDescriptorProto"] = betterproto.message_field(8) options: "MessageOptions" = betterproto.message_field(7) reserved_range: List["DescriptorProtoReservedRange"] = betterproto.message_field(9) - # Reserved field names, which may not be used by fields in the same message. - # A given name may only be reserved once. reserved_name: List[str] = betterproto.string_field(10) + """ + Reserved field names, which may not be used by fields in the same message. + A given name may only be reserved once. + """ @dataclass(eq=False, repr=False) @@ -466,8 +626,8 @@ class DescriptorProtoReservedRange(betterproto.Message): @dataclass(eq=False, repr=False) class ExtensionRangeOptions(betterproto.Message): - # The parser stores options it doesn't recognize here. See above. uninterpreted_option: List["UninterpretedOption"] = betterproto.message_field(999) + """The parser stores options it doesn't recognize here. See above.""" @dataclass(eq=False, repr=False) @@ -477,48 +637,68 @@ class FieldDescriptorProto(betterproto.Message): name: str = betterproto.string_field(1) number: int = betterproto.int32_field(3) label: "FieldDescriptorProtoLabel" = betterproto.enum_field(4) - # If type_name is set, this need not be set. If both this and type_name are - # set, this must be one of TYPE_ENUM, TYPE_MESSAGE or TYPE_GROUP. type: "FieldDescriptorProtoType" = betterproto.enum_field(5) - # For message and enum types, this is the name of the type. If the name - # starts with a '.', it is fully-qualified. Otherwise, C++-like scoping - # rules are used to find the type (i.e. first the nested types within this - # message are searched, then within the parent, on up to the root namespace). + """ + If type_name is set, this need not be set. If both this and type_name are + set, this must be one of TYPE_ENUM, TYPE_MESSAGE or TYPE_GROUP. + """ + type_name: str = betterproto.string_field(6) - # For extensions, this is the name of the type being extended. It is - # resolved in the same manner as type_name. + """ + For message and enum types, this is the name of the type. If the name + starts with a '.', it is fully-qualified. Otherwise, C++-like scoping + rules are used to find the type (i.e. first the nested types within this + message are searched, then within the parent, on up to the root namespace). + """ + extendee: str = betterproto.string_field(2) - # For numeric types, contains the original text representation of the value. - # For booleans, "true" or "false". For strings, contains the default text - # contents (not escaped in any way). For bytes, contains the C escaped value. - # All bytes >= 128 are escaped. TODO(kenton): Base-64 encode? + """ + For extensions, this is the name of the type being extended. It is + resolved in the same manner as type_name. + """ + default_value: str = betterproto.string_field(7) - # If set, gives the index of a oneof in the containing type's oneof_decl - # list. This field is a member of that oneof. + """ + For numeric types, contains the original text representation of the value. + For booleans, "true" or "false". For strings, contains the default text + contents (not escaped in any way). For bytes, contains the C escaped value. + All bytes >= 128 are escaped. + """ + oneof_index: int = betterproto.int32_field(9) - # JSON name of this field. The value is set by protocol compiler. If the user - # has set a "json_name" option on this field, that option's value will be - # used. Otherwise, it's deduced from the field's name by converting it to - # camelCase. + """ + If set, gives the index of a oneof in the containing type's oneof_decl + list. This field is a member of that oneof. + """ + json_name: str = betterproto.string_field(10) + """ + JSON name of this field. The value is set by protocol compiler. If the user + has set a "json_name" option on this field, that option's value will be + used. Otherwise, it's deduced from the field's name by converting it to + camelCase. + """ + options: "FieldOptions" = betterproto.message_field(8) - # If true, this is a proto3 "optional". When a proto3 field is optional, it - # tracks presence regardless of field type. When proto3_optional is true, - # this field must be belong to a oneof to signal to old proto3 clients that - # presence is tracked for this field. This oneof is known as a "synthetic" - # oneof, and this field must be its sole member (each proto3 optional field - # gets its own synthetic oneof). Synthetic oneofs exist in the descriptor - # only, and do not generate any API. Synthetic oneofs must be ordered after - # all "real" oneofs. For message fields, proto3_optional doesn't create any - # semantic change, since non-repeated message fields always track presence. - # However it still indicates the semantic detail of whether the user wrote - # "optional" or not. This can be useful for round-tripping the .proto file. - # For consistency we give message fields a synthetic oneof also, even though - # it is not required to track presence. This is especially important because - # the parser can't tell if a field is a message or an enum, so it must always - # create a synthetic oneof. Proto2 optional fields do not set this flag, - # because they already indicate optional with `LABEL_OPTIONAL`. proto3_optional: bool = betterproto.bool_field(17) + """ + If true, this is a proto3 "optional". When a proto3 field is optional, it + tracks presence regardless of field type. When proto3_optional is true, + this field must be belong to a oneof to signal to old proto3 clients that + presence is tracked for this field. This oneof is known as a "synthetic" + oneof, and this field must be its sole member (each proto3 optional field + gets its own synthetic oneof). Synthetic oneofs exist in the descriptor + only, and do not generate any API. Synthetic oneofs must be ordered after + all "real" oneofs. For message fields, proto3_optional doesn't create any + semantic change, since non-repeated message fields always track presence. + However it still indicates the semantic detail of whether the user wrote + "optional" or not. This can be useful for round-tripping the .proto file. + For consistency we give message fields a synthetic oneof also, even though + it is not required to track presence. This is especially important because + the parser can't tell if a field is a message or an enum, so it must always + create a synthetic oneof. Proto2 optional fields do not set this flag, + because they already indicate optional with `LABEL_OPTIONAL`. + """ @dataclass(eq=False, repr=False) @@ -536,15 +716,20 @@ class EnumDescriptorProto(betterproto.Message): name: str = betterproto.string_field(1) value: List["EnumValueDescriptorProto"] = betterproto.message_field(2) options: "EnumOptions" = betterproto.message_field(3) - # Range of reserved numeric values. Reserved numeric values may not be used - # by enum values in the same enum declaration. Reserved ranges may not - # overlap. reserved_range: List[ "EnumDescriptorProtoEnumReservedRange" ] = betterproto.message_field(4) - # Reserved enum value names, which may not be reused. A given name may only - # be reserved once. + """ + Range of reserved numeric values. Reserved numeric values may not be used + by enum values in the same enum declaration. Reserved ranges may not + overlap. + """ + reserved_name: List[str] = betterproto.string_field(5) + """ + Reserved enum value names, which may not be reused. A given name may only + be reserved once. + """ @dataclass(eq=False, repr=False) @@ -583,103 +768,153 @@ class MethodDescriptorProto(betterproto.Message): """Describes a method of a service.""" name: str = betterproto.string_field(1) - # Input and output type names. These are resolved in the same way as - # FieldDescriptorProto.type_name, but must refer to a message type. input_type: str = betterproto.string_field(2) + """ + Input and output type names. These are resolved in the same way as + FieldDescriptorProto.type_name, but must refer to a message type. + """ + output_type: str = betterproto.string_field(3) options: "MethodOptions" = betterproto.message_field(4) - # Identifies if client streams multiple client messages client_streaming: bool = betterproto.bool_field(5) - # Identifies if server streams multiple server messages + """Identifies if client streams multiple client messages""" + server_streaming: bool = betterproto.bool_field(6) + """Identifies if server streams multiple server messages""" @dataclass(eq=False, repr=False) class FileOptions(betterproto.Message): - # Sets the Java package where classes generated from this .proto will be - # placed. By default, the proto package is used, but this is often - # inappropriate because proto packages do not normally start with backwards - # domain names. java_package: str = betterproto.string_field(1) - # Controls the name of the wrapper Java class generated for the .proto file. - # That class will always contain the .proto file's getDescriptor() method as - # well as any top-level extensions defined in the .proto file. If - # java_multiple_files is disabled, then all the other classes from the .proto - # file will be nested inside the single wrapper outer class. + """ + Sets the Java package where classes generated from this .proto will be + placed. By default, the proto package is used, but this is often + inappropriate because proto packages do not normally start with backwards + domain names. + """ + java_outer_classname: str = betterproto.string_field(8) - # If enabled, then the Java code generator will generate a separate .java - # file for each top-level message, enum, and service defined in the .proto - # file. Thus, these types will *not* be nested inside the wrapper class - # named by java_outer_classname. However, the wrapper class will still be - # generated to contain the file's getDescriptor() method as well as any top- - # level extensions defined in the file. + """ + Controls the name of the wrapper Java class generated for the .proto file. + That class will always contain the .proto file's getDescriptor() method as + well as any top-level extensions defined in the .proto file. If + java_multiple_files is disabled, then all the other classes from the .proto + file will be nested inside the single wrapper outer class. + """ + java_multiple_files: bool = betterproto.bool_field(10) - # This option does nothing. + """ + If enabled, then the Java code generator will generate a separate .java + file for each top-level message, enum, and service defined in the .proto + file. Thus, these types will *not* be nested inside the wrapper class + named by java_outer_classname. However, the wrapper class will still be + generated to contain the file's getDescriptor() method as well as any top- + level extensions defined in the file. + """ + java_generate_equals_and_hash: bool = betterproto.bool_field(20) - # If set true, then the Java2 code generator will generate code that throws - # an exception whenever an attempt is made to assign a non-UTF-8 byte - # sequence to a string field. Message reflection will do the same. However, - # an extension field still accepts non-UTF-8 byte sequences. This option has - # no effect on when used with the lite runtime. + """This option does nothing.""" + java_string_check_utf8: bool = betterproto.bool_field(27) + """ + If set true, then the Java2 code generator will generate code that throws + an exception whenever an attempt is made to assign a non-UTF-8 byte + sequence to a string field. Message reflection will do the same. However, + an extension field still accepts non-UTF-8 byte sequences. This option has + no effect on when used with the lite runtime. + """ + optimize_for: "FileOptionsOptimizeMode" = betterproto.enum_field(9) - # Sets the Go package where structs generated from this .proto will be - # placed. If omitted, the Go package will be derived from the following: - - # The basename of the package import path, if provided. - Otherwise, the - # package statement in the .proto file, if present. - Otherwise, the - # basename of the .proto file, without extension. go_package: str = betterproto.string_field(11) - # Should generic services be generated in each language? "Generic" services - # are not specific to any particular RPC system. They are generated by the - # main code generators in each language (without additional plugins). Generic - # services were the only kind of service generation supported by early - # versions of google.protobuf. Generic services are now considered deprecated - # in favor of using plugins that generate code specific to your particular - # RPC system. Therefore, these default to false. Old code which depends on - # generic services should explicitly set them to true. + """ + Sets the Go package where structs generated from this .proto will be + placed. If omitted, the Go package will be derived from the following: - + The basename of the package import path, if provided. - Otherwise, the + package statement in the .proto file, if present. - Otherwise, the + basename of the .proto file, without extension. + """ + cc_generic_services: bool = betterproto.bool_field(16) + """ + Should generic services be generated in each language? "Generic" services + are not specific to any particular RPC system. They are generated by the + main code generators in each language (without additional plugins). Generic + services were the only kind of service generation supported by early + versions of google.protobuf. Generic services are now considered deprecated + in favor of using plugins that generate code specific to your particular + RPC system. Therefore, these default to false. Old code which depends on + generic services should explicitly set them to true. + """ + java_generic_services: bool = betterproto.bool_field(17) py_generic_services: bool = betterproto.bool_field(18) php_generic_services: bool = betterproto.bool_field(42) - # Is this file deprecated? Depending on the target platform, this can emit - # Deprecated annotations for everything in the file, or it will be completely - # ignored; in the very least, this is a formalization for deprecating files. deprecated: bool = betterproto.bool_field(23) - # Enables the use of arenas for the proto messages in this file. This applies - # only to generated classes for C++. + """ + Is this file deprecated? Depending on the target platform, this can emit + Deprecated annotations for everything in the file, or it will be completely + ignored; in the very least, this is a formalization for deprecating files. + """ + cc_enable_arenas: bool = betterproto.bool_field(31) - # Sets the objective c class prefix which is prepended to all objective c - # generated classes from this .proto. There is no default. + """ + Enables the use of arenas for the proto messages in this file. This applies + only to generated classes for C++. + """ + objc_class_prefix: str = betterproto.string_field(36) - # Namespace for generated classes; defaults to the package. + """ + Sets the objective c class prefix which is prepended to all objective c + generated classes from this .proto. There is no default. + """ + csharp_namespace: str = betterproto.string_field(37) - # By default Swift generators will take the proto package and CamelCase it - # replacing '.' with underscore and use that to prefix the types/symbols - # defined. When this options is provided, they will use this value instead to - # prefix the types/symbols defined. + """Namespace for generated classes; defaults to the package.""" + swift_prefix: str = betterproto.string_field(39) - # Sets the php class prefix which is prepended to all php generated classes - # from this .proto. Default is empty. + """ + By default Swift generators will take the proto package and CamelCase it + replacing '.' with underscore and use that to prefix the types/symbols + defined. When this options is provided, they will use this value instead to + prefix the types/symbols defined. + """ + php_class_prefix: str = betterproto.string_field(40) - # Use this option to change the namespace of php generated classes. Default - # is empty. When this option is empty, the package name will be used for - # determining the namespace. + """ + Sets the php class prefix which is prepended to all php generated classes + from this .proto. Default is empty. + """ + php_namespace: str = betterproto.string_field(41) - # Use this option to change the namespace of php generated metadata classes. - # Default is empty. When this option is empty, the proto file name will be - # used for determining the namespace. + """ + Use this option to change the namespace of php generated classes. Default + is empty. When this option is empty, the package name will be used for + determining the namespace. + """ + php_metadata_namespace: str = betterproto.string_field(44) - # Use this option to change the package of ruby generated classes. Default is - # empty. When this option is not set, the package name will be used for - # determining the ruby package. + """ + Use this option to change the namespace of php generated metadata classes. + Default is empty. When this option is empty, the proto file name will be + used for determining the namespace. + """ + ruby_package: str = betterproto.string_field(45) - # The parser stores options it doesn't recognize here. See the documentation - # for the "Options" section above. + """ + Use this option to change the package of ruby generated classes. Default is + empty. When this option is not set, the package name will be used for + determining the ruby package. + """ + uninterpreted_option: List["UninterpretedOption"] = betterproto.message_field(999) + """ + The parser stores options it doesn't recognize here. See the documentation + for the "Options" section above. + """ def __post_init__(self) -> None: super().__post_init__() - if self.java_generate_equals_and_hash: + if self.is_set("java_generate_equals_and_hash"): warnings.warn( "FileOptions.java_generate_equals_and_hash is deprecated", DeprecationWarning, @@ -688,147 +923,200 @@ class FileOptions(betterproto.Message): @dataclass(eq=False, repr=False) class MessageOptions(betterproto.Message): - # Set true to use the old proto1 MessageSet wire format for extensions. This - # is provided for backwards-compatibility with the MessageSet wire format. - # You should not use this for any other reason: It's less efficient, has - # fewer features, and is more complicated. The message must be defined - # exactly as follows: message Foo { option message_set_wire_format = - # true; extensions 4 to max; } Note that the message cannot have any - # defined fields; MessageSets only have extensions. All extensions of your - # type must be singular messages; e.g. they cannot be int32s, enums, or - # repeated messages. Because this is an option, the above two restrictions - # are not enforced by the protocol compiler. message_set_wire_format: bool = betterproto.bool_field(1) - # Disables the generation of the standard "descriptor()" accessor, which can - # conflict with a field of the same name. This is meant to make migration - # from proto1 easier; new code should avoid fields named "descriptor". + """ + Set true to use the old proto1 MessageSet wire format for extensions. This + is provided for backwards-compatibility with the MessageSet wire format. + You should not use this for any other reason: It's less efficient, has + fewer features, and is more complicated. The message must be defined + exactly as follows: message Foo { option message_set_wire_format = + true; extensions 4 to max; } Note that the message cannot have any + defined fields; MessageSets only have extensions. All extensions of your + type must be singular messages; e.g. they cannot be int32s, enums, or + repeated messages. Because this is an option, the above two restrictions + are not enforced by the protocol compiler. + """ + no_standard_descriptor_accessor: bool = betterproto.bool_field(2) - # Is this message deprecated? Depending on the target platform, this can emit - # Deprecated annotations for the message, or it will be completely ignored; - # in the very least, this is a formalization for deprecating messages. + """ + Disables the generation of the standard "descriptor()" accessor, which can + conflict with a field of the same name. This is meant to make migration + from proto1 easier; new code should avoid fields named "descriptor". + """ + deprecated: bool = betterproto.bool_field(3) - # Whether the message is an automatically generated map entry type for the - # maps field. For maps fields: map map_field = 1; The - # parsed descriptor looks like: message MapFieldEntry { option - # map_entry = true; optional KeyType key = 1; optional - # ValueType value = 2; } repeated MapFieldEntry map_field = 1; - # Implementations may choose not to generate the map_entry=true message, but - # use a native map in the target language to hold the keys and values. The - # reflection APIs in such implementations still need to work as if the field - # is a repeated message field. NOTE: Do not set the option in .proto files. - # Always use the maps syntax instead. The option should only be implicitly - # set by the proto compiler parser. + """ + Is this message deprecated? Depending on the target platform, this can emit + Deprecated annotations for the message, or it will be completely ignored; + in the very least, this is a formalization for deprecating messages. + """ + map_entry: bool = betterproto.bool_field(7) - # The parser stores options it doesn't recognize here. See above. + """ + Whether the message is an automatically generated map entry type for the + maps field. For maps fields: map map_field = 1; The + parsed descriptor looks like: message MapFieldEntry { option + map_entry = true; optional KeyType key = 1; optional + ValueType value = 2; } repeated MapFieldEntry map_field = 1; + Implementations may choose not to generate the map_entry=true message, but + use a native map in the target language to hold the keys and values. The + reflection APIs in such implementations still need to work as if the field + is a repeated message field. NOTE: Do not set the option in .proto files. + Always use the maps syntax instead. The option should only be implicitly + set by the proto compiler parser. + """ + uninterpreted_option: List["UninterpretedOption"] = betterproto.message_field(999) + """The parser stores options it doesn't recognize here. See above.""" @dataclass(eq=False, repr=False) class FieldOptions(betterproto.Message): - # The ctype option instructs the C++ code generator to use a different - # representation of the field than it normally would. See the specific - # options below. This option is not yet implemented in the open source - # release -- sorry, we'll try to include it in a future version! ctype: "FieldOptionsCType" = betterproto.enum_field(1) - # The packed option can be enabled for repeated primitive fields to enable a - # more efficient representation on the wire. Rather than repeatedly writing - # the tag and type for each element, the entire array is encoded as a single - # length-delimited blob. In proto3, only explicit setting it to false will - # avoid using packed encoding. + """ + The ctype option instructs the C++ code generator to use a different + representation of the field than it normally would. See the specific + options below. This option is not yet implemented in the open source + release -- sorry, we'll try to include it in a future version! + """ + packed: bool = betterproto.bool_field(2) - # The jstype option determines the JavaScript type used for values of the - # field. The option is permitted only for 64 bit integral and fixed types - # (int64, uint64, sint64, fixed64, sfixed64). A field with jstype JS_STRING - # is represented as JavaScript string, which avoids loss of precision that - # can happen when a large value is converted to a floating point JavaScript. - # Specifying JS_NUMBER for the jstype causes the generated JavaScript code to - # use the JavaScript "number" type. The behavior of the default option - # JS_NORMAL is implementation dependent. This option is an enum to permit - # additional types to be added, e.g. goog.math.Integer. + """ + The packed option can be enabled for repeated primitive fields to enable a + more efficient representation on the wire. Rather than repeatedly writing + the tag and type for each element, the entire array is encoded as a single + length-delimited blob. In proto3, only explicit setting it to false will + avoid using packed encoding. + """ + jstype: "FieldOptionsJsType" = betterproto.enum_field(6) - # Should this field be parsed lazily? Lazy applies only to message-type - # fields. It means that when the outer message is initially parsed, the - # inner message's contents will not be parsed but instead stored in encoded - # form. The inner message will actually be parsed when it is first accessed. - # This is only a hint. Implementations are free to choose whether to use - # eager or lazy parsing regardless of the value of this option. However, - # setting this option true suggests that the protocol author believes that - # using lazy parsing on this field is worth the additional bookkeeping - # overhead typically needed to implement it. This option does not affect the - # public interface of any generated code; all method signatures remain the - # same. Furthermore, thread-safety of the interface is not affected by this - # option; const methods remain safe to call from multiple threads - # concurrently, while non-const methods continue to require exclusive access. - # Note that implementations may choose not to check required fields within a - # lazy sub-message. That is, calling IsInitialized() on the outer message - # may return true even if the inner message has missing required fields. This - # is necessary because otherwise the inner message would have to be parsed in - # order to perform the check, defeating the purpose of lazy parsing. An - # implementation which chooses not to check required fields must be - # consistent about it. That is, for any particular sub-message, the - # implementation must either *always* check its required fields, or *never* - # check its required fields, regardless of whether or not the message has - # been parsed. + """ + The jstype option determines the JavaScript type used for values of the + field. The option is permitted only for 64 bit integral and fixed types + (int64, uint64, sint64, fixed64, sfixed64). A field with jstype JS_STRING + is represented as JavaScript string, which avoids loss of precision that + can happen when a large value is converted to a floating point JavaScript. + Specifying JS_NUMBER for the jstype causes the generated JavaScript code to + use the JavaScript "number" type. The behavior of the default option + JS_NORMAL is implementation dependent. This option is an enum to permit + additional types to be added, e.g. goog.math.Integer. + """ + lazy: bool = betterproto.bool_field(5) - # Is this field deprecated? Depending on the target platform, this can emit - # Deprecated annotations for accessors, or it will be completely ignored; in - # the very least, this is a formalization for deprecating fields. + """ + Should this field be parsed lazily? Lazy applies only to message-type + fields. It means that when the outer message is initially parsed, the + inner message's contents will not be parsed but instead stored in encoded + form. The inner message will actually be parsed when it is first accessed. + This is only a hint. Implementations are free to choose whether to use + eager or lazy parsing regardless of the value of this option. However, + setting this option true suggests that the protocol author believes that + using lazy parsing on this field is worth the additional bookkeeping + overhead typically needed to implement it. This option does not affect the + public interface of any generated code; all method signatures remain the + same. Furthermore, thread-safety of the interface is not affected by this + option; const methods remain safe to call from multiple threads + concurrently, while non-const methods continue to require exclusive access. + Note that implementations may choose not to check required fields within a + lazy sub-message. That is, calling IsInitialized() on the outer message + may return true even if the inner message has missing required fields. This + is necessary because otherwise the inner message would have to be parsed in + order to perform the check, defeating the purpose of lazy parsing. An + implementation which chooses not to check required fields must be + consistent about it. That is, for any particular sub-message, the + implementation must either *always* check its required fields, or *never* + check its required fields, regardless of whether or not the message has + been parsed. As of 2021, lazy does no correctness checks on the byte stream + during parsing. This may lead to crashes if and when an invalid byte + stream is finally parsed upon access. TODO(b/211906113): Enable validation + on lazy fields. + """ + + unverified_lazy: bool = betterproto.bool_field(15) + """ + unverified_lazy does no correctness checks on the byte stream. This should + only be used where lazy with verification is prohibitive for performance + reasons. + """ + deprecated: bool = betterproto.bool_field(3) - # For Google-internal migration only. Do not use. + """ + Is this field deprecated? Depending on the target platform, this can emit + Deprecated annotations for accessors, or it will be completely ignored; in + the very least, this is a formalization for deprecating fields. + """ + weak: bool = betterproto.bool_field(10) - # The parser stores options it doesn't recognize here. See above. + """For Google-internal migration only. Do not use.""" + uninterpreted_option: List["UninterpretedOption"] = betterproto.message_field(999) + """The parser stores options it doesn't recognize here. See above.""" @dataclass(eq=False, repr=False) class OneofOptions(betterproto.Message): - # The parser stores options it doesn't recognize here. See above. uninterpreted_option: List["UninterpretedOption"] = betterproto.message_field(999) + """The parser stores options it doesn't recognize here. See above.""" @dataclass(eq=False, repr=False) class EnumOptions(betterproto.Message): - # Set this option to true to allow mapping different tag names to the same - # value. allow_alias: bool = betterproto.bool_field(2) - # Is this enum deprecated? Depending on the target platform, this can emit - # Deprecated annotations for the enum, or it will be completely ignored; in - # the very least, this is a formalization for deprecating enums. + """ + Set this option to true to allow mapping different tag names to the same + value. + """ + deprecated: bool = betterproto.bool_field(3) - # The parser stores options it doesn't recognize here. See above. + """ + Is this enum deprecated? Depending on the target platform, this can emit + Deprecated annotations for the enum, or it will be completely ignored; in + the very least, this is a formalization for deprecating enums. + """ + uninterpreted_option: List["UninterpretedOption"] = betterproto.message_field(999) + """The parser stores options it doesn't recognize here. See above.""" @dataclass(eq=False, repr=False) class EnumValueOptions(betterproto.Message): - # Is this enum value deprecated? Depending on the target platform, this can - # emit Deprecated annotations for the enum value, or it will be completely - # ignored; in the very least, this is a formalization for deprecating enum - # values. deprecated: bool = betterproto.bool_field(1) - # The parser stores options it doesn't recognize here. See above. + """ + Is this enum value deprecated? Depending on the target platform, this can + emit Deprecated annotations for the enum value, or it will be completely + ignored; in the very least, this is a formalization for deprecating enum + values. + """ + uninterpreted_option: List["UninterpretedOption"] = betterproto.message_field(999) + """The parser stores options it doesn't recognize here. See above.""" @dataclass(eq=False, repr=False) class ServiceOptions(betterproto.Message): - # Is this service deprecated? Depending on the target platform, this can emit - # Deprecated annotations for the service, or it will be completely ignored; - # in the very least, this is a formalization for deprecating services. deprecated: bool = betterproto.bool_field(33) - # The parser stores options it doesn't recognize here. See above. + """ + Is this service deprecated? Depending on the target platform, this can emit + Deprecated annotations for the service, or it will be completely ignored; + in the very least, this is a formalization for deprecating services. + """ + uninterpreted_option: List["UninterpretedOption"] = betterproto.message_field(999) + """The parser stores options it doesn't recognize here. See above.""" @dataclass(eq=False, repr=False) class MethodOptions(betterproto.Message): - # Is this method deprecated? Depending on the target platform, this can emit - # Deprecated annotations for the method, or it will be completely ignored; in - # the very least, this is a formalization for deprecating methods. deprecated: bool = betterproto.bool_field(33) + """ + Is this method deprecated? Depending on the target platform, this can emit + Deprecated annotations for the method, or it will be completely ignored; in + the very least, this is a formalization for deprecating methods. + """ + idempotency_level: "MethodOptionsIdempotencyLevel" = betterproto.enum_field(34) - # The parser stores options it doesn't recognize here. See above. uninterpreted_option: List["UninterpretedOption"] = betterproto.message_field(999) + """The parser stores options it doesn't recognize here. See above.""" @dataclass(eq=False, repr=False) @@ -843,9 +1131,12 @@ class UninterpretedOption(betterproto.Message): """ name: List["UninterpretedOptionNamePart"] = betterproto.message_field(2) - # The value of the uninterpreted option, in whatever type the tokenizer - # identified it as during parsing. Exactly one of these should be set. identifier_value: str = betterproto.string_field(3) + """ + The value of the uninterpreted option, in whatever type the tokenizer + identified it as during parsing. Exactly one of these should be set. + """ + positive_int_value: int = betterproto.uint64_field(4) negative_int_value: int = betterproto.int64_field(5) double_value: float = betterproto.double_field(6) @@ -874,81 +1165,92 @@ class SourceCodeInfo(betterproto.Message): FileDescriptorProto was generated. """ - # A Location identifies a piece of source code in a .proto file which - # corresponds to a particular definition. This information is intended to be - # useful to IDEs, code indexers, documentation generators, and similar tools. - # For example, say we have a file like: message Foo { optional string - # foo = 1; } Let's look at just the field definition: optional string foo - # = 1; ^ ^^ ^^ ^ ^^^ a bc de f ghi We have the - # following locations: span path represents [a,i) [ 4, - # 0, 2, 0 ] The whole field definition. [a,b) [ 4, 0, 2, 0, 4 ] The - # label (optional). [c,d) [ 4, 0, 2, 0, 5 ] The type (string). [e,f) [ - # 4, 0, 2, 0, 1 ] The name (foo). [g,h) [ 4, 0, 2, 0, 3 ] The number - # (1). Notes: - A location may refer to a repeated field itself (i.e. not to - # any particular index within it). This is used whenever a set of elements - # are logically enclosed in a single code segment. For example, an entire - # extend block (possibly containing multiple extension definitions) will - # have an outer location whose path refers to the "extensions" repeated - # field without an index. - Multiple locations may have the same path. This - # happens when a single logical declaration is spread out across multiple - # places. The most obvious example is the "extend" block again -- there - # may be multiple extend blocks in the same scope, each of which will have - # the same path. - A location's span is not always a subset of its parent's - # span. For example, the "extendee" of an extension declaration appears at - # the beginning of the "extend" block and is shared by all extensions - # within the block. - Just because a location's span is a subset of some - # other location's span does not mean that it is a descendant. For - # example, a "group" defines both a type and a field in a single - # declaration. Thus, the locations corresponding to the type and field and - # their components will overlap. - Code which tries to interpret locations - # should probably be designed to ignore those that it doesn't understand, - # as more types of locations could be recorded in the future. location: List["SourceCodeInfoLocation"] = betterproto.message_field(1) + """ + A Location identifies a piece of source code in a .proto file which + corresponds to a particular definition. This information is intended to be + useful to IDEs, code indexers, documentation generators, and similar tools. + For example, say we have a file like: message Foo { optional string + foo = 1; } Let's look at just the field definition: optional string foo + = 1; ^ ^^ ^^ ^ ^^^ a bc de f ghi We have the + following locations: span path represents [a,i) [ 4, + 0, 2, 0 ] The whole field definition. [a,b) [ 4, 0, 2, 0, 4 ] The + label (optional). [c,d) [ 4, 0, 2, 0, 5 ] The type (string). [e,f) [ + 4, 0, 2, 0, 1 ] The name (foo). [g,h) [ 4, 0, 2, 0, 3 ] The number + (1). Notes: - A location may refer to a repeated field itself (i.e. not to + any particular index within it). This is used whenever a set of elements + are logically enclosed in a single code segment. For example, an entire + extend block (possibly containing multiple extension definitions) will + have an outer location whose path refers to the "extensions" repeated + field without an index. - Multiple locations may have the same path. This + happens when a single logical declaration is spread out across multiple + places. The most obvious example is the "extend" block again -- there + may be multiple extend blocks in the same scope, each of which will have + the same path. - A location's span is not always a subset of its parent's + span. For example, the "extendee" of an extension declaration appears at + the beginning of the "extend" block and is shared by all extensions + within the block. - Just because a location's span is a subset of some + other location's span does not mean that it is a descendant. For + example, a "group" defines both a type and a field in a single + declaration. Thus, the locations corresponding to the type and field and + their components will overlap. - Code which tries to interpret locations + should probably be designed to ignore those that it doesn't understand, + as more types of locations could be recorded in the future. + """ @dataclass(eq=False, repr=False) class SourceCodeInfoLocation(betterproto.Message): - # Identifies which part of the FileDescriptorProto was defined at this - # location. Each element is a field number or an index. They form a path - # from the root FileDescriptorProto to the place where the definition. For - # example, this path: [ 4, 3, 2, 7, 1 ] refers to: file.message_type(3) - # // 4, 3 .field(7) // 2, 7 .name() // 1 This - # is because FileDescriptorProto.message_type has field number 4: repeated - # DescriptorProto message_type = 4; and DescriptorProto.field has field - # number 2: repeated FieldDescriptorProto field = 2; and - # FieldDescriptorProto.name has field number 1: optional string name = 1; - # Thus, the above path gives the location of a field name. If we removed the - # last element: [ 4, 3, 2, 7 ] this path refers to the whole field - # declaration (from the beginning of the label to the terminating semicolon). path: List[int] = betterproto.int32_field(1) - # Always has exactly three or four elements: start line, start column, end - # line (optional, otherwise assumed same as start line), end column. These - # are packed into a single field for efficiency. Note that line and column - # numbers are zero-based -- typically you will want to add 1 to each before - # displaying to a user. + """ + Identifies which part of the FileDescriptorProto was defined at this + location. Each element is a field number or an index. They form a path + from the root FileDescriptorProto to the place where the definition occurs. + For example, this path: [ 4, 3, 2, 7, 1 ] refers to: + file.message_type(3) // 4, 3 .field(7) // 2, 7 .name() + // 1 This is because FileDescriptorProto.message_type has field number 4: + repeated DescriptorProto message_type = 4; and DescriptorProto.field has + field number 2: repeated FieldDescriptorProto field = 2; and + FieldDescriptorProto.name has field number 1: optional string name = 1; + Thus, the above path gives the location of a field name. If we removed the + last element: [ 4, 3, 2, 7 ] this path refers to the whole field + declaration (from the beginning of the label to the terminating semicolon). + """ + span: List[int] = betterproto.int32_field(2) - # If this SourceCodeInfo represents a complete declaration, these are any - # comments appearing before and after the declaration which appear to be - # attached to the declaration. A series of line comments appearing on - # consecutive lines, with no other tokens appearing on those lines, will be - # treated as a single comment. leading_detached_comments will keep paragraphs - # of comments that appear before (but not connected to) the current element. - # Each paragraph, separated by empty lines, will be one comment element in - # the repeated field. Only the comment content is provided; comment markers - # (e.g. //) are stripped out. For block comments, leading whitespace and an - # asterisk will be stripped from the beginning of each line other than the - # first. Newlines are included in the output. Examples: optional int32 foo - # = 1; // Comment attached to foo. // Comment attached to bar. optional - # int32 bar = 2; optional string baz = 3; // Comment attached to baz. - # // Another line attached to baz. // Comment attached to qux. // // - # Another line attached to qux. optional double qux = 4; // Detached - # comment for corge. This is not leading or trailing comments // to qux or - # corge because there are blank lines separating it from // both. // - # Detached comment for corge paragraph 2. optional string corge = 5; /* - # Block comment attached * to corge. Leading asterisks * will be - # removed. */ /* Block comment attached to * grault. */ optional int32 - # grault = 6; // ignored detached comments. + """ + Always has exactly three or four elements: start line, start column, end + line (optional, otherwise assumed same as start line), end column. These + are packed into a single field for efficiency. Note that line and column + numbers are zero-based -- typically you will want to add 1 to each before + displaying to a user. + """ + leading_comments: str = betterproto.string_field(3) + """ + If this SourceCodeInfo represents a complete declaration, these are any + comments appearing before and after the declaration which appear to be + attached to the declaration. A series of line comments appearing on + consecutive lines, with no other tokens appearing on those lines, will be + treated as a single comment. leading_detached_comments will keep paragraphs + of comments that appear before (but not connected to) the current element. + Each paragraph, separated by empty lines, will be one comment element in + the repeated field. Only the comment content is provided; comment markers + (e.g. //) are stripped out. For block comments, leading whitespace and an + asterisk will be stripped from the beginning of each line other than the + first. Newlines are included in the output. Examples: optional int32 foo + = 1; // Comment attached to foo. // Comment attached to bar. optional + int32 bar = 2; optional string baz = 3; // Comment attached to baz. + // Another line attached to baz. // Comment attached to qux. // // + Another line attached to qux. optional double qux = 4; // Detached + comment for corge. This is not leading or trailing comments // to qux or + corge because there are blank lines separating it from // both. // + Detached comment for corge paragraph 2. optional string corge = 5; /* + Block comment attached * to corge. Leading asterisks * will be + removed. */ /* Block comment attached to * grault. */ optional int32 + grault = 6; // ignored detached comments. + """ + trailing_comments: str = betterproto.string_field(4) leading_detached_comments: List[str] = betterproto.string_field(6) @@ -961,25 +1263,36 @@ class GeneratedCodeInfo(betterproto.Message): source file, but may contain references to different source .proto files. """ - # An Annotation connects some span of text in generated code to an element of - # its generating .proto file. annotation: List["GeneratedCodeInfoAnnotation"] = betterproto.message_field(1) + """ + An Annotation connects some span of text in generated code to an element of + its generating .proto file. + """ @dataclass(eq=False, repr=False) class GeneratedCodeInfoAnnotation(betterproto.Message): - # Identifies the element in the original source .proto file. This field is - # formatted the same as SourceCodeInfo.Location.path. path: List[int] = betterproto.int32_field(1) - # Identifies the filesystem path to the original source .proto. + """ + Identifies the element in the original source .proto file. This field is + formatted the same as SourceCodeInfo.Location.path. + """ + source_file: str = betterproto.string_field(2) - # Identifies the starting offset in bytes in the generated code that relates - # to the identified object. + """Identifies the filesystem path to the original source .proto.""" + begin: int = betterproto.int32_field(3) - # Identifies the ending offset in bytes in the generated code that relates to - # the identified offset. The end offset should be one past the last relevant - # byte (so the length of the text = end - begin). + """ + Identifies the starting offset in bytes in the generated code that relates + to the identified object. + """ + end: int = betterproto.int32_field(4) + """ + Identifies the ending offset in bytes in the generated code that relates to + the identified offset. The end offset should be one past the last relevant + byte (so the length of the text = end - begin). + """ @dataclass(eq=False, repr=False) @@ -1015,16 +1328,21 @@ class Duration(betterproto.Message): format as "3.000001s". """ - # Signed seconds of the span of time. Must be from -315,576,000,000 to - # +315,576,000,000 inclusive. Note: these bounds are computed from: 60 - # sec/min * 60 min/hr * 24 hr/day * 365.25 days/year * 10000 years seconds: int = betterproto.int64_field(1) - # Signed fractions of a second at nanosecond resolution of the span of time. - # Durations less than one second are represented with a 0 `seconds` field and - # a positive or negative `nanos` field. For durations of one second or more, - # a non-zero value for the `nanos` field must be of the same sign as the - # `seconds` field. Must be from -999,999,999 to +999,999,999 inclusive. + """ + Signed seconds of the span of time. Must be from -315,576,000,000 to + +315,576,000,000 inclusive. Note: these bounds are computed from: 60 + sec/min * 60 min/hr * 24 hr/day * 365.25 days/year * 10000 years + """ + nanos: int = betterproto.int32_field(2) + """ + Signed fractions of a second at nanosecond resolution of the span of time. + Durations less than one second are represented with a 0 `seconds` field and + a positive or negative `nanos` field. For durations of one second or more, + a non-zero value for the `nanos` field must be of the same sign as the + `seconds` field. Must be from -999,999,999 to +999,999,999 inclusive. + """ @dataclass(eq=False, repr=False) @@ -1120,8 +1438,8 @@ class FieldMask(betterproto.Message): `INVALID_ARGUMENT` error if any path is unmappable. """ - # The set of field mask paths. paths: List[str] = betterproto.string_field(1) + """The set of field mask paths.""" @dataclass(eq=False, repr=False) @@ -1135,10 +1453,10 @@ class Struct(betterproto.Message): representation for `Struct` is JSON object. """ - # Unordered map of dynamically typed values. fields: Dict[str, "Value"] = betterproto.map_field( 1, betterproto.TYPE_STRING, betterproto.TYPE_MESSAGE ) + """Unordered map of dynamically typed values.""" @dataclass(eq=False, repr=False) @@ -1146,23 +1464,28 @@ class Value(betterproto.Message): """ `Value` represents a dynamically typed value which can be either null, a number, a string, a boolean, a recursive struct value, or a list of values. - A producer of value is expected to set one of that variants, absence of any - variant indicates an error. The JSON representation for `Value` is JSON + A producer of value is expected to set one of these variants. Absence of + any variant indicates an error. The JSON representation for `Value` is JSON value. """ - # Represents a null value. null_value: "NullValue" = betterproto.enum_field(1, group="kind") - # Represents a double value. + """Represents a null value.""" + number_value: float = betterproto.double_field(2, group="kind") - # Represents a string value. + """Represents a double value.""" + string_value: str = betterproto.string_field(3, group="kind") - # Represents a boolean value. + """Represents a string value.""" + bool_value: bool = betterproto.bool_field(4, group="kind") - # Represents a structured value. + """Represents a boolean value.""" + struct_value: "Struct" = betterproto.message_field(5, group="kind") - # Represents a repeated `Value`. + """Represents a structured value.""" + list_value: "ListValue" = betterproto.message_field(6, group="kind") + """Represents a repeated `Value`.""" @dataclass(eq=False, repr=False) @@ -1172,8 +1495,8 @@ class ListValue(betterproto.Message): representation for `ListValue` is JSON array. """ - # Repeated field of dynamically typed values. values: List["Value"] = betterproto.message_field(1) + """Repeated field of dynamically typed values.""" @dataclass(eq=False, repr=False) @@ -1234,13 +1557,18 @@ class Timestamp(betterproto.Message): to obtain a formatter capable of generating timestamps in this format. """ - # Represents seconds of UTC time since Unix epoch 1970-01-01T00:00:00Z. Must - # be from 0001-01-01T00:00:00Z to 9999-12-31T23:59:59Z inclusive. seconds: int = betterproto.int64_field(1) - # Non-negative fractions of a second at nanosecond resolution. Negative - # second values with fractions must still have non-negative nanos values that - # count forward in time. Must be from 0 to 999,999,999 inclusive. + """ + Represents seconds of UTC time since Unix epoch 1970-01-01T00:00:00Z. Must + be from 0001-01-01T00:00:00Z to 9999-12-31T23:59:59Z inclusive. + """ + nanos: int = betterproto.int32_field(2) + """ + Non-negative fractions of a second at nanosecond resolution. Negative + second values with fractions must still have non-negative nanos values that + count forward in time. Must be from 0 to 999,999,999 inclusive. + """ @dataclass(eq=False, repr=False) @@ -1250,8 +1578,8 @@ class DoubleValue(betterproto.Message): JSON number. """ - # The double value. value: float = betterproto.double_field(1) + """The double value.""" @dataclass(eq=False, repr=False) @@ -1261,8 +1589,8 @@ class FloatValue(betterproto.Message): JSON number. """ - # The float value. value: float = betterproto.float_field(1) + """The float value.""" @dataclass(eq=False, repr=False) @@ -1272,8 +1600,8 @@ class Int64Value(betterproto.Message): JSON string. """ - # The int64 value. value: int = betterproto.int64_field(1) + """The int64 value.""" @dataclass(eq=False, repr=False) @@ -1283,8 +1611,8 @@ class UInt64Value(betterproto.Message): JSON string. """ - # The uint64 value. value: int = betterproto.uint64_field(1) + """The uint64 value.""" @dataclass(eq=False, repr=False) @@ -1294,8 +1622,8 @@ class Int32Value(betterproto.Message): JSON number. """ - # The int32 value. value: int = betterproto.int32_field(1) + """The int32 value.""" @dataclass(eq=False, repr=False) @@ -1305,8 +1633,8 @@ class UInt32Value(betterproto.Message): JSON number. """ - # The uint32 value. value: int = betterproto.uint32_field(1) + """The uint32 value.""" @dataclass(eq=False, repr=False) @@ -1316,8 +1644,8 @@ class BoolValue(betterproto.Message): `true` and `false`. """ - # The bool value. value: bool = betterproto.bool_field(1) + """The bool value.""" @dataclass(eq=False, repr=False) @@ -1327,8 +1655,8 @@ class StringValue(betterproto.Message): JSON string. """ - # The string value. value: str = betterproto.string_field(1) + """The string value.""" @dataclass(eq=False, repr=False) @@ -1338,5 +1666,5 @@ class BytesValue(betterproto.Message): JSON string. """ - # The bytes value. value: bytes = betterproto.bytes_field(1) + """The bytes value.""" diff --git a/src/betterproto/lib/google/protobuf/compiler/__init__.py b/src/betterproto/lib/google/protobuf/compiler/__init__.py index cb2396d..58f9a13 100644 --- a/src/betterproto/lib/google/protobuf/compiler/__init__.py +++ b/src/betterproto/lib/google/protobuf/compiler/__init__.py @@ -1,14 +1,17 @@ # Generated by the protocol buffer compiler. DO NOT EDIT! # sources: google/protobuf/compiler/plugin.proto # plugin: python-betterproto +# This file has been @generated from dataclasses import dataclass from typing import List import betterproto -from betterproto.grpc.grpclib_server import ServiceBase +import betterproto.lib.google.protobuf as betterproto_lib_google_protobuf class CodeGeneratorResponseFeature(betterproto.Enum): + """Sync with code_generator.h.""" + FEATURE_NONE = 0 FEATURE_PROTO3_OPTIONAL = 1 @@ -20,54 +23,69 @@ class Version(betterproto.Message): major: int = betterproto.int32_field(1) minor: int = betterproto.int32_field(2) patch: int = betterproto.int32_field(3) - # A suffix for alpha, beta or rc release, e.g., "alpha-1", "rc2". It should - # be empty for mainline stable releases. suffix: str = betterproto.string_field(4) + """ + A suffix for alpha, beta or rc release, e.g., "alpha-1", "rc2". It should + be empty for mainline stable releases. + """ @dataclass(eq=False, repr=False) class CodeGeneratorRequest(betterproto.Message): """An encoded CodeGeneratorRequest is written to the plugin's stdin.""" - # The .proto files that were explicitly listed on the command-line. The code - # generator should generate code only for these files. Each file's - # descriptor will be included in proto_file, below. file_to_generate: List[str] = betterproto.string_field(1) - # The generator parameter passed on the command-line. + """ + The .proto files that were explicitly listed on the command-line. The code + generator should generate code only for these files. Each file's + descriptor will be included in proto_file, below. + """ + parameter: str = betterproto.string_field(2) - # FileDescriptorProtos for all files in files_to_generate and everything they - # import. The files will appear in topological order, so each file appears - # before any file that imports it. protoc guarantees that all proto_files - # will be written after the fields above, even though this is not technically - # guaranteed by the protobuf wire format. This theoretically could allow a - # plugin to stream in the FileDescriptorProtos and handle them one by one - # rather than read the entire set into memory at once. However, as of this - # writing, this is not similarly optimized on protoc's end -- it will store - # all fields in memory at once before sending them to the plugin. Type names - # of fields and extensions in the FileDescriptorProto are always fully - # qualified. + """The generator parameter passed on the command-line.""" + proto_file: List[ "betterproto_lib_google_protobuf.FileDescriptorProto" ] = betterproto.message_field(15) - # The version number of protocol compiler. + """ + FileDescriptorProtos for all files in files_to_generate and everything they + import. The files will appear in topological order, so each file appears + before any file that imports it. protoc guarantees that all proto_files + will be written after the fields above, even though this is not technically + guaranteed by the protobuf wire format. This theoretically could allow a + plugin to stream in the FileDescriptorProtos and handle them one by one + rather than read the entire set into memory at once. However, as of this + writing, this is not similarly optimized on protoc's end -- it will store + all fields in memory at once before sending them to the plugin. Type names + of fields and extensions in the FileDescriptorProto are always fully + qualified. + """ + compiler_version: "Version" = betterproto.message_field(3) + """The version number of protocol compiler.""" @dataclass(eq=False, repr=False) class CodeGeneratorResponse(betterproto.Message): """The plugin writes an encoded CodeGeneratorResponse to stdout.""" - # Error message. If non-empty, code generation failed. The plugin process - # should exit with status code zero even if it reports an error in this way. - # This should be used to indicate errors in .proto files which prevent the - # code generator from generating correct code. Errors which indicate a - # problem in protoc itself -- such as the input CodeGeneratorRequest being - # unparseable -- should be reported by writing a message to stderr and - # exiting with a non-zero status code. error: str = betterproto.string_field(1) - # A bitmask of supported features that the code generator supports. This is a - # bitwise "or" of values from the Feature enum. + """ + Error message. If non-empty, code generation failed. The plugin process + should exit with status code zero even if it reports an error in this way. + This should be used to indicate errors in .proto files which prevent the + code generator from generating correct code. Errors which indicate a + problem in protoc itself -- such as the input CodeGeneratorRequest being + unparseable -- should be reported by writing a message to stderr and + exiting with a non-zero status code. + """ + supported_features: int = betterproto.uint64_field(2) + """ + A bitmask of supported features that the code generator supports. This is a + bitwise "or" of values from the Feature enum. + """ + file: List["CodeGeneratorResponseFile"] = betterproto.message_field(15) @@ -75,54 +93,60 @@ class CodeGeneratorResponse(betterproto.Message): class CodeGeneratorResponseFile(betterproto.Message): """Represents a single generated file.""" - # The file name, relative to the output directory. The name must not contain - # "." or ".." components and must be relative, not be absolute (so, the file - # cannot lie outside the output directory). "/" must be used as the path - # separator, not "\". If the name is omitted, the content will be appended to - # the previous file. This allows the generator to break large files into - # small chunks, and allows the generated text to be streamed back to protoc - # so that large files need not reside completely in memory at one time. Note - # that as of this writing protoc does not optimize for this -- it will read - # the entire CodeGeneratorResponse before writing files to disk. name: str = betterproto.string_field(1) - # If non-empty, indicates that the named file should already exist, and the - # content here is to be inserted into that file at a defined insertion point. - # This feature allows a code generator to extend the output produced by - # another code generator. The original generator may provide insertion - # points by placing special annotations in the file that look like: - # @@protoc_insertion_point(NAME) The annotation can have arbitrary text - # before and after it on the line, which allows it to be placed in a comment. - # NAME should be replaced with an identifier naming the point -- this is what - # other generators will use as the insertion_point. Code inserted at this - # point will be placed immediately above the line containing the insertion - # point (thus multiple insertions to the same point will come out in the - # order they were added). The double-@ is intended to make it unlikely that - # the generated code could contain things that look like insertion points by - # accident. For example, the C++ code generator places the following line in - # the .pb.h files that it generates: // - # @@protoc_insertion_point(namespace_scope) This line appears within the - # scope of the file's package namespace, but outside of any particular class. - # Another plugin can then specify the insertion_point "namespace_scope" to - # generate additional classes or other declarations that should be placed in - # this scope. Note that if the line containing the insertion point begins - # with whitespace, the same whitespace will be added to every line of the - # inserted text. This is useful for languages like Python, where indentation - # matters. In these languages, the insertion point comment should be - # indented the same amount as any inserted code will need to be in order to - # work correctly in that context. The code generator that generates the - # initial file and the one which inserts into it must both run as part of a - # single invocation of protoc. Code generators are executed in the order in - # which they appear on the command line. If |insertion_point| is present, - # |name| must also be present. + """ + The file name, relative to the output directory. The name must not contain + "." or ".." components and must be relative, not be absolute (so, the file + cannot lie outside the output directory). "/" must be used as the path + separator, not "\". If the name is omitted, the content will be appended to + the previous file. This allows the generator to break large files into + small chunks, and allows the generated text to be streamed back to protoc + so that large files need not reside completely in memory at one time. Note + that as of this writing protoc does not optimize for this -- it will read + the entire CodeGeneratorResponse before writing files to disk. + """ + insertion_point: str = betterproto.string_field(2) - # The file contents. + """ + If non-empty, indicates that the named file should already exist, and the + content here is to be inserted into that file at a defined insertion point. + This feature allows a code generator to extend the output produced by + another code generator. The original generator may provide insertion + points by placing special annotations in the file that look like: + @@protoc_insertion_point(NAME) The annotation can have arbitrary text + before and after it on the line, which allows it to be placed in a comment. + NAME should be replaced with an identifier naming the point -- this is what + other generators will use as the insertion_point. Code inserted at this + point will be placed immediately above the line containing the insertion + point (thus multiple insertions to the same point will come out in the + order they were added). The double-@ is intended to make it unlikely that + the generated code could contain things that look like insertion points by + accident. For example, the C++ code generator places the following line in + the .pb.h files that it generates: // + @@protoc_insertion_point(namespace_scope) This line appears within the + scope of the file's package namespace, but outside of any particular class. + Another plugin can then specify the insertion_point "namespace_scope" to + generate additional classes or other declarations that should be placed in + this scope. Note that if the line containing the insertion point begins + with whitespace, the same whitespace will be added to every line of the + inserted text. This is useful for languages like Python, where indentation + matters. In these languages, the insertion point comment should be + indented the same amount as any inserted code will need to be in order to + work correctly in that context. The code generator that generates the + initial file and the one which inserts into it must both run as part of a + single invocation of protoc. Code generators are executed in the order in + which they appear on the command line. If |insertion_point| is present, + |name| must also be present. + """ + content: str = betterproto.string_field(15) - # Information describing the file content being inserted. If an insertion - # point is used, this information will be appropriately offset and inserted - # into the code generation metadata for the generated files. + """The file contents.""" + generated_code_info: "betterproto_lib_google_protobuf.GeneratedCodeInfo" = ( betterproto.message_field(16) ) - - -import betterproto.lib.google.protobuf as betterproto_lib_google_protobuf + """ + Information describing the file content being inserted. If an insertion + point is used, this information will be appropriately offset and inserted + into the code generation metadata for the generated files. + """ diff --git a/src/betterproto/templates/template.py.j2 b/src/betterproto/templates/template.py.j2 index ce6fe90..61c1863 100644 --- a/src/betterproto/templates/template.py.j2 +++ b/src/betterproto/templates/template.py.j2 @@ -1,6 +1,7 @@ # Generated by the protocol buffer compiler. DO NOT EDIT! # sources: {{ ', '.join(output_file.input_filenames) }} # plugin: python-betterproto +# This file has been @generated {% for i in output_file.python_module_imports|sort %} import {{ i }} {% endfor %}