python: Fix docstring formatting (#15570)

Signed-off-by: Ryan Northey <[email protected]>

tools/api_proto_plugin/annotations.py

@@ -56,14 +56,14 @@ class AnnotationError(Exception):
 def extract_annotations(s, inherited_annotations=None):
     """Extract annotations map from a given comment string.
 
-  Args:
-    s: string that may contains annotations.
-    inherited_annotations: annotation map from file-level inherited annotations
-      (or None) if this is a file-level comment.
-
-  Returns:
-    Annotation map.
-  """
+    Args:
+        s: string that may contains annotations.
+        inherited_annotations: annotation map from file-level inherited annotations
+           (or None) if this is a file-level comment.
+
+    Returns:
+        Annotation map.
+    """
     annotations = {
         k: v for k, v in (inherited_annotations or {}).items() if k in INHERITED_ANNOTATIONS
     }
@@ -80,17 +80,17 @@ def extract_annotations(s, inherited_annotations=None):
 def xform_annotation(s, annotation_xforms):
     """Return transformed string with annotation transformers.
 
-  The annotation will be replaced with the new value returned by the transformer.
-  If the transformer returns None, then the annotation will be removed.
-  If the annotation presented in transformers doesn't exist in the original string,
-  a new annotation will be appended to the end of string.
+    The annotation will be replaced with the new value returned by the transformer.
+    If the transformer returns None, then the annotation will be removed.
+    If the annotation presented in transformers doesn't exist in the original string,
+    a new annotation will be appended to the end of string.
 
-  Args:
-    annotation_xforms: a dict of transformers for annotations.
+    Args:
+        annotation_xforms: a dict of transformers for annotations.
 
-  Returns:
-    transformed string.
-  """
+    Returns:
+        transformed string.
+    """
     present_annotations = set()
 
     def xform(match):

tools/api_proto_plugin/plugin.py

@@ -38,16 +38,16 @@ def direct_output_descriptor(output_suffix, visitor, want_params=False):
 def plugin(output_descriptors):
     """Protoc plugin entry point.
 
-  This defines protoc plugin and manages the stdin -> stdout flow. An
-  api_proto_plugin is defined by the provided visitor.
+    This defines protoc plugin and manages the stdin -> stdout flow. An
+    api_proto_plugin is defined by the provided visitor.
 
-  See
-  http://www.expobrain.net/2015/09/13/create-a-plugin-for-google-protocol-buffer/
-  for further details on protoc plugin basics.
+    See
+        http://www.expobrain.net/2015/09/13/create-a-plugin-for-google-protocol-buffer/
+          for further details on protoc plugin basics.
 
-  Args:
-    output_descriptors: a list of OutputDescriptors.
-  """
+    Args:
+        output_descriptors: a list of OutputDescriptors.
+    """
     request = plugin_pb2.CodeGeneratorRequest()
     request.ParseFromString(sys.stdin.buffer.read())
     response = plugin_pb2.CodeGeneratorResponse()

tools/api_proto_plugin/traverse.py

@@ -6,42 +6,42 @@
 def traverse_service(type_context, service_proto, visitor):
     """Traverse a service definition.
 
-  Args:
-    type_context: type_context.TypeContext for service type.
-    service_proto: ServiceDescriptorProto for service.
-    visitor: visitor.Visitor defining the business logic of the plugin.
-
-  Returns:
-    Plugin specific output.
-  """
+    Args:
+        type_context: type_context.TypeContext for service type.
+        service_proto: ServiceDescriptorProto for service.
+        visitor: visitor.Visitor defining the business logic of the plugin.
+
+    Returns:
+        Plugin specific output.
+    """
     return visitor.visit_service(service_proto, type_context)
 
 
 def traverse_enum(type_context, enum_proto, visitor):
     """Traverse an enum definition.
 
-  Args:
-    type_context: type_context.TypeContext for enum type.
-    enum_proto: EnumDescriptorProto for enum.
-    visitor: visitor.Visitor defining the business logic of the plugin.
+    Args:
+        type_context: type_context.TypeContext for enum type.
+        enum_proto: EnumDescriptorProto for enum.
+        visitor: visitor.Visitor defining the business logic of the plugin.
 
-  Returns:
-    Plugin specific output.
-  """
+    Returns:
+        Plugin specific output.
+    """
     return visitor.visit_enum(enum_proto, type_context)
 
 
 def traverse_message(type_context, msg_proto, visitor):
     """Traverse a message definition.
 
-  Args:
-    type_context: type_context.TypeContext for message type.
-    msg_proto: DescriptorProto for message.
-    visitor: visitor.Visitor defining the business logic of the plugin.
+    Args:
+        type_context: type_context.TypeContext for message type.
+        msg_proto: DescriptorProto for message.
+        visitor: visitor.Visitor defining the business logic of the plugin.
 
-  Returns:
-    Plugin specific output.
-  """
+    Returns:
+        Plugin specific output.
+    """
     # We need to do some extra work to recover the map type annotation from the
     # synthesized messages.
     type_context.map_typenames = {
@@ -67,13 +67,13 @@ def traverse_message(type_context, msg_proto, visitor):
 def traverse_file(file_proto, visitor):
     """Traverse a proto file definition.
 
-  Args:
-    file_proto: FileDescriptorProto for file.
-    visitor: visitor.Visitor defining the business logic of the plugin.
+    Args:
+        file_proto: FileDescriptorProto for file.
+        visitor: visitor.Visitor defining the business logic of the plugin.
 
-  Returns:
-    Plugin specific output.
-  """
+    Returns:
+        Plugin specific output.
+    """
     source_code_info = type_context.SourceCodeInfo(file_proto.name, file_proto.source_code_info)
     package_type_context = type_context.TypeContext(source_code_info, file_proto.package)
     services = [

tools/api_proto_plugin/type_context.py

@@ -16,12 +16,12 @@ def __init__(self, comment, file_level_annotations=None):
     def get_comment_with_transforms(self, annotation_xforms):
         """Return transformed comment with annotation transformers.
 
-    Args:
-      annotation_xforms: a dict of transformers for annotations in leading comment.
+        Args:
+            annotation_xforms: a dict of transformers for annotations in leading comment.
 
-    Returns:
-      transformed Comment object.
-    """
+        Returns:
+            transformed Comment object.
+        """
         return Comment(annotations.xform_annotation(self.raw, annotation_xforms),
                        self.file_level_annotations)
 
@@ -68,27 +68,27 @@ def file_level_annotations(self):
     def location_path_lookup(self, path):
         """Lookup SourceCodeInfo.Location by path in SourceCodeInfo.
 
-    Args:
-      path: a list of path indexes as per
-        https://github.com/google/protobuf/blob/a08b03d4c00a5793b88b494f672513f6ad46a681/src/google/protobuf/descriptor.proto#L717.
+        Args:
+            path: a list of path indexes as per
+              https://github.com/google/protobuf/blob/a08b03d4c00a5793b88b494f672513f6ad46a681/src/google/protobuf/descriptor.proto#L717.
 
-    Returns:
-      SourceCodeInfo.Location object if found, otherwise None.
-    """
+        Returns:
+            SourceCodeInfo.Location object if found, otherwise None.
+        """
         return self._locations.get(str(path), None)
 
     # TODO(htuch): consider integrating comment lookup with overall
     # FileDescriptorProto, perhaps via two passes.
     def leading_comment_path_lookup(self, path):
         """Lookup leading comment by path in SourceCodeInfo.
 
-    Args:
-      path: a list of path indexes as per
-        https://github.com/google/protobuf/blob/a08b03d4c00a5793b88b494f672513f6ad46a681/src/google/protobuf/descriptor.proto#L717.
+        Args:
+            path: a list of path indexes as per
+               https://github.com/google/protobuf/blob/a08b03d4c00a5793b88b494f672513f6ad46a681/src/google/protobuf/descriptor.proto#L717.
 
-    Returns:
-      Comment object.
-    """
+        Returns:
+            Comment object.
+        """
         location = self.location_path_lookup(path)
         if location is not None:
             return Comment(location.leading_comments, self.file_level_annotations)
@@ -97,13 +97,13 @@ def leading_comment_path_lookup(self, path):
     def leading_detached_comments_path_lookup(self, path):
         """Lookup leading detached comments by path in SourceCodeInfo.
 
-    Args:
-      path: a list of path indexes as per
-        https://github.com/google/protobuf/blob/a08b03d4c00a5793b88b494f672513f6ad46a681/src/google/protobuf/descriptor.proto#L717.
+        Args:
+            path: a list of path indexes as per
+               https://github.com/google/protobuf/blob/a08b03d4c00a5793b88b494f672513f6ad46a681/src/google/protobuf/descriptor.proto#L717.
 
-    Returns:
-      List of detached comment strings.
-    """
+        Returns:
+            List of detached comment strings.
+        """
         location = self.location_path_lookup(path)
         if location is not None and location.leading_detached_comments != self.file_level_comments:
             return location.leading_detached_comments
@@ -112,13 +112,13 @@ def leading_detached_comments_path_lookup(self, path):
     def trailing_comment_path_lookup(self, path):
         """Lookup trailing comment by path in SourceCodeInfo.
 
-    Args:
-      path: a list of path indexes as per
-        https://github.com/google/protobuf/blob/a08b03d4c00a5793b88b494f672513f6ad46a681/src/google/protobuf/descriptor.proto#L717.
+        Args:
+            path: a list of path indexes as per
+               https://github.com/google/protobuf/blob/a08b03d4c00a5793b88b494f672513f6ad46a681/src/google/protobuf/descriptor.proto#L717.
 
-    Returns:
-      Raw detached comment string
-    """
+        Returns:
+            Raw detached comment string
+        """
         location = self.location_path_lookup(path)
         if location is not None:
             return location.trailing_comments
@@ -128,9 +128,9 @@ def trailing_comment_path_lookup(self, path):
 class TypeContext(object):
     """Contextual information for a message/field.
 
-  Provides information around namespaces and enclosing types for fields and
-  nested messages/enums.
-  """
+    Provides information around namespaces and enclosing types for fields and
+    nested messages/enums.
+    """
 
     def __init__(self, source_code_info, name):
         # SourceCodeInfo as per
@@ -173,49 +173,49 @@ def _extend(self, path, type_name, name, deprecated=False):
     def extend_message(self, index, name, deprecated):
         """Extend type context with a message.
 
-    Args:
-      index: message index in file.
-      name: message name.
-      deprecated: is the message depreacted?
-    """
+        Args:
+            index: message index in file.
+            name: message name.
+            deprecated: is the message depreacted?
+        """
         return self._extend([4, index], 'message', name, deprecated)
 
     def extend_nested_message(self, index, name, deprecated):
         """Extend type context with a nested message.
 
-    Args:
-      index: nested message index in message.
-      name: message name.
-      deprecated: is the message depreacted?
-    """
+        Args:
+            index: nested message index in message.
+            name: message name.
+            deprecated: is the message depreacted?
+        """
         return self._extend([3, index], 'message', name, deprecated)
 
     def extend_field(self, index, name):
         """Extend type context with a field.
 
-    Args:
-      index: field index in message.
-      name: field name.
-    """
+        Args:
+            index: field index in message.
+            name: field name.
+        """
         return self._extend([2, index], 'field', name)
 
     def extend_enum(self, index, name, deprecated):
         """Extend type context with an enum.
 
-    Args:
-      index: enum index in file.
-      name: enum name.
-      deprecated: is the message depreacted?
-    """
+        Args:
+            index: enum index in file.
+            name: enum name.
+            deprecated: is the message depreacted?
+        """
         return self._extend([5, index], 'enum', name, deprecated)
 
     def extend_service(self, index, name):
         """Extend type context with a service.
 
-    Args:
-      index: service index in file.
-      name: service name.
-    """
+        Args:
+            index: service index in file.
+            name: service name.
+        """
         return self._extend([6, index], 'service', name)
 
     def extend_nested_enum(self, index, name, deprecated):
@@ -231,28 +231,28 @@ def extend_nested_enum(self, index, name, deprecated):
     def extend_enum_value(self, index, name):
         """Extend type context with an enum enum.
 
-    Args:
-      index: enum value index in enum.
-      name: value name.
-    """
+        Args:
+            index: enum value index in enum.
+            name: value name.
+        """
         return self._extend([2, index], 'enum_value', name)
 
     def extend_oneof(self, index, name):
         """Extend type context with an oneof declaration.
 
-    Args:
-      index: oneof index in oneof_decl.
-      name: oneof name.
-    """
+        Args:
+            index: oneof index in oneof_decl.
+            name: oneof name.
+        """
         return self._extend([8, index], 'oneof', name)
 
     def extend_method(self, index, name):
         """Extend type context with a service method declaration.
 
-    Args:
-      index: method index in service.
-      name: method name.
-    """
+        Args:
+            index: method index in service.
+            name: method name.
+        """
         return self._extend([2, index], 'method', name)
 
     @property