@@ -46,126 +46,72 @@ class Any(google.protobuf.message.Message, google.protobuf.internal.well_known_t
4646 """`Any` contains an arbitrary serialized protocol buffer message along with a
4747 URL that describes the type of the serialized message.
4848
49- Protobuf library provides support to pack/unpack Any values in the form
50- of utility functions or additional generated methods of the Any type.
51-
52- Example 1: Pack and unpack a message in C++.
53-
54- Foo foo = ...;
55- Any any;
56- any.PackFrom(foo);
57- ...
58- if (any.UnpackTo(&foo)) {
59- ...
60- }
61-
62- Example 2: Pack and unpack a message in Java.
63-
64- Foo foo = ...;
65- Any any = Any.pack(foo);
66- ...
67- if (any.is(Foo.class)) {
68- foo = any.unpack(Foo.class);
69- }
70- // or ...
71- if (any.isSameTypeAs(Foo.getDefaultInstance())) {
72- foo = any.unpack(Foo.getDefaultInstance());
73- }
74-
75- Example 3: Pack and unpack a message in Python.
76-
77- foo = Foo(...)
78- any = Any()
79- any.Pack(foo)
80- ...
81- if any.Is(Foo.DESCRIPTOR):
82- any.Unpack(foo)
83- ...
84-
85- Example 4: Pack and unpack a message in Go
86-
87- foo := &pb.Foo{...}
88- any, err := anypb.New(foo)
89- if err != nil {
90- ...
91- }
92- ...
93- foo := &pb.Foo{}
94- if err := any.UnmarshalTo(foo); err != nil {
95- ...
96- }
97-
98- The pack methods provided by protobuf library will by default use
99- 'type.googleapis.com/full.type.name' as the type URL and the unpack
100- methods only use the fully qualified type name after the last '/'
101- in the type URL, for example "foo.bar.com/x/y.z" will yield type
102- name "y.z".
103-
104- JSON
105- ====
106- The JSON representation of an `Any` value uses the regular
107- representation of the deserialized, embedded message, with an
108- additional field `@type` which contains the type URL. Example:
109-
110- package google.profile;
111- message Person {
112- string first_name = 1;
113- string last_name = 2;
114- }
115-
116- {
117- "@type": "type.googleapis.com/google.profile.Person",
118- "firstName": <string>,
119- "lastName": <string>
120- }
121-
122- If the embedded message type is well-known and has a custom JSON
123- representation, that representation will be embedded adding a field
124- `value` which holds the custom JSON in addition to the `@type`
125- field. Example (for message [google.protobuf.Duration][]):
126-
127- {
128- "@type": "type.googleapis.com/google.protobuf.Duration",
129- "value": "1.212s"
130- }
49+ In its binary encoding, an `Any` is an ordinary message; but in other wire
50+ forms like JSON, it has a special encoding. The format of the type URL is
51+ described on the `type_url` field.
52+
53+ Protobuf APIs provide utilities to interact with `Any` values:
54+
55+ - A 'pack' operation accepts a message and constructs a generic `Any` wrapper
56+ around it.
57+ - An 'unpack' operation reads the content of an `Any` message, either into an
58+ existing message or a new one. Unpack operations must check the type of the
59+ value they unpack against the declared `type_url`.
60+ - An 'is' operation decides whether an `Any` contains a message of the given
61+ type, i.e. whether it can 'unpack' that type.
62+
63+ The JSON format representation of an `Any` follows one of these cases:
64+
65+ - For types without special-cased JSON encodings, the JSON format
66+ representation of the `Any` is the same as that of the message, with an
67+ additional `@type` field which contains the type URL.
68+ - For types with special-cased JSON encodings (typically called 'well-known'
69+ types, listed in https://protobuf.dev/programming-guides/json/#any), the
70+ JSON format representation has a key `@type` which contains the type URL
71+ and a key `value` which contains the JSON-serialized value.
72+
73+ The text format representation of an `Any` is like a message with one field
74+ whose name is the type URL in brackets. For example, an `Any` containing a
75+ `foo.Bar` message may be written `[type.googleapis.com/foo.Bar] { a: 2 }`.
13176 """
13277
13378 DESCRIPTOR : google .protobuf .descriptor .Descriptor
13479
13580 TYPE_URL_FIELD_NUMBER : builtins .int
13681 VALUE_FIELD_NUMBER : builtins .int
13782 type_url : builtins .str
138- """A URL/resource name that uniquely identifies the type of the serialized
139- protocol buffer message. This string must contain at least
140- one "/" character. The last segment of the URL's path must represent
141- the fully qualified name of the type (as in
142- `path/google.protobuf.Duration`). The name should be in a canonical form
143- (e.g., leading "." is not accepted).
144-
145- In practice, teams usually precompile into the binary all types that they
146- expect it to use in the context of Any. However, for URLs which use the
147- scheme `http`, `https`, or no scheme, one can optionally set up a type
148- server that maps type URLs to message definitions as follows:
149-
150- * If no scheme is provided, `https` is assumed.
151- * An HTTP GET on the URL must yield a [google.protobuf.Type][]
152- value in binary format, or produce an error.
153- * Applications are allowed to cache lookup results based on the
154- URL, or have them precompiled into a binary to avoid any
155- lookup. Therefore, binary compatibility needs to be preserved
156- on changes to types. (Use versioned type names to manage
157- breaking changes.)
158-
159- Note: this functionality is not currently available in the official
160- protobuf release, and it is not used for type URLs beginning with
161- type.googleapis.com. As of May 2023, there are no widely used type server
162- implementations and no plans to implement one.
163-
164- Schemes other than `http`, `https` (or the empty scheme) might be
165- used with implementation specific semantics.
83+ """Identifies the type of the serialized Protobuf message with a URI reference
84+ consisting of a prefix ending in a slash and the fully-qualified type name.
85+
86+ Example: type.googleapis.com/google.protobuf.StringValue
87+
88+ This string must contain at least one `/` character, and the content after
89+ the last `/` must be the fully-qualified name of the type in canonical
90+ form, without a leading dot. Do not write a scheme on these URI references
91+ so that clients do not attempt to contact them.
92+
93+ The prefix is arbitrary and Protobuf implementations are expected to
94+ simply strip off everything up to and including the last `/` to identify
95+ the type. `type.googleapis.com/` is a common default prefix that some
96+ legacy implementations require. This prefix does not indicate the origin of
97+ the type, and URIs containing it are not expected to respond to any
98+ requests.
99+
100+ All type URL strings must be legal URI references with the additional
101+ restriction (for the text format) that the content of the reference
102+ must consist only of alphanumeric characters, percent-encoded escapes, and
103+ characters in the following set (not including the outer backticks):
104+ `/-.~_!$&()*+,;=`. Despite our allowing percent encodings, implementations
105+ should not unescape them to prevent confusion with existing parsers. For
106+ example, `type.googleapis.com%2FFoo` should be rejected.
107+
108+ In the original design of `Any`, the possibility of launching a type
109+ resolution service at these type URLs was considered but Protobuf never
110+ implemented one and considers contacting these URLs to be problematic and
111+ a potential security issue. Do not attempt to contact type URLs.
166112 """
167113 value : builtins .bytes
168- """Must be a valid serialized protocol buffer of the above specified type ."""
114+ """Holds a Protobuf serialization of the type described by type_url ."""
169115 def __init__ (self , * , type_url : builtins .str | None = ..., value : builtins .bytes | None = ...) -> None : ...
170116 def ClearField (self , field_name : typing .Literal ["type_url" , b"type_url" , "value" , b"value" ]) -> None : ...
171117
0 commit comments