protobuf.wkt
Protobuf Well-Known types.
ext_csharp
module-attribute
ext_csharp = Extension()
ext_cpp
module-attribute
ext_cpp = Extension()
ext_go
module-attribute
ext_go = Extension()
ext_java
module-attribute
ext_java = Extension()
Any
Bases: Message[_AnyFields], AnyMixin
Any contains an arbitrary serialized protocol buffer message along with a
URL that describes the type of the serialized message.
In its binary encoding, an Any is an ordinary message; but in other wire
forms like JSON, it has a special encoding. The format of the type URL is
described on the type_url field.
Protobuf APIs provide utilities to interact with Any values:
- A 'pack' operation accepts a message and constructs a generic
Anywrapper around it. - An 'unpack' operation reads the content of an
Anymessage, either into an existing message or a new one. Unpack operations must check the type of the value they unpack against the declaredtype_url. - An 'is' operation decides whether an
Anycontains a message of the given type, i.e. whether it can 'unpack' that type.
The JSON format representation of an Any follows one of these cases:
- For types without special-cased JSON encodings, the JSON format
representation of the
Anyis the same as that of the message, with an additional@typefield which contains the type URL. - For types with special-cased JSON encodings (typically called 'well-known'
types, listed in https://protobuf.dev/programming-guides/json/#any), the
JSON format representation has a key
@typewhich contains the type URL and a keyvaluewhich contains the JSON-serialized value.
The text format representation of an Any is like a message with one field
whose name is the type URL in brackets. For example, an Any containing a
foo.Bar message may be written [type.googleapis.com/foo.Bar] { a: 2 }.
Attributes:
| Name | Type | Description |
|---|---|---|
type_url |
str
|
Identifies the type of the serialized Protobuf message with a URI reference consisting of a prefix ending in a slash and the fully-qualified type name. Example: type.googleapis.com/google.protobuf.StringValue This string must contain at least one The prefix is arbitrary and Protobuf implementations are expected to
simply strip off everything up to and including the last All type URL strings must be legal URI references with the additional
restriction (for the text format) that the content of the reference
must consist only of alphanumeric characters, percent-encoded escapes, and
characters in the following set (not including the outer backticks):
In the original design of |
value |
bytes
|
Api
Api(
*,
name="",
methods=None,
options=None,
version="",
source_context=None,
mixins=None,
syntax=None,
edition="",
)
Bases: Message[_ApiFields]
Api is a light-weight descriptor for an API Interface.
Interfaces are also described as "protocol buffer services" in some contexts, such as by the "service" keyword in a .proto file, but they are different from API Services, which represent a concrete implementation of an interface as opposed to simply a description of methods and bindings. They are also sometimes simply referred to as "APIs" in other contexts, such as the name of this message itself. See https://cloud.google.com/apis/design/glossary for detailed terminology.
New usages of this message as an alternative to ServiceDescriptorProto are strongly discouraged. This message does not reliability preserve all information necessary to model the schema and preserve semantics. Instead make use of FileDescriptorSet which preserves the necessary information.
Attributes:
| Name | Type | Description |
|---|---|---|
name |
str
|
|
methods |
list[Method]
|
|
options |
list[Option]
|
|
version |
str
|
A version string for this interface. If specified, must have the form
The versioning schema uses semantic versioning 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 |
source_context |
SourceContext | None
|
|
mixins |
list[Mixin]
|
|
syntax |
Syntax
|
|
edition |
str
|
Method
Method(
*,
name="",
request_type_url="",
request_streaming=False,
response_type_url="",
response_streaming=False,
options=None,
syntax=None,
edition="",
)
Bases: Message[_MethodFields]
Method represents a method of an API interface.
New usages of this message as an alternative to MethodDescriptorProto are strongly discouraged. This message does not reliability preserve all information necessary to model the schema and preserve semantics. Instead make use of FileDescriptorSet which preserves the necessary information.
Attributes:
| Name | Type | Description |
|---|---|---|
name |
str
|
|
request_type_url |
str
|
|
request_streaming |
bool
|
|
response_type_url |
str
|
|
response_streaming |
bool
|
|
options |
list[Option]
|
|
syntax |
Syntax
|
|
edition |
str
|
Mixin
Bases: Message[_MixinFields]
Declares an API Interface to be included in this interface. The including interface must redeclare all the methods from the included interface, but documentation and options are inherited as follows:
-
If after comment and whitespace stripping, the documentation string of the redeclared method is empty, it will be inherited from the original method.
-
Each annotation belonging to the service config (http, visibility) which is not set in the redeclared method will be inherited.
-
If an http annotation is inherited, the path pattern will be modified as follows. Any version prefix will be replaced by the version of the including interface plus the [root][] path if specified.
Example of a simple mixin:
package google.acl.v1;
service AccessControl {
// Get the underlying ACL object.
rpc GetAcl(GetAclRequest) returns (Acl) {
option (google.api.http).get = "/v1/{resource=**}:getAcl";
}
}
package google.storage.v2;
service Storage {
rpc GetAcl(GetAclRequest) returns (Acl);
// Get a data record.
rpc GetData(GetDataRequest) returns (Data) {
option (google.api.http).get = "/v2/{resource=**}";
}
}
Example of a mixin configuration:
apis:
- name: google.storage.v2.Storage
mixins:
- name: google.acl.v1.AccessControl
The mixin construct implies that all methods in AccessControl are
also declared with same name and request/response types in
Storage. A documentation generator or annotation processor will
see the effective Storage.GetAcl method after inheriting
documentation and annotations as follows:
service Storage {
// Get the underlying ACL object.
rpc GetAcl(GetAclRequest) returns (Acl) {
option (google.api.http).get = "/v2/{resource=**}:getAcl";
}
...
}
Note how the version in the path pattern changed from v1 to v2.
If the root field in the mixin is specified, it should be a
relative path under which inherited HTTP paths are placed. Example:
apis:
- name: google.storage.v2.Storage
mixins:
- name: google.acl.v1.AccessControl
root: acls
This implies the following inherited HTTP annotation:
service Storage {
// Get the underlying ACL object.
rpc GetAcl(GetAclRequest) returns (Acl) {
option (google.api.http).get = "/v2/acls/{resource=**}:getAcl";
}
...
}
Attributes:
| Name | Type | Description |
|---|---|---|
name |
str
|
|
root |
str
|
CodeGeneratorRequest
CodeGeneratorRequest(
*,
file_to_generate=None,
parameter=None,
proto_file=None,
source_file_descriptors=None,
compiler_version=None,
)
Bases: Message[_CodeGeneratorRequestFields]
An encoded CodeGeneratorRequest is written to the plugin's stdin.
Attributes:
| Name | Type | Description |
|---|---|---|
file_to_generate |
list[str]
|
|
parameter |
str
|
|
proto_file |
list[FileDescriptorProto]
|
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. Note: the files listed in files_to_generate will include runtime-retention options only, but all other files will include source-retention options. The source_file_descriptors field below is available in case you need source-retention options for files_to_generate. 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. |
source_file_descriptors |
list[FileDescriptorProto]
|
|
compiler_version |
Version | None
|
CodeGeneratorResponse
CodeGeneratorResponse(
*,
error=None,
supported_features=None,
minimum_edition=None,
maximum_edition=None,
file=None,
)
Bases: Message[_CodeGeneratorResponseFields]
The plugin writes an encoded CodeGeneratorResponse to stdout.
Attributes:
| Name | Type | Description |
|---|---|---|
error |
str
|
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
|
|
minimum_edition |
int
|
The minimum edition this plugin supports. This will be treated as an Edition enum, but we want to allow unknown values. It should be specified according the edition enum value, not the edition number. Only takes effect for plugins that have FEATURE_SUPPORTS_EDITIONS set. |
maximum_edition |
int
|
The maximum edition this plugin supports. This will be treated as an Edition enum, but we want to allow unknown values. It should be specified according the edition enum value, not the edition number. Only takes effect for plugins that have FEATURE_SUPPORTS_EDITIONS set. |
file |
list[File]
|
File
Bases: Message[_FileFields]
Represents a single generated file.
Attributes:
| Name | Type | Description |
|---|---|---|
name |
str
|
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
|
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
|
|
generated_code_info |
GeneratedCodeInfo | None
|
Feature
Bases: Enum
Sync with code_generator.h.
Attributes:
| Name | Type | Description |
|---|---|---|
NONE |
||
PROTO3_OPTIONAL |
||
SUPPORTS_EDITIONS |
Version
CppFeatures
CppFeatures(
*,
legacy_closed_enum=None,
string_type=None,
enum_name_uses_string_view=None,
repeated_type=None,
)
Bases: Message[_CppFeaturesFields]
Attributes:
| Name | Type | Description |
|---|---|---|
legacy_closed_enum |
bool
|
|
string_type |
StringType
|
|
enum_name_uses_string_view |
bool
|
|
repeated_type |
RepeatedType
|
DescriptorProto
DescriptorProto(
*,
name=None,
field=None,
extension=None,
nested_type=None,
enum_type=None,
extension_range=None,
oneof_decl=None,
options=None,
reserved_range=None,
reserved_name=None,
visibility=None,
)
Bases: Message[_DescriptorProtoFields]
Describes a message type.
Attributes:
| Name | Type | Description |
|---|---|---|
name |
str
|
|
field |
list[FieldDescriptorProto]
|
|
extension |
list[FieldDescriptorProto]
|
|
nested_type |
list[DescriptorProto]
|
|
enum_type |
list[EnumDescriptorProto]
|
|
extension_range |
list[ExtensionRange]
|
|
oneof_decl |
list[OneofDescriptorProto]
|
|
options |
MessageOptions | None
|
|
reserved_range |
list[ReservedRange]
|
|
reserved_name |
list[str]
|
|
visibility |
SymbolVisibility
|
ExtensionRange
Bases: Message[_ExtensionRangeFields]
Attributes:
| Name | Type | Description |
|---|---|---|
start |
int
|
|
end |
int
|
|
options |
ExtensionRangeOptions | None
|
Edition
Bases: Enum
The full set of known editions.
Attributes:
| Name | Type | Description |
|---|---|---|
UNKNOWN |
||
LEGACY |
||
PROTO2 |
||
PROTO3 |
||
EDITION_2023 |
||
EDITION_2024 |
||
EDITION_2026 |
||
UNSTABLE |
||
EDITION_1_TEST_ONLY |
||
EDITION_2_TEST_ONLY |
||
EDITION_99997_TEST_ONLY |
||
EDITION_99998_TEST_ONLY |
||
EDITION_99999_TEST_ONLY |
||
MAX |
EnumDescriptorProto
EnumDescriptorProto(
*,
name=None,
value=None,
options=None,
reserved_range=None,
reserved_name=None,
visibility=None,
)
Bases: Message[_EnumDescriptorProtoFields]
Describes an enum type.
Attributes:
| Name | Type | Description |
|---|---|---|
name |
str
|
|
value |
list[EnumValueDescriptorProto]
|
|
options |
EnumOptions | None
|
|
reserved_range |
list[EnumReservedRange]
|
|
reserved_name |
list[str]
|
|
visibility |
SymbolVisibility
|
EnumReservedRange
Bases: Message[_EnumReservedRangeFields]
Range of reserved numeric values. Reserved values may not be used by entries in the same enum. Reserved ranges may not overlap.
Note that this is distinct from DescriptorProto.ReservedRange in that it is inclusive such that it can appropriately represent the entire int32 domain.
Attributes:
| Name | Type | Description |
|---|---|---|
start |
int
|
|
end |
int
|
EnumOptions
EnumOptions(
*,
allow_alias=None,
deprecated=None,
deprecated_legacy_json_field_conflicts=None,
features=None,
uninterpreted_option=None,
)
Bases: Message[_EnumOptionsFields]
Attributes:
| Name | Type | Description |
|---|---|---|
allow_alias |
bool
|
|
deprecated |
bool
|
|
deprecated_legacy_json_field_conflicts |
bool
|
Enable the legacy handling of JSON field name conflicts. This lowercases
and strips underscored from the fields before comparison in proto3 only.
The new behavior takes |
features |
FeatureSet | None
|
Any features defined in the specific edition. WARNING: This field should only be used by protobuf plugins or special cases like the proto compiler. Other uses are discouraged and developers should rely on the protoreflect APIs for their client language. |
uninterpreted_option |
list[UninterpretedOption]
|
EnumValueDescriptorProto
Bases: Message[_EnumValueDescriptorProtoFields]
Describes a value within an enum.
Attributes:
| Name | Type | Description |
|---|---|---|
name |
str
|
|
number |
int
|
|
options |
EnumValueOptions | None
|
EnumValueOptions
EnumValueOptions(
*,
deprecated=None,
features=None,
debug_redact=None,
feature_support=None,
uninterpreted_option=None,
)
Bases: Message[_EnumValueOptionsFields]
Attributes:
| Name | Type | Description |
|---|---|---|
deprecated |
bool
|
|
features |
FeatureSet | None
|
Any features defined in the specific edition. WARNING: This field should only be used by protobuf plugins or special cases like the proto compiler. Other uses are discouraged and developers should rely on the protoreflect APIs for their client language. |
debug_redact |
bool
|
|
feature_support |
FeatureSupport | None
|
|
uninterpreted_option |
list[UninterpretedOption]
|
ExtensionRangeOptions
ExtensionRangeOptions(
*,
uninterpreted_option=None,
declaration=None,
features=None,
verification=None,
)
Bases: Message[_ExtensionRangeOptionsFields]
Attributes:
| Name | Type | Description |
|---|---|---|
uninterpreted_option |
list[UninterpretedOption]
|
|
declaration |
list[Declaration]
|
|
features |
FeatureSet | None
|
|
verification |
VerificationState
|
FeatureSet
FeatureSet(
*,
field_presence=None,
enum_type=None,
repeated_field_encoding=None,
utf8_validation=None,
message_encoding=None,
json_format=None,
enforce_naming_style=None,
default_symbol_visibility=None,
)
Bases: Message[_FeatureSetFields]
TODO Enums in C++ gencode (and potentially other languages) are not well scoped. This means that each of the feature enums below can clash with each other. The short names we've chosen maximize call-site readability, but leave us very open to this scenario. A future feature will be designed and implemented to handle this, hopefully before we ever hit a conflict here.
Attributes:
| Name | Type | Description |
|---|---|---|
field_presence |
FieldPresence
|
|
enum_type |
EnumType
|
|
repeated_field_encoding |
RepeatedFieldEncoding
|
|
utf8_validation |
Utf8Validation
|
|
message_encoding |
MessageEncoding
|
|
json_format |
JsonFormat
|
|
enforce_naming_style |
EnforceNamingStyle
|
|
default_symbol_visibility |
DefaultSymbolVisibility
|
VisibilityFeature
Bases: Message[_VisibilityFeatureFields]
DefaultSymbolVisibility
FieldPresence
EnumType
RepeatedFieldEncoding
Utf8Validation
MessageEncoding
JsonFormat
EnforceNamingStyle
FeatureSetDefaults
Bases: Message[_FeatureSetDefaultsFields]
A compiled specification for the defaults of a set of features. These messages are generated from FeatureSet extensions and can be used to seed feature resolution. The resolution with this object becomes a simple search for the closest matching edition, followed by proto merges.
Attributes:
| Name | Type | Description |
|---|---|---|
defaults |
list[FeatureSetEditionDefault]
|
|
minimum_edition |
Edition
|
|
maximum_edition |
Edition
|
FeatureSetEditionDefault
Bases: Message[_FeatureSetEditionDefaultFields]
A map from every known edition with a unique set of defaults to its defaults. Not all editions may be contained here. For a given edition, the defaults at the closest matching edition ordered at or before it should be used. This field must be in strict ascending order by edition.
Attributes:
| Name | Type | Description |
|---|---|---|
edition |
Edition
|
|
overridable_features |
FeatureSet | None
|
|
fixed_features |
FeatureSet | None
|
FieldDescriptorProto
FieldDescriptorProto(
*,
name=None,
number=None,
label=None,
type=None,
type_name=None,
extendee=None,
default_value=None,
oneof_index=None,
json_name=None,
options=None,
proto3_optional=None,
)
Bases: Message[_FieldDescriptorProtoFields]
Describes a field within a message.
Attributes:
| Name | Type | Description |
|---|---|---|
name |
str
|
|
number |
int
|
|
label |
Label
|
|
type |
Type
|
|
type_name |
str
|
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
|
|
default_value |
str
|
|
oneof_index |
int
|
|
json_name |
str
|
|
options |
FieldOptions | None
|
|
proto3_optional |
bool
|
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 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 |
Type
Bases: Enum
Attributes:
| Name | Type | Description |
|---|---|---|
DOUBLE |
||
FLOAT |
||
INT64 |
||
UINT64 |
||
INT32 |
||
FIXED64 |
||
FIXED32 |
||
BOOL |
||
STRING |
||
GROUP |
Tag-delimited aggregate.
Group type is deprecated and not supported after google.protobuf. However, Proto3
implementations should still be able to parse the group wire format and
treat group fields as unknown fields. In Editions, the group wire format
can be enabled via the |
|
MESSAGE |
||
BYTES |
||
UINT32 |
||
ENUM |
||
SFIXED32 |
||
SFIXED64 |
||
SINT32 |
||
SINT64 |
Label
FieldOptions
FieldOptions(
*,
ctype=None,
packed=None,
jstype=None,
lazy=None,
unverified_lazy=None,
deprecated=None,
weak=None,
debug_redact=None,
retention=None,
targets=None,
edition_defaults=None,
features=None,
feature_support=None,
uninterpreted_option=None,
)
Bases: Message[_FieldOptionsFields]
Attributes:
| Name | Type | Description |
|---|---|---|
ctype |
CType
|
NOTE: ctype is deprecated. Use |
packed |
bool
|
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. This option is prohibited in
Editions, but the |
jstype |
JSType
|
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
|
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 lazy message fields are still eagerly verified to check ill-formed wireformat or missing required fields. Calling IsInitialized() on the outer message would fail if the inner message has missing required fields. Failed verification would result in parsing failure (except when uninitialized messages are acceptable). |
unverified_lazy |
bool
|
|
deprecated |
bool
|
|
weak |
bool
|
|
debug_redact |
bool
|
|
retention |
OptionRetention
|
|
targets |
list[OptionTargetType]
|
|
edition_defaults |
list[EditionDefault]
|
|
features |
FeatureSet | None
|
Any features defined in the specific edition. WARNING: This field should only be used by protobuf plugins or special cases like the proto compiler. Other uses are discouraged and developers should rely on the protoreflect APIs for their client language. |
feature_support |
FeatureSupport | None
|
|
uninterpreted_option |
list[UninterpretedOption]
|
EditionDefault
FeatureSupport
FeatureSupport(
*,
edition_introduced=None,
edition_deprecated=None,
deprecation_warning=None,
edition_removed=None,
removal_error=None,
)
CType
Bases: Enum
Attributes:
| Name | Type | Description |
|---|---|---|
STRING |
||
CORD |
The option [ctype=CORD] may be applied to a non-repeated field of type "bytes". It indicates that in C++, the data should be stored in a Cord instead of a string. For very large strings, this may reduce memory fragmentation. It may also allow better performance when parsing from a Cord, or when parsing with aliasing enabled, as the parsed Cord may then alias the original buffer. |
|
STRING_PIECE |
JSType
OptionRetention
Bases: Enum
If set to RETENTION_SOURCE, the option will be omitted from the binary.
Attributes:
| Name | Type | Description |
|---|---|---|
RETENTION_UNKNOWN |
||
RETENTION_RUNTIME |
||
RETENTION_SOURCE |
OptionTargetType
Bases: Enum
This indicates the types of entities that the field may apply to when used as an option. If it is unset, then the field may be freely used as an option on any kind of entity.
Attributes:
| Name | Type | Description |
|---|---|---|
TARGET_TYPE_UNKNOWN |
||
TARGET_TYPE_FILE |
||
TARGET_TYPE_EXTENSION_RANGE |
||
TARGET_TYPE_MESSAGE |
||
TARGET_TYPE_FIELD |
||
TARGET_TYPE_ONEOF |
||
TARGET_TYPE_ENUM |
||
TARGET_TYPE_ENUM_ENTRY |
||
TARGET_TYPE_SERVICE |
||
TARGET_TYPE_METHOD |
FileDescriptorProto
FileDescriptorProto(
*,
name=None,
package=None,
dependency=None,
public_dependency=None,
weak_dependency=None,
option_dependency=None,
message_type=None,
enum_type=None,
service=None,
extension=None,
options=None,
source_code_info=None,
syntax=None,
edition=None,
)
Bases: Message[_FileDescriptorProtoFields]
Describes a complete .proto file.
Attributes:
| Name | Type | Description |
|---|---|---|
name |
str
|
|
package |
str
|
|
dependency |
list[str]
|
|
public_dependency |
list[int]
|
|
weak_dependency |
list[int]
|
|
option_dependency |
list[str]
|
|
message_type |
list[DescriptorProto]
|
|
enum_type |
list[EnumDescriptorProto]
|
|
service |
list[ServiceDescriptorProto]
|
|
extension |
list[FieldDescriptorProto]
|
|
options |
FileOptions | None
|
|
source_code_info |
SourceCodeInfo | None
|
|
syntax |
str
|
The syntax of the proto file. The supported values are "proto2", "proto3", and "editions". If |
edition |
Edition
|
FileDescriptorSet
Bases: Message[_FileDescriptorSetFields], FileDescriptorSetMixin
The protocol compiler can output a FileDescriptorSet containing the .proto files it parses.
Attributes:
| Name | Type | Description |
|---|---|---|
file |
list[FileDescriptorProto]
|
FileOptions
FileOptions(
*,
java_package=None,
java_outer_classname=None,
java_multiple_files=None,
java_generate_equals_and_hash=None,
java_string_check_utf8=None,
optimize_for=None,
go_package=None,
cc_generic_services=None,
java_generic_services=None,
py_generic_services=None,
deprecated=None,
cc_enable_arenas=None,
objc_class_prefix=None,
csharp_namespace=None,
swift_prefix=None,
php_class_prefix=None,
php_namespace=None,
php_metadata_namespace=None,
ruby_package=None,
features=None,
uninterpreted_option=None,
)
Bases: Message[_FileOptionsFields]
Attributes:
| Name | Type | Description |
|---|---|---|
java_package |
str
|
|
java_outer_classname |
str
|
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
|
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
|
|
java_string_check_utf8 |
bool
|
A proto2 file can set this to true to opt in to UTF-8 checking for Java, which will throw an exception if invalid UTF-8 is parsed from the wire or assigned to a string field. TODO: clarify exactly what kinds of field types this option applies to, and update these docs accordingly. Proto3 files already perform these checks. Setting the option explicitly to false has no effect: it cannot be used to opt proto3 files out of UTF-8 checks. |
optimize_for |
OptimizeMode
|
|
go_package |
str
|
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
|
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
|
|
py_generic_services |
bool
|
|
deprecated |
bool
|
|
cc_enable_arenas |
bool
|
|
objc_class_prefix |
str
|
|
csharp_namespace |
str
|
|
swift_prefix |
str
|
|
php_class_prefix |
str
|
|
php_namespace |
str
|
|
php_metadata_namespace |
str
|
|
ruby_package |
str
|
|
features |
FeatureSet | None
|
Any features defined in the specific edition. WARNING: This field should only be used by protobuf plugins or special cases like the proto compiler. Other uses are discouraged and developers should rely on the protoreflect APIs for their client language. |
uninterpreted_option |
list[UninterpretedOption]
|
OptimizeMode
Bases: Enum
Generated classes can be optimized for speed or code size.
Attributes:
| Name | Type | Description |
|---|---|---|
SPEED |
||
CODE_SIZE |
||
LITE_RUNTIME |
GeneratedCodeInfo
Bases: Message[_GeneratedCodeInfoFields]
Describes the relationship between generated code and its original source file. A GeneratedCodeInfo message is associated with only one generated source file, but may contain references to different source .proto files.
Attributes:
| Name | Type | Description |
|---|---|---|
annotation |
list[Annotation]
|
Annotation
MessageOptions
MessageOptions(
*,
message_set_wire_format=None,
no_standard_descriptor_accessor=None,
deprecated=None,
map_entry=None,
deprecated_legacy_json_field_conflicts=None,
features=None,
uninterpreted_option=None,
)
Bases: Message[_MessageOptionsFields]
Attributes:
| Name | Type | Description |
|---|---|---|
message_set_wire_format |
bool
|
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
|
|
deprecated |
bool
|
|
map_entry |
bool
|
Whether the message is an automatically generated map entry type for the maps field. For maps fields:
map 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. |
deprecated_legacy_json_field_conflicts |
bool
|
Enable the legacy handling of JSON field name conflicts. This lowercases
and strips underscored from the fields before comparison in proto3 only.
The new behavior takes This should only be used as a temporary measure against broken builds due to the change in behavior for JSON field name conflicts. TODO This is legacy behavior we plan to remove once downstream teams have had time to migrate. |
features |
FeatureSet | None
|
Any features defined in the specific edition. WARNING: This field should only be used by protobuf plugins or special cases like the proto compiler. Other uses are discouraged and developers should rely on the protoreflect APIs for their client language. |
uninterpreted_option |
list[UninterpretedOption]
|
MethodDescriptorProto
MethodDescriptorProto(
*,
name=None,
input_type=None,
output_type=None,
options=None,
client_streaming=None,
server_streaming=None,
)
MethodOptions
MethodOptions(
*,
deprecated=None,
idempotency_level=None,
features=None,
uninterpreted_option=None,
)
Bases: Message[_MethodOptionsFields]
Attributes:
| Name | Type | Description |
|---|---|---|
deprecated |
bool
|
|
idempotency_level |
IdempotencyLevel
|
|
features |
FeatureSet | None
|
Any features defined in the specific edition. WARNING: This field should only be used by protobuf plugins or special cases like the proto compiler. Other uses are discouraged and developers should rely on the protoreflect APIs for their client language. |
uninterpreted_option |
list[UninterpretedOption]
|
IdempotencyLevel
Bases: 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.
Attributes:
| Name | Type | Description |
|---|---|---|
IDEMPOTENCY_UNKNOWN |
||
NO_SIDE_EFFECTS |
||
IDEMPOTENT |
OneofDescriptorProto
Bases: Message[_OneofDescriptorProtoFields]
Describes a oneof.
Attributes:
| Name | Type | Description |
|---|---|---|
name |
str
|
|
options |
OneofOptions | None
|
OneofOptions
Bases: Message[_OneofOptionsFields]
Attributes:
| Name | Type | Description |
|---|---|---|
features |
FeatureSet | None
|
Any features defined in the specific edition. WARNING: This field should only be used by protobuf plugins or special cases like the proto compiler. Other uses are discouraged and developers should rely on the protoreflect APIs for their client language. |
uninterpreted_option |
list[UninterpretedOption]
|
ServiceDescriptorProto
Bases: Message[_ServiceDescriptorProtoFields]
Describes a service.
Attributes:
| Name | Type | Description |
|---|---|---|
name |
str
|
|
method |
list[MethodDescriptorProto]
|
|
options |
ServiceOptions | None
|
ServiceOptions
Bases: Message[_ServiceOptionsFields]
Attributes:
| Name | Type | Description |
|---|---|---|
features |
FeatureSet | None
|
Any features defined in the specific edition. WARNING: This field should only be used by protobuf plugins or special cases like the proto compiler. Other uses are discouraged and developers should rely on the protoreflect APIs for their client language. |
deprecated |
bool
|
|
uninterpreted_option |
list[UninterpretedOption]
|
SourceCodeInfo
Bases: Message[_SourceCodeInfoFields]
Encapsulates information about the original source file from which a FileDescriptorProto was generated.
Attributes:
| Name | Type | Description |
|---|---|---|
location |
list[Location]
|
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
Location(
*,
path=None,
span=None,
leading_comments=None,
trailing_comments=None,
leading_detached_comments=None,
)
Bases: Message[_LocationFields]
Attributes:
| Name | Type | Description |
|---|---|---|
path |
list[int]
|
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 appears. 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]
|
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
|
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 moo. // // Another line attached to moo. optional double moo = 4; // Detached comment for corge. This is not leading or trailing comments // to moo 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
|
|
leading_detached_comments |
list[str]
|
SymbolVisibility
Bases: Enum
Describes the 'visibility' of a symbol with respect to the proto import
system. Symbols can only be imported when the visibility rules do not prevent
it (ex: local symbols cannot be imported). Visibility modifiers can only set
on message and enum as they are the only types available to be referenced
from other files.
Attributes:
| Name | Type | Description |
|---|---|---|
VISIBILITY_UNSET |
||
VISIBILITY_LOCAL |
||
VISIBILITY_EXPORT |
UninterpretedOption
UninterpretedOption(
*,
name=None,
identifier_value=None,
positive_int_value=None,
negative_int_value=None,
double_value=None,
string_value=None,
aggregate_value=None,
)
Bases: Message[_UninterpretedOptionFields]
A message representing a option the parser does not recognize. This only appears in options protos created by the compiler::Parser class. DescriptorPool resolves these when building Descriptor objects. Therefore, options protos in descriptor objects (e.g. returned by Descriptor::options(), or produced by Descriptor::CopyTo()) will never have UninterpretedOptions in them.
Attributes:
| Name | Type | Description |
|---|---|---|
name |
list[NamePart]
|
|
identifier_value |
str
|
|
positive_int_value |
int
|
|
negative_int_value |
int
|
|
double_value |
float
|
|
string_value |
bytes
|
|
aggregate_value |
str
|
NamePart
Bases: Message[_NamePartFields]
The name of the uninterpreted option. Each string represents a segment in a dot-separated name. is_extension is true iff a segment represents an extension (denoted with parentheses in options specs in .proto files). E.g.,{ ["foo", false], ["bar.baz", true], ["moo", false] } represents "foo.(bar.baz).moo".
Attributes:
| Name | Type | Description |
|---|---|---|
name_part |
str
|
|
is_extension |
bool
|
Duration
Bases: Message[_DurationFields], DurationMixin
A Duration represents a signed, fixed-length span of time represented as a count of seconds and fractions of seconds at nanosecond resolution. It is independent of any calendar and concepts like "day" or "month". It is related to Timestamp in that the difference between two Timestamp values is a Duration and it can be added or subtracted from a Timestamp. Range is approximately +-10,000 years.
Examples
Example 1: Compute Duration from two Timestamps in pseudo code.
Timestamp start = ...;
Timestamp end = ...;
Duration duration = ...;
duration.seconds = end.seconds - start.seconds;
duration.nanos = end.nanos - start.nanos;
if (duration.seconds < 0 && duration.nanos > 0) {
duration.seconds += 1;
duration.nanos -= 1000000000;
} else if (duration.seconds > 0 && duration.nanos < 0) {
duration.seconds -= 1;
duration.nanos += 1000000000;
}
Example 2: Compute Timestamp from Timestamp + Duration in pseudo code.
Timestamp start = ...;
Duration duration = ...;
Timestamp end = ...;
end.seconds = start.seconds + duration.seconds;
end.nanos = start.nanos + duration.nanos;
if (end.nanos < 0) {
end.seconds -= 1;
end.nanos += 1000000000;
} else if (end.nanos >= 1000000000) {
end.seconds += 1;
end.nanos -= 1000000000;
}
Example 3: Compute Duration from datetime.timedelta in Python.
td = datetime.timedelta(days=3, minutes=10)
duration = Duration()
duration.FromTimedelta(td)
JSON Mapping
In JSON format, the Duration type is encoded as a string rather than an object, where the string ends in the suffix "s" (indicating seconds) and is preceded by the number of seconds, with nanoseconds expressed as fractional seconds. For example, 3 seconds with 0 nanoseconds should be encoded in JSON format as "3s", while 3 seconds and 1 nanosecond should be expressed in JSON format as "3.000000001s", and 3 seconds and 1 microsecond should be expressed in JSON format as "3.000001s".
Attributes:
| Name | Type | Description |
|---|---|---|
seconds |
int
|
|
nanos |
int
|
Signed fractions of a second at nanosecond resolution of the span
of time. Durations less than one second are represented with a 0
|
to_nanos
to_seconds
from_seconds
classmethod
Empty
Bases: Message[_EmptyFields]
A generic empty message that you can re-use to avoid defining duplicated empty messages in your APIs. A typical example is to use it as the request or the response type of an API method. For instance:
service Foo {
rpc Bar(google.protobuf.Empty) returns (google.protobuf.Empty);
}
FieldMask
Bases: Message[_FieldMaskFields]
FieldMask represents a set of symbolic field paths, for example:
paths: "f.a"
paths: "f.b.d"
Here f represents a field in some root message, a and b
fields in the message found in f, and d a field found in the
message in f.b.
Field masks are used to specify a subset of fields that should be returned by a get operation or modified by an update operation. Field masks also have a custom JSON encoding (see below).
Field Masks in Projections
When used in the context of a projection, a response message or sub-message is filtered by the API to only contain those fields as specified in the mask. For example, if the mask in the previous example is applied to a response message as follows:
f {
a : 22
b {
d : 1
x : 2
}
y : 13
}
z: 8
The result will not contain specific values for fields x,y and z (their value will be set to the default, and omitted in proto text output):
f {
a : 22
b {
d : 1
}
}
A repeated field is not allowed except at the last position of a paths string.
If a FieldMask object is not present in a get operation, the operation applies to all fields (as if a FieldMask of all fields had been specified).
Note that a field mask does not necessarily apply to the top-level response message. In case of a REST get operation, the field mask applies directly to the response, but in case of a REST list operation, the mask instead applies to each individual message in the returned resource list. In case of a REST custom method, other definitions may be used. Where the mask applies will be clearly documented together with its declaration in the API. In any case, the effect on the returned resource/resources is required behavior for APIs.
Field Masks in Update Operations
A field mask in update operations specifies which fields of the targeted resource are going to be updated. The API is required to only change the values of the fields as specified in the mask and leave the others untouched. If a resource is passed in to describe the updated values, the API ignores the values of all fields not covered by the mask.
If a repeated field is specified for an update operation, new values will
be appended to the existing repeated field in the target resource. Note that
a repeated field is only allowed in the last position of a paths string.
If a sub-message is specified in the last position of the field mask for an update operation, then new value will be merged into the existing sub-message in the target resource.
For example, given the target message:
f {
b {
d: 1
x: 2
}
c: [1]
}
And an update message:
f {
b {
d: 10
}
c: [2]
}
then if the field mask is:
paths: ["f.b", "f.c"]
then the result will be:
f {
b {
d: 10
x: 2
}
c: [1, 2]
}
An implementation may provide options to override this default behavior for repeated and message fields.
Note that libraries which implement FieldMask resolution have various different behaviors in the face of empty masks or the special "*" mask. When implementing a service you should confirm these cases have the appropriate behavior in the underlying FieldMask library that you desire, and you may need to special case those cases in your application code if the underlying field mask library behavior differs from your intended service semantics.
Update methods implementing https://google.aip.dev/134 - MUST support the special value * meaning "full replace" - MUST treat an omitted field mask as "replace fields which are present".
Other methods implementing https://google.aip.dev/157 - SHOULD support the special value "*" to mean "get all". - MUST treat an omitted field mask to mean "get all", unless otherwise documented.
Considerations for HTTP REST
The HTTP kind of an update operation which uses a field mask must be set to PATCH instead of PUT in order to satisfy HTTP semantics (PUT must only be used for full updates).
JSON Encoding of Field Masks
In JSON, a field mask is encoded as a single string where paths are separated by a comma. Fields name in each path are converted to/from lower-camel naming conventions.
As an example, consider the following message declarations:
message Profile {
User user = 1;
Photo photo = 2;
}
message User {
string display_name = 1;
string address = 2;
}
In proto a field mask for Profile may look as such:
mask {
paths: "user.display_name"
paths: "photo"
}
In JSON, the same mask is represented as below:
{
mask: "user.displayName,photo"
}
Field Masks and Oneof Fields
Field masks treat fields in oneofs just as regular fields. Consider the following message:
message SampleMessage {
oneof test_oneof {
string name = 4;
SubMessage sub_message = 9;
}
}
The field mask can be:
mask {
paths: "name"
}
Or:
mask {
paths: "sub_message"
}
Note that oneof type names ("test_oneof" in this case) cannot be used in paths.
Field Mask Verification
The implementation of any API method which has a FieldMask type field in the
request should verify the included field paths, and return an
INVALID_ARGUMENT error if any path is unmappable.
Attributes:
| Name | Type | Description |
|---|---|---|
paths |
list[str]
|
GoFeatures
GoFeatures(
*,
legacy_unmarshal_json_enum=None,
api_level=None,
strip_enum_prefix=None,
optimize_mode=None,
)
Bases: Message[_GoFeaturesFields]
Attributes:
| Name | Type | Description |
|---|---|---|
legacy_unmarshal_json_enum |
bool
|
|
api_level |
APILevel
|
|
strip_enum_prefix |
StripEnumPrefix
|
|
optimize_mode |
OptimizeMode
|
OptimizeModeFeature
Bases: Message[_OptimizeModeFeatureFields]
Wrap the OptimizeMode enum in a message for scoping: This way, users can type shorter names (SPEED, CODE_SIZE).
OptimizeMode
Bases: Enum
The name of this enum matches OptimizeMode in descriptor.proto.
Attributes:
| Name | Type | Description |
|---|---|---|
UNSPECIFIED |
||
SPEED |
||
CODE_SIZE |
APILevel
StripEnumPrefix
JavaFeatures
JavaFeatures(
*,
legacy_closed_enum=None,
utf8_validation=None,
large_enum=None,
use_old_outer_classname_default=None,
nest_in_file_class=None,
)
Bases: Message[_JavaFeaturesFields]
Attributes:
| Name | Type | Description |
|---|---|---|
legacy_closed_enum |
bool
|
|
utf8_validation |
Utf8Validation
|
|
large_enum |
bool
|
|
use_old_outer_classname_default |
bool
|
Whether to use the old default outer class name scheme, or the new feature which adds a "Proto" suffix to the outer class name. Users will not be able to set this option, because we removed it in the same edition that it was introduced. But we use it to determine which naming scheme to use for outer class name defaults. |
nest_in_file_class |
NestInFileClass
|
SourceContext
ListValue
NullValue
Bases: Enum
Represents a JSON null.
NullValue is a sentinel, using an enum with only one value to represent
the null value for the Value type union.
A field of type NullValue with any value other than 0 is considered
invalid. Most ProtoJSON serializers will emit a Value with a null_value set
as a JSON null regardless of the integer value, and so will round trip to
a 0 value.
Attributes:
| Name | Type | Description |
|---|---|---|
NULL_VALUE |
Struct
Bases: Message[_StructFields], StructMixin
Represents a JSON object.
An unordered key-value map, intending to perfectly capture the semantics of a JSON object. This enables parsing any arbitrary JSON payload as a message field in ProtoJSON format.
This follows RFC 8259 guidelines for interoperable JSON: notably this type
cannot represent large Int64 values or NaN/Infinity numbers,
since the JSON format generally does not support those values in its number
type.
If you do not intend to parse arbitrary JSON into your message, a custom typed message should be preferred instead of using this type.
Attributes:
| Name | Type | Description |
|---|---|---|
fields |
dict[str, Value]
|
from_python
classmethod
to_python
Convert this Struct to a Python dict.
Examples:
Value
Bases: Message[_ValueFields], ValueMixin
Represents a JSON value.
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 these
variants. Absence of any variant is an invalid state.
Attributes:
| Name | Type | Description |
|---|---|---|
kind |
Oneof[Literal['null_value'], NullValue] | Oneof[Literal['number_value'], float] | Oneof[Literal['string_value'], str] | Oneof[Literal['bool_value'], bool] | Oneof[Literal['struct_value'], Struct] | Oneof[Literal['list_value'], ListValue] | None
|
from_python
classmethod
Create a Value from a Python value.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
value
|
ValueTypeParam
|
The Python value to convert. |
required |
Returns:
| Type | Description |
|---|---|
SelfValue
|
A Value representing the given Python value. |
Raises:
| Type | Description |
|---|---|
TypeError
|
If the value is of an unsupported type, including |
Examples:
>>> from protobuf.wkt import Value
>>> Value.from_python(None)
Value(kind=Oneof(field='null_value', value=NullValue.NULL_VALUE))
>>> Value.from_python(True)
Value(kind=Oneof(field='bool_value', value=True))
>>> Value.from_python(2)
Value(kind=Oneof(field='number_value', value=2.0))
>>> Value.from_python(3.14)
Value(kind=Oneof(field='number_value', value=3.14))
>>> Value.from_python("hello")
Value(kind=Oneof(field='string_value', value='hello'))
>>> Value.from_python([1, "foo"])
Value(kind=Oneof(field='list_value', value=ListValue(values=[Value(kind=Oneof(field='number_value', value=1.0)), Value(kind=Oneof(field='string_value', value='foo'))])))
>>> Value.from_python({"a": 1, "b": "bear"})
Value(kind=Oneof(field='struct_value', value=Struct(fields={'a': Value(kind=Oneof(field='number_value', value=1.0)), 'b': Value(kind=Oneof(field='string_value', value='bear'))})))
to_python
Convert this Value to a Python value.
Examples:
>>> from protobuf import Oneof
>>> from protobuf.wkt import ListValue, NullValue, Struct, Value
>>> Value(
... kind=Oneof(field="null_value", value=NullValue.NULL_VALUE)
... ).to_python()
>>> Value(kind=Oneof(field="bool_value", value=True)).to_python()
True
>>> Value(kind=Oneof(field="number_value", value=3.14)).to_python()
3.14
>>> Value(kind=Oneof(field="string_value", value="hello")).to_python()
'hello'
>>> Value(
... kind=Oneof(
... field="list_value",
... value=ListValue(
... values=[
... Value(kind=Oneof(field="number_value", value=1.0)),
... Value(kind=Oneof(field="string_value", value="foo")),
... ]
... ),
... )
... ).to_python()
[1.0, 'foo']
>>> Value(
... kind=Oneof(
... field="struct_value",
... value=Struct(
... fields={
... "a": Value(kind=Oneof(field="number_value", value=1.0)),
... "b": Value(
... kind=Oneof(field="string_value", value="bear")
... ),
... }
... ),
... )
... ).to_python()
{'a': 1.0, 'b': 'bear'}
Timestamp
Bases: Message[_TimestampFields], TimestampMixin
A Timestamp represents a point in time independent of any time zone or local calendar, encoded as a count of seconds and fractions of seconds at nanosecond resolution. The count is relative to an epoch at UTC midnight on January 1, 1970, in the proleptic Gregorian calendar which extends the Gregorian calendar backwards to year one.
All minutes are 60 seconds long. Leap seconds are "smeared" so that no leap second table is needed for interpretation, using a 24-hour linear smear.
The range is from 0001-01-01T00:00:00Z to 9999-12-31T23:59:59.999999999Z. By restricting to that range, we ensure that we can convert to and from RFC 3339 date strings.
Examples
Example 1: Compute Timestamp from POSIX time().
Timestamp timestamp;
timestamp.set_seconds(time(NULL));
timestamp.set_nanos(0);
Example 2: Compute Timestamp from POSIX gettimeofday().
struct timeval tv;
gettimeofday(&tv, NULL);
Timestamp timestamp;
timestamp.set_seconds(tv.tv_sec);
timestamp.set_nanos(tv.tv_usec * 1000);
Example 3: Compute Timestamp from Win32 GetSystemTimeAsFileTime().
FILETIME ft;
GetSystemTimeAsFileTime(&ft);
UINT64 ticks = (((UINT64)ft.dwHighDateTime) << 32) | ft.dwLowDateTime;
// A Windows tick is 100 nanoseconds. Windows epoch 1601-01-01T00:00:00Z
// is 11644473600 seconds before Unix epoch 1970-01-01T00:00:00Z.
Timestamp timestamp;
timestamp.set_seconds((INT64) ((ticks / 10000000) - 11644473600LL));
timestamp.set_nanos((INT32) ((ticks % 10000000) * 100));
Example 4: Compute Timestamp from Java System.currentTimeMillis().
long millis = System.currentTimeMillis();
Timestamp timestamp = Timestamp.newBuilder().setSeconds(millis / 1000)
.setNanos((int) ((millis % 1000) * 1000000)).build();
Example 5: Compute Timestamp from Java Instant.now().
Instant now = Instant.now();
Timestamp timestamp =
Timestamp.newBuilder().setSeconds(now.getEpochSecond())
.setNanos(now.getNano()).build();
Example 6: Compute Timestamp from current time in Python.
timestamp = Timestamp()
timestamp.GetCurrentTime()
JSON Mapping
In JSON format, the Timestamp type is encoded as a string in the RFC 3339 format. That is, the format is "{year}-{month}-{day}T{hour}:{min}:{sec}[.{frac_sec}]Z" where {year} is always expressed using four digits while {month}, {day}, {hour}, {min}, and {sec} are zero-padded to two digits each. The fractional seconds, which can go up to 9 digits (i.e. up to 1 nanosecond resolution), are optional. The "Z" suffix indicates the timezone ("UTC"); the timezone is required. A ProtoJSON serializer should always use UTC (as indicated by "Z") when printing the Timestamp type and a ProtoJSON parser should be able to accept both UTC and other timezones (as indicated by an offset).
For example, "2017-01-15T01:30:15.01Z" encodes 15.01 seconds past 01:30 UTC on January 15, 2017.
In JavaScript, one can convert a Date object to this format using the
standard
toISOString()
method. In Python, a standard datetime.datetime object can be converted
to this format using
strftime with
the time format spec '%Y-%m-%dT%H:%M:%S.%fZ'. Likewise, in Java, one can use
the Joda Time's ISODateTimeFormat.dateTime() to obtain a formatter capable of generating timestamps in this format.
Attributes:
| Name | Type | Description |
|---|---|---|
seconds |
int
|
|
nanos |
int
|
Non-negative fractions of a second at nanosecond resolution. This field is the nanosecond portion of the duration, not an alternative to seconds. Negative second values with fractions must still have non-negative nanos values that count forward in time. Must be between 0 and 999,999,999 inclusive. |
to_nanos
to_seconds
Convert to a number of seconds since Unix epoch 1970-01-01T00:00:00Z.
Parts of a second are expressed as fractional values.
Examples:
from_seconds
classmethod
Create a new Timestamp from a timestamp expressed in seconds since Unix epoch 1970-01-01T00:00:00Z.
Parts of a second are expressed as fractional values.
Examples:
Enum
Bases: Message[_EnumFields]
Enum type definition.
New usages of this message as an alternative to EnumDescriptorProto are strongly discouraged. This message does not reliability preserve all information necessary to model the schema and preserve semantics. Instead make use of FileDescriptorSet which preserves the necessary information.
Attributes:
| Name | Type | Description |
|---|---|---|
name |
str
|
|
enumvalue |
list[EnumValue]
|
|
options |
list[Option]
|
|
source_context |
SourceContext | None
|
|
syntax |
Syntax
|
|
edition |
str
|
EnumValue
Bases: Message[_EnumValueFields]
Enum value definition.
New usages of this message as an alternative to EnumValueDescriptorProto are strongly discouraged. This message does not reliability preserve all information necessary to model the schema and preserve semantics. Instead make use of FileDescriptorSet which preserves the necessary information.
Attributes:
| Name | Type | Description |
|---|---|---|
name |
str
|
|
number |
int
|
|
options |
list[Option]
|
Field
Field(
*,
kind=None,
cardinality=None,
number=0,
name="",
type_url="",
oneof_index=0,
packed=False,
options=None,
json_name="",
default_value="",
)
Bases: Message[_FieldFields]
A single field of a message type.
New usages of this message as an alternative to FieldDescriptorProto are strongly discouraged. This message does not reliability preserve all information necessary to model the schema and preserve semantics. Instead make use of FileDescriptorSet which preserves the necessary information.
Attributes:
| Name | Type | Description |
|---|---|---|
kind |
Kind
|
|
cardinality |
Cardinality
|
|
number |
int
|
|
name |
str
|
|
type_url |
str
|
|
oneof_index |
int
|
|
packed |
bool
|
|
options |
list[Option]
|
|
json_name |
str
|
|
default_value |
str
|
Kind
Bases: Enum
Basic field types.
Attributes:
| Name | Type | Description |
|---|---|---|
TYPE_UNKNOWN |
||
TYPE_DOUBLE |
||
TYPE_FLOAT |
||
TYPE_INT64 |
||
TYPE_UINT64 |
||
TYPE_INT32 |
||
TYPE_FIXED64 |
||
TYPE_FIXED32 |
||
TYPE_BOOL |
||
TYPE_STRING |
||
TYPE_GROUP |
||
TYPE_MESSAGE |
||
TYPE_BYTES |
||
TYPE_UINT32 |
||
TYPE_ENUM |
||
TYPE_SFIXED32 |
||
TYPE_SFIXED64 |
||
TYPE_SINT32 |
||
TYPE_SINT64 |
Cardinality
Bases: Enum
Whether a field is optional, required, or repeated.
Attributes:
| Name | Type | Description |
|---|---|---|
UNKNOWN |
||
OPTIONAL |
||
REQUIRED |
||
REPEATED |
Option
Bases: Message[_OptionFields]
A protocol buffer option, which can be attached to a message, field, enumeration, etc.
New usages of this message as an alternative to FileOptions, MessageOptions, FieldOptions, EnumOptions, EnumValueOptions, ServiceOptions, or MethodOptions are strongly discouraged.
Attributes:
| Name | Type | Description |
|---|---|---|
name |
str
|
|
value |
Any | None
|
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. |
Syntax
Bases: Enum
The syntax in which a protocol buffer element is defined.
Attributes:
| Name | Type | Description |
|---|---|---|
PROTO2 |
||
PROTO3 |
||
EDITIONS |
Type
Type(
*,
name="",
fields=None,
oneofs=None,
options=None,
source_context=None,
syntax=None,
edition="",
)
Bases: Message[_TypeFields]
A protocol buffer message type.
New usages of this message as an alternative to DescriptorProto are strongly discouraged. This message does not reliability preserve all information necessary to model the schema and preserve semantics. Instead make use of FileDescriptorSet which preserves the necessary information.
Attributes:
| Name | Type | Description |
|---|---|---|
name |
str
|
|
fields |
list[Field]
|
|
oneofs |
list[str]
|
|
options |
list[Option]
|
|
source_context |
SourceContext | None
|
|
syntax |
Syntax
|
|
edition |
str
|