Pull comments from deprecation option for warning details

Signed-off-by: Aidan Jensen <[email protected]>

Author: Aidan Jensen

README.md

@@ -219,6 +219,16 @@ However, it may be helpful when migrating existing proto2 code, where the distin
 protoc --python_out=output/location --mypy_out=relax_strict_optional_primitives:output/location
 ```
 
+### `use_default_deprecation_warnings`
+
+By default mypy-protobuf will pull the leading and trailing comments from the deprecation option definition,
+and insert it into the deprecation warning. This option will instead use a standard deprecation warning instead of comments.
+
+```
+protoc --python_out=output/location --mypy_out=use_default_deprecation_warning:output/location
+
+```
+
 ### Output suppression
 
 To suppress output, you can run

mypy_protobuf/main.py

@@ -149,12 +149,14 @@ def __init__(
         descriptors: Descriptors,
         readable_stubs: bool,
         relax_strict_optional_primitives: bool,
+        use_default_deprecation_warnings: bool,
         grpc: bool,
     ) -> None:
         self.fd = fd
         self.descriptors = descriptors
         self.readable_stubs = readable_stubs
         self.relax_strict_optional_primitives = relax_strict_optional_primitives
+        self.use_default_depreaction_warnings = use_default_deprecation_warnings
         self.grpc = grpc
         self.lines: List[str] = []
         self.indent = ""
@@ -257,6 +259,47 @@ def _has_comments(self, scl: SourceCodeLocation) -> bool:
         sci_loc = self.source_code_info_by_scl.get(tuple(scl))
         return sci_loc is not None and bool(sci_loc.leading_detached_comments or sci_loc.leading_comments or sci_loc.trailing_comments)
 
+    def _get_comments(self, scl: SourceCodeLocation) -> List[str]:
+        """Return list of comment lines"""
+        if not self._has_comments(scl):
+            return []
+
+        sci_loc = self.source_code_info_by_scl.get(tuple(scl))
+        assert sci_loc is not None
+
+        leading_detached_lines = []
+        leading_lines = []
+        trailing_lines = []
+        for leading_detached_comment in sci_loc.leading_detached_comments:
+            leading_detached_lines = self._break_text(leading_detached_comment)
+        if sci_loc.leading_comments is not None:
+            leading_lines = self._break_text(sci_loc.leading_comments)
+        # Trailing comments also go in the header - to make sure it gets into the docstring
+        if sci_loc.trailing_comments is not None:
+            trailing_lines = self._break_text(sci_loc.trailing_comments)
+
+        lines = leading_detached_lines
+        if leading_detached_lines and (leading_lines or trailing_lines):
+            lines.append("")
+        lines.extend(leading_lines)
+        lines.extend(trailing_lines)
+
+        return lines
+
+    def _write_deprecation_warning(self, scl: SourceCodeLocation, default_message: str) -> None:
+        if not self.use_default_depreaction_warnings and (comments := self._get_comments(scl)):
+            self._write_line(
+                '@{}("""{}""")',
+                self._import("warnings", "deprecated"),
+                "\\n".join(comments),
+            )
+        else:
+            self._write_line(
+                '@{}("{}")',
+                self._import("warnings", "deprecated"),
+                default_message,
+            )
+
     def _write_comments(self, scl: SourceCodeLocation) -> bool:
         """Return true if any comments were written"""
         if not self._has_comments(scl):
@@ -371,9 +414,8 @@ def write_enums(
             wl("")
 
             if enum.options.deprecated:
-                wl(
-                    '@{}("{}")',
-                    self._import("warnings", "deprecated"),
+                self._write_deprecation_warning(
+                    scl + [d.EnumDescriptorProto.OPTIONS_FIELD_NUMBER] + [d.EnumOptions.DEPRECATED_FIELD_NUMBER],
                     "This enum has been marked as deprecated using proto enum options.",
                 )
             if self._has_comments(scl):
@@ -422,9 +464,8 @@ def write_messages(
             class_name = desc.name if desc.name not in PYTHON_RESERVED else "_r_" + desc.name
             message_class = self._import("google.protobuf.message", "Message")
             if desc.options.deprecated:
-                wl(
-                    '@{}("{}")',
-                    self._import("warnings", "deprecated"),
+                self._write_deprecation_warning(
+                    scl_prefix + [i] + [d.DescriptorProto.OPTIONS_FIELD_NUMBER] + [d.MessageOptions.DEPRECATED_FIELD_NUMBER],
                     "This message has been marked as deprecated using proto message options.",
                 )
             wl("@{}", self._import("typing", "final"))
@@ -854,9 +895,8 @@ def write_grpc_services(
 
             # The stub client
             if service.options.deprecated:
-                wl(
-                    '@{}("{}")',
-                    self._import("warnings", "deprecated"),
+                self._write_deprecation_warning(
+                    scl + [d.ServiceDescriptorProto.OPTIONS_FIELD_NUMBER] + [d.ServiceOptions.DEPRECATED_FIELD_NUMBER],
                     "This stub has been marked as deprecated using proto service options.",
                 )
             class_name = f"{service.name}Stub"
@@ -900,9 +940,8 @@ def write_grpc_services(
 
             # The service definition interface
             if service.options.deprecated:
-                wl(
-                    '@{}("{}")',
-                    self._import("warnings", "deprecated"),
+                self._write_deprecation_warning(
+                    scl + [d.ServiceDescriptorProto.OPTIONS_FIELD_NUMBER] + [d.ServiceOptions.DEPRECATED_FIELD_NUMBER],
                     "This servicer has been marked as deprecated using proto service options.",
                 )
             wl(
@@ -917,9 +956,8 @@ def write_grpc_services(
             server = self._import("grpc", "Server")
             aserver = self._import("grpc.aio", "Server")
             if service.options.deprecated:
-                wl(
-                    '@{}("{}")',
-                    self._import("warnings", "deprecated"),
+                self._write_deprecation_warning(
+                    scl + [d.ServiceDescriptorProto.OPTIONS_FIELD_NUMBER] + [d.ServiceOptions.DEPRECATED_FIELD_NUMBER],
                     "This servicer has been marked as deprecated using proto service options.",
                 )
             wl(
@@ -1083,13 +1121,15 @@ def generate_mypy_stubs(
     quiet: bool,
     readable_stubs: bool,
     relax_strict_optional_primitives: bool,
+    use_default_deprecation_warnings: bool,
 ) -> None:
     for name, fd in descriptors.to_generate.items():
         pkg_writer = PkgWriter(
             fd,
             descriptors,
             readable_stubs,
             relax_strict_optional_primitives,
+            use_default_deprecation_warnings,
             grpc=False,
         )
 
@@ -1115,13 +1155,15 @@ def generate_mypy_grpc_stubs(
     quiet: bool,
     readable_stubs: bool,
     relax_strict_optional_primitives: bool,
+    use_default_deprecation_warnings: bool,
 ) -> None:
     for name, fd in descriptors.to_generate.items():
         pkg_writer = PkgWriter(
             fd,
             descriptors,
             readable_stubs,
             relax_strict_optional_primitives,
+            use_default_deprecation_warnings,
             grpc=True,
         )
         pkg_writer.write_grpc_async_hacks()
@@ -1173,6 +1215,7 @@ def main() -> None:
             "quiet" in request.parameter,
             "readable_stubs" in request.parameter,
             "relax_strict_optional_primitives" in request.parameter,
+            "use_default_deprecation_warnings" in request.parameter,
         )
 
 
@@ -1185,6 +1228,7 @@ def grpc() -> None:
             "quiet" in request.parameter,
             "readable_stubs" in request.parameter,
             "relax_strict_optional_primitives" in request.parameter,
+            "use_default_deprecation_warnings" in request.parameter,
         )
 
 

proto/testproto/grpc/dummy.proto

@@ -30,6 +30,7 @@ message DeprecatedRequest {
 
 // Marking the service as deprecated
 service DeprecatedService {
+  // This service is deprecated
   option deprecated = true;
   // DeprecatedMethod
   rpc DeprecatedMethod (DeprecatedRequest) returns (DummyReply) {

proto/testproto/test.proto

@@ -190,7 +190,11 @@ message DeprecatedMessage {
 
 enum DeprecatedEnum {
     // This enum is deprecated
+    // 2 lines of comments
+    // "Quotes in comments"
+    // and 'single quotes'
     option deprecated = true;
+    // Trailing comment
 
     DEPRECATED_ONE = 1;
     DEPRECATED_TWO = 2;

run_test.sh

@@ -130,6 +130,7 @@ MYPY_PROTOBUF_VENV=venv_$PY_VER_MYPY_PROTOBUF
     find proto -name "*.proto" -print0 | xargs -0 "$PROTOC" "${PROTOC_ARGS[@]}" --mypy_out=quiet:test/generated
     find proto -name "*.proto" -print0 | xargs -0 "$PROTOC" "${PROTOC_ARGS[@]}" --mypy_out=readable_stubs:test/generated
     find proto -name "*.proto" -print0 | xargs -0 "$PROTOC" "${PROTOC_ARGS[@]}" --mypy_out=relax_strict_optional_primitives:test/generated
+    find proto -name "*.proto" -print0 | xargs -0 "$PROTOC" "${PROTOC_ARGS[@]}" --mypy_out=use_default_deprecation_warnings:test/generated
     # Overwrite w/ run with mypy-protobuf without flags
     find proto -name "*.proto" -print0 | xargs -0 "$PROTOC" "${PROTOC_ARGS[@]}" --mypy_out=test/generated
 

test/generated/testproto/grpc/dummy_pb2_grpc.pyi

@@ -237,7 +237,7 @@ _DeprecatedServiceDeprecatedMethodNotDeprecatedRequestType = typing_extensions.T
     ],
 )
 
-@deprecated("This stub has been marked as deprecated using proto service options.")
+@deprecated("""This service is deprecated""")
 class DeprecatedServiceStub(typing.Generic[_DeprecatedServiceDeprecatedMethodType, _DeprecatedServiceDeprecatedMethodNotDeprecatedRequestType]):
     """Marking the service as deprecated"""
 
@@ -282,7 +282,7 @@ DeprecatedServiceAsyncStub: typing_extensions.TypeAlias = DeprecatedServiceStub[
     ],
 ]
 
-@deprecated("This servicer has been marked as deprecated using proto service options.")
+@deprecated("""This service is deprecated""")
 class DeprecatedServiceServicer(metaclass=abc.ABCMeta):
     """Marking the service as deprecated"""
 
@@ -302,5 +302,5 @@ class DeprecatedServiceServicer(metaclass=abc.ABCMeta):
     ) -> typing.Union[testproto.grpc.dummy_pb2.DummyReply, collections.abc.Awaitable[testproto.grpc.dummy_pb2.DummyReply]]:
         """DeprecatedMethodNotDeprecatedRequest"""
 
-@deprecated("This servicer has been marked as deprecated using proto service options.")
+@deprecated("""This service is deprecated""")
 def add_DeprecatedServiceServicer_to_server(servicer: DeprecatedServiceServicer, server: typing.Union[grpc.Server, grpc.aio.Server]) -> None: ...

test/generated/testproto/test_pb2.pyi

@@ -83,7 +83,7 @@ class _DeprecatedEnumEnumTypeWrapper(google.protobuf.internal.enum_type_wrapper.
     DEPRECATED_ONE: _DeprecatedEnum.ValueType  # 1
     DEPRECATED_TWO: _DeprecatedEnum.ValueType  # 2
 
-@deprecated("This enum has been marked as deprecated using proto enum options.")
+@deprecated("""This enum is deprecated\n2 lines of comments\n"Quotes in comments"\nand 'single quotes'\nTrailing comment""")
 class DeprecatedEnum(_DeprecatedEnum, metaclass=_DeprecatedEnumEnumTypeWrapper): ...
 
 DEPRECATED_ONE: DeprecatedEnum.ValueType  # 1
@@ -407,7 +407,7 @@ class SelfField(google.protobuf.message.Message):
 
 Global___SelfField: typing_extensions.TypeAlias = SelfField
 
-@deprecated("This message has been marked as deprecated using proto message options.")
+@deprecated("""This message is deprecated""")
 @typing.final
 class DeprecatedMessage(google.protobuf.message.Message):
     DESCRIPTOR: google.protobuf.descriptor.Descriptor

test_negative/output.expected.3.13

@@ -4,18 +4,26 @@ test/generated/testproto/grpc/dummy_pb2_grpc.pyi:215: note: class testproto.grpc
 test/generated/testproto/grpc/dummy_pb2_grpc.pyi:219: note: class testproto.grpc.dummy_pb2.DeprecatedRequest is deprecated: This message has been marked as deprecated using proto message options.  [deprecated]
 test/generated/testproto/grpc/dummy_pb2_grpc.pyi:245: note: class testproto.grpc.dummy_pb2.DeprecatedRequest is deprecated: This message has been marked as deprecated using proto message options.  [deprecated]
 test/generated/testproto/grpc/dummy_pb2_grpc.pyi:257: note: class testproto.grpc.dummy_pb2.DeprecatedRequest is deprecated: This message has been marked as deprecated using proto message options.  [deprecated]
-test/generated/testproto/grpc/dummy_pb2_grpc.pyi:274: note: class testproto.grpc.dummy_pb2_grpc.DeprecatedServiceStub is deprecated: This stub has been marked as deprecated using proto service options.  [deprecated]
+test/generated/testproto/grpc/dummy_pb2_grpc.pyi:274: note: class testproto.grpc.dummy_pb2_grpc.DeprecatedServiceStub is deprecated: This service is deprecated  [deprecated]
 test/generated/testproto/grpc/dummy_pb2_grpc.pyi:276: note: class testproto.grpc.dummy_pb2.DeprecatedRequest is deprecated: This message has been marked as deprecated using proto message options.  [deprecated]
 test/generated/testproto/grpc/dummy_pb2_grpc.pyi:292: note: class testproto.grpc.dummy_pb2.DeprecatedRequest is deprecated: This message has been marked as deprecated using proto message options.  [deprecated]
-test/generated/testproto/grpc/dummy_pb2_grpc.pyi:306: note: class testproto.grpc.dummy_pb2_grpc.DeprecatedServiceServicer is deprecated: This servicer has been marked as deprecated using proto service options.  [deprecated]
-test/generated/testproto/test_pb2.pyi:91: note: class testproto.test_pb2.DeprecatedEnum is deprecated: This enum has been marked as deprecated using proto enum options.  [deprecated]
-test/generated/testproto/test_pb2.pyi:425: note: class testproto.test_pb2.DeprecatedMessage is deprecated: This message has been marked as deprecated using proto message options.  [deprecated]
+test/generated/testproto/grpc/dummy_pb2_grpc.pyi:306: note: class testproto.grpc.dummy_pb2_grpc.DeprecatedServiceServicer is deprecated: This service is deprecated  [deprecated]
+test/generated/testproto/test_pb2.pyi:91: note: class testproto.test_pb2.DeprecatedEnum is deprecated: This enum is deprecated
+2 lines of comments
+"Quotes in comments"
+and 'single quotes'
+Trailing comment  [deprecated]
+test/generated/testproto/test_pb2.pyi:425: note: class testproto.test_pb2.DeprecatedMessage is deprecated: This message is deprecated  [deprecated]
 test_negative/negative.py:14: note: class testproto.grpc.dummy_pb2.DeprecatedRequest is deprecated: This message has been marked as deprecated using proto message options.  [deprecated]
-test_negative/negative.py:19: note: class testproto.grpc.dummy_pb2_grpc.DeprecatedServiceServicer is deprecated: This servicer has been marked as deprecated using proto service options.  [deprecated]
-test_negative/negative.py:19: note: class testproto.grpc.dummy_pb2_grpc.DeprecatedServiceStub is deprecated: This stub has been marked as deprecated using proto service options.  [deprecated]
-test_negative/negative.py:19: note: function testproto.grpc.dummy_pb2_grpc.add_DeprecatedServiceServicer_to_server is deprecated: This servicer has been marked as deprecated using proto service options.  [deprecated]
-test_negative/negative.py:29: note: class testproto.test_pb2.DeprecatedEnum is deprecated: This enum has been marked as deprecated using proto enum options.  [deprecated]
-test_negative/negative.py:30: note: class testproto.test_pb2.DeprecatedMessage is deprecated: This message has been marked as deprecated using proto message options.  [deprecated]
+test_negative/negative.py:19: note: class testproto.grpc.dummy_pb2_grpc.DeprecatedServiceServicer is deprecated: This service is deprecated  [deprecated]
+test_negative/negative.py:19: note: class testproto.grpc.dummy_pb2_grpc.DeprecatedServiceStub is deprecated: This service is deprecated  [deprecated]
+test_negative/negative.py:19: note: function testproto.grpc.dummy_pb2_grpc.add_DeprecatedServiceServicer_to_server is deprecated: This service is deprecated  [deprecated]
+test_negative/negative.py:29: note: class testproto.test_pb2.DeprecatedEnum is deprecated: This enum is deprecated
+2 lines of comments
+"Quotes in comments"
+and 'single quotes'
+Trailing comment  [deprecated]
+test_negative/negative.py:30: note: class testproto.test_pb2.DeprecatedMessage is deprecated: This message is deprecated  [deprecated]
 test_negative/negative.py:44: error: "Simple1" has no attribute "SerializeToStringg"  [attr-defined]
 test_negative/negative.py:47: error: Argument 1 to "ParseFromString" of "Message" has incompatible type "Simple1"; expected "bytes"  [arg-type]
 test_negative/negative.py:50: error: Argument 1 to "CopyFrom" of "Message" has incompatible type "bytes"; expected "Simple1"  [arg-type]