feat: support protobuf method deprecation option [gapic-generator-python] (#875)

Author: miraleung

gapic/ads-templates/%namespace/%name/%version/%sub/services/%service/client.py.j2

@@ -334,6 +334,9 @@ class {{ service.client_name }}(metaclass={{ service.client_name }}Meta):
                 {{ method.client_output.meta.doc|rst(width=72, indent=16, source_format='rst') }}
         {% endif %}
         """
+        {% if method.is_deprecated %}
+        warnings.warn("{{ method.name|snake_case }} is deprecated", warnings.DeprecationWarning)
+        {% endif %}
         {% if not method.client_streaming %}
         # Create or coerce a protobuf request object.
         {% if method.flattened_fields %}

gapic/schema/wrappers.py

@@ -734,8 +734,14 @@ def _client_output(self, enable_asyncio: bool):
         # Return the usual output.
         return self.output
 
+    @property
+    def is_deprecated(self) -> bool:
+        """Returns true if the method is deprecated, false otherwise."""
+        return descriptor_pb2.MethodOptions.HasField(self.options, 'deprecated')
+
     # TODO(yon-mg): remove or rewrite: don't think it performs as intended
     #               e.g. doesn't work with basic case of gRPC transcoding
+
     @property
     def field_headers(self) -> Sequence[str]:
         """Return the field headers defined for this method."""

gapic/templates/%namespace/%name_%version/%sub/services/%service/client.py.j2

@@ -359,6 +359,9 @@ class {{ service.client_name }}(metaclass={{ service.client_name }}Meta):
                 {{ method.client_output.meta.doc|rst(width=72, indent=16, source_format="rst") }}
         {% endif %}
         """
+        {% if method.is_deprecated %}
+        warnings.warn("{{ method.name|snake_case }} is deprecated", warnings.DeprecationWarning)
+        {% endif %}
         {% if not method.client_streaming %}
         # Create or coerce a protobuf request object.
         {% if method.flattened_fields %}
@@ -476,9 +479,9 @@ class {{ service.client_name }}(metaclass={{ service.client_name }}Meta):
         metadata: Sequence[Tuple[str, str]] = (),
     ) -> policy_pb2.Policy:
         r"""Sets the IAM access control policy on the specified function.
-        
+
         Replaces any existing policy.
-        
+
         Args:
             request (:class:`~.iam_policy_pb2.SetIamPolicyRequest`):
                 The request object. Request message for `SetIamPolicy`

test_utils/test_utils.py

@@ -162,6 +162,7 @@ def make_method(
         module: str = 'baz',
         http_rule: http_pb2.HttpRule = None,
         signatures: typing.Sequence[str] = (),
+        is_deprecated: bool = False,
         **kwargs
 ) -> wrappers.Method:
     # Use default input and output messages if they are not provided.
@@ -189,6 +190,9 @@ def make_method(
     if isinstance(package, str):
         package = tuple(package.split('.'))
 
+    if is_deprecated:
+        method_pb.options.deprecated = True
+
     # Instantiate the wrapper class.
     return wrappers.Method(
         method_pb=method_pb,

tests/unit/schema/wrappers/test_method.py

@@ -52,6 +52,11 @@ def test_method_not_void():
     assert not method.void
 
 
+def test_method_deprecated():
+    method = make_method('DeprecatedMethod', is_deprecated=True)
+    assert method.is_deprecated
+
+
 def test_method_client_output():
     output = make_message(name='Input', module='baz')
     method = make_method('DoStuff', output_message=output)