@@ -78,13 +78,18 @@ protobuf extensions
78
78
are involved, a well-known pitfall is that extensions are silently moved
79
79
to the ` proto2::UnknownFieldSet ` when a message is deserialized in C++,
80
80
but the ` cc_proto_library ` for the extensions is not linked in. The root
81
- cause is an asymmetry in the handling of Python protos vs C++ protos: when
82
- a Python proto is deserialized, both the Python descriptor pool and the C++
83
- descriptor pool are inspected, but when a C++ proto is deserialized, only
81
+ cause is an asymmetry in the handling of Python protos vs C++
82
+ protos:
83
+ when a Python proto is deserialized, both the Python descriptor pool and the
84
+ C++ descriptor pool are inspected, but when a C++ proto is deserialized, only
84
85
the C++ descriptor pool is inspected. Until this asymmetry is resolved, the
85
86
` cc_proto_library ` for all extensions involved must be added to the ` deps ` of
86
- the relevant ` pybind_library ` or ` pybind_extension ` , but this is sufficiently
87
- unobvious to be a setup for regular accidents, potentially with critical
87
+ the relevant ` pybind_library ` or ` pybind_extension ` , or if this is impractial,
88
+ ` pybind11_protobuf::check_unknown_fields::ExtensionsWithUnknownFieldsPolicy::WeakEnableFallbackToSerializeParse `
89
+ or ` pybind11_protobuf::AllowUnknownFieldsFor ` can be used.
90
+
91
+ The pitfall is sufficiently unobvious to be a setup for regular accidents,
92
+ potentially with critical
88
93
consequences.
89
94
90
95
To guard against the most common type of accident, native_proto_caster.h
@@ -97,14 +102,20 @@ in certain situations:
97
102
* and the ` proto2::UnknownFieldSet ` for the message or any of its submessages
98
103
is not empty.
99
104
100
- ` pybind11_protobuf::AllowUnknownFieldsFor ` is an escape hatch for situations in
101
- which
105
+ ` pybind11_protobuf::check_unknown_fields::ExtensionsWithUnknownFieldsPolicy::WeakEnableFallbackToSerializeParse `
106
+ is a ** global** escape hatch trading off convenience and runtime overhead: the
107
+ convenience is that it is not necessary to determine what ` cc_proto_library `
108
+ dependencies need to be added, the runtime overhead is that
109
+ ` SerializePartialToString ` /` ParseFromString ` is used for messages with unknown
110
+ fields, instead of the much faster ` CopyFrom ` .
102
111
103
- * unknown fields existed before the safety mechanism was
104
- introduced.
105
- * unknown fields are needed in the future.
112
+ Another escape hatch is ` pybind11_protobuf::AllowUnknownFieldsFor ` , which
113
+ simply disables the safety mechanism for ** specific message types** , without
114
+ a runtime overhead. This is useful for situations in which unknown fields
115
+ are acceptable.
106
116
107
- An example of a full error message (with lines breaks here for readability):
117
+ An example of a full error message generated by the safety mechanism
118
+ (with lines breaks here for readability):
108
119
109
120
```
110
121
Proto Message of type pybind11.test.NestRepeated has an Unknown Field with
@@ -117,14 +128,13 @@ Only if there is no alternative to suppressing this error, use
117
128
(Warning: suppressions may mask critical bugs.)
118
129
```
119
130
120
- The current implementation is a compromise solution, trading off simplicity
121
- of implementation, runtime performance, and precision. Generally, the runtime
122
- overhead is expected to be very small, but fields flagged as unknown may not
123
- necessarily be in extensions.
124
- Alerting developers of new code to unknown fields is assumed to be generally
125
- helpful, but the unknown fields detection is limited to messages with
126
- extensions, to avoid the runtime overhead for the presumably much more common
127
- case that no extensions are involved.
131
+ Note that the current implementation of the safety mechanism is a compromise
132
+ solution, trading off simplicity of implementation, runtime performance,
133
+ and precision. Alerting developers of new code to unknown fields is assumed
134
+ to be generally helpful, but the unknown fields detection is limited to
135
+ messages with extensions, to avoid the runtime overhead for the presumably
136
+ much more common case that no extensions are involved. Because of this,
137
+ the runtime overhead for the safety mechanism is expected to be very small.
128
138
129
139
### Enumerations
130
140
0 commit comments