Tests and impl for resource path helper methods (#253)

Includes generated unit tests, plumbing code unit tests, and system
tests for determining whether a message is a resource, providing an
accessor for one and only one path if it is a resource, and a service
accessor for all message fields that are resources (only one level
deep at the moment).

Author: software-dov

packages/gapic-generator/gapic/schema/wrappers.py

@@ -37,6 +37,7 @@
 from google.api import annotations_pb2      # type: ignore
 from google.api import client_pb2
 from google.api import field_behavior_pb2
+from google.api import resource_pb2
 from google.api_core import exceptions      # type: ignore
 from google.protobuf import descriptor_pb2  # type: ignore
 
@@ -212,6 +213,9 @@ class MessageType:
     def __getattr__(self, name):
         return getattr(self.message_pb, name)
 
+    def __hash__(self):
+        return hash(self.name)
+
     @utils.cached_property
     def field_types(self) -> Sequence[Union['MessageType', 'EnumType']]:
         """Return all composite fields used in this proto's messages."""
@@ -231,6 +235,25 @@ def ident(self) -> metadata.Address:
         """Return the identifier data to be used in templates."""
         return self.meta.address
 
+    @property
+    def resource_path(self) -> Optional[str]:
+        """If this message describes a resource, return the path to the resource.
+        If there are multiple paths, returns the first one."""
+        return next(
+            iter(self.options.Extensions[resource_pb2.resource].pattern),
+            None
+        )
+
+    @property
+    def resource_type(self) -> Optional[str]:
+        resource = self.options.Extensions[resource_pb2.resource]
+        return resource.type[resource.type.find('/') + 1:] if resource else None
+
+    @property
+    def resource_path_args(self) -> Sequence[str]:
+        path_arg_re = re.compile(r'\{([a-zA-Z0-9_-]+)\}')
+        return path_arg_re.findall(self.resource_path or '')
+
     def get_field(self, *field_path: str,
                   collisions: FrozenSet[str] = frozenset()) -> Field:
         """Return a field arbitrarily deep in this message's structure.
@@ -732,6 +755,17 @@ def names(self) -> FrozenSet[str]:
         # Done; return the answer.
         return frozenset(answer)
 
+    @utils.cached_property
+    def resource_messages(self) -> FrozenSet[MessageType]:
+        """Returns all the resource message types used in all
+        request fields in the service."""
+        return frozenset(
+            field.message
+            for method in self.methods.values()
+            for field in method.input.fields.values()
+            if field.message and field.message.resource_path
+        )
+
     def with_context(self, *, collisions: FrozenSet[str]) -> 'Service':
         """Return a derivative of this service with the provided context.
 

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

@@ -81,6 +81,13 @@ class {{ service.client_name }}(metaclass={{ service.client_name }}Meta):
     from_service_account_json = from_service_account_file
 
 
+    {% for message in service.resource_messages -%}
+    @staticmethod
+    def {{ message.resource_type|snake_case }}_path({% for arg in message.resource_path_args %}{{ arg }}: str,{% endfor %}) -> str:
+        """Return a fully-qualified {{ message.resource_type|snake_case }} string."""
+        return "{{ message.resource_path }}".format({% for arg in message.resource_path_args %}{{ arg }}={{ arg }}, {% endfor %})
+    {% endfor %}
+
     def __init__(self, *,
             credentials: credentials.Credentials = None,
             transport: Union[str, {{ service.name }}Transport] = None,

packages/gapic-generator/gapic/templates/tests/unit/%name_%version/%sub/test_%service.py.j2

@@ -422,4 +422,17 @@ def test_{{ service.name|snake_case }}_grpc_lro_client():
     assert transport.operations_client is transport.operations_client
 
 {% endif -%}
+
+{% for message in service.resource_messages -%}
+{% with molluscs = cycler("squid", "clam", "whelk", "octopus", "oyster", "nudibranch", "cuttlefish", "mussel", "winkle") -%}
+def test_{{ message.name|snake_case }}_path():
+  {% for arg in message.resource_path_args -%}
+  {{ arg }} = "{{ molluscs.next() }}"
+  {% endfor %}
+  expected = "{{ message.resource_path }}".format({% for arg in message.resource_path_args %}{{ arg }}={{ arg }}, {% endfor %})
+  actual = {{ service.client_name }}.{{ message.name|snake_case }}_path({{message.resource_path_args|join(", ") }})
+  assert expected == actual
+
+{% endwith -%}
+{% endfor -%}
 {% endblock %}

packages/gapic-generator/tests/system/test_resource_crud.py

@@ -43,3 +43,10 @@ def test_crud_positional(identity):
         assert identity.get_user(user.name).display_name == 'Monty Python'
     finally:
         identity.delete_user(user.name)
+
+
+def test_path_methods(identity):
+    expected = "users/bdfl"
+    actual = identity.user_path("bdfl")
+
+    assert expected == actual

packages/gapic-generator/tests/unit/schema/wrappers/test_message.py

@@ -17,6 +17,7 @@
 
 import pytest
 
+from google.api import resource_pb2
 from google.protobuf import descriptor_pb2
 
 from gapic.schema import metadata
@@ -124,6 +125,21 @@ def test_get_field_nonterminal_repeated_error():
         assert outer.get_field('inner', 'one') == inner_fields[1]
 
 
+def test_resource_path():
+    options = descriptor_pb2.MessageOptions()
+    resource = options.Extensions[resource_pb2.resource]
+    resource.pattern.append(
+        "kingdoms/{kingdom}/phyla/{phylum}/classes/{klass}")
+    resource.pattern.append(
+        "kingdoms/{kingdom}/divisions/{division}/classes/{klass}")
+    resource.type = "taxonomy.biology.com/Class"
+    message = make_message('Squid', options=options)
+
+    assert message.resource_path == "kingdoms/{kingdom}/phyla/{phylum}/classes/{klass}"
+    assert message.resource_path_args == ["kingdom", "phylum", "klass"]
+    assert message.resource_type == "Class"
+
+
 def test_field_map():
     # Create an Entry message.
     entry_msg = make_message(
@@ -140,8 +156,8 @@ def test_field_map():
 
 
 def make_message(name: str, package: str = 'foo.bar.v1', module: str = 'baz',
-        fields: Sequence[wrappers.Field] = (), meta: metadata.Metadata = None,
-        options: descriptor_pb2.MethodOptions = None,
+                 fields: Sequence[wrappers.Field] = (), meta: metadata.Metadata = None,
+                 options: descriptor_pb2.MethodOptions = None,
                  ) -> wrappers.MessageType:
     message_pb = descriptor_pb2.DescriptorProto(
         name=name,
@@ -183,7 +199,7 @@ def make_field(name: str, repeated: bool = False,
 
 
 def make_enum(name: str, package: str = 'foo.bar.v1', module: str = 'baz',
-        values: Tuple[str, int] = (), meta: metadata.Metadata = None,
+              values: Tuple[str, int] = (), meta: metadata.Metadata = None,
               ) -> wrappers.EnumType:
     enum_value_pbs = [
         descriptor_pb2.EnumValueDescriptorProto(name=i[0], number=i[1])

packages/gapic-generator/tests/unit/schema/wrappers/test_service.py

@@ -12,11 +12,13 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 
+import collections
 import typing
 
 from google.api import annotations_pb2
 from google.api import client_pb2
 from google.api import http_pb2
+from google.api import resource_pb2
 from google.protobuf import descriptor_pb2
 
 from gapic.schema import imp
@@ -146,6 +148,52 @@ def test_module_name():
     assert service.module_name == 'my_service'
 
 
+def test_resource_messages():
+    # Resources
+    squid_options = descriptor_pb2.MessageOptions()
+    squid_options.Extensions[resource_pb2.resource].pattern.append(
+        "squid/{squid}")
+    squid_message = make_message("Squid", options=squid_options)
+    clam_options = descriptor_pb2.MessageOptions()
+    clam_options.Extensions[resource_pb2.resource].pattern.append(
+        "clam/{clam}")
+    clam_message = make_message("Clam", options=clam_options)
+    whelk_options = descriptor_pb2.MessageOptions()
+    whelk_options.Extensions[resource_pb2.resource].pattern.append(
+        "whelk/{whelk}")
+    whelk_message = make_message("Whelk", options=whelk_options)
+
+    # Not resources
+    octopus_message = make_message("Octopus")
+    oyster_message = make_message("Oyster")
+    nudibranch_message = make_message("Nudibranch")
+
+    service = make_service(
+        'Molluscs',
+        methods=(
+            make_method(
+                f"Get{message.name}",
+                input_message=make_message(
+                    f"{message.name}Request",
+                    fields=[make_field(message.name, message=message)]
+                )
+            )
+            for message in (
+                squid_message,
+                clam_message,
+                whelk_message,
+                octopus_message,
+                oyster_message,
+                nudibranch_message
+            )
+        )
+    )
+
+    expected = {squid_message, clam_message, whelk_message}
+    actual = service.resource_messages
+    assert expected == actual
+
+
 def make_service(name: str = 'Placeholder', host: str = '',
                  methods: typing.Tuple[wrappers.Method] = (),
                  scopes: typing.Tuple[str] = ()) -> wrappers.Service:
@@ -248,6 +296,7 @@ def get_message(dot_path: str, *,
     # path is just google.protobuf.DescriptorProto).
     pieces = dot_path.split('.')
     pkg, module, name = pieces[:-2], pieces[-2], pieces[-1]
+
     return wrappers.MessageType(
         fields={i.name: wrappers.Field(
             field_pb=i,
@@ -264,6 +313,93 @@ def get_message(dot_path: str, *,
     )
 
 
+def make_method(
+        name: str, input_message: wrappers.MessageType = None,
+        output_message: wrappers.MessageType = None,
+        package: str = 'foo.bar.v1', module: str = 'baz',
+        http_rule: http_pb2.HttpRule = None,
+        signatures: typing.Sequence[str] = (),
+        **kwargs) -> wrappers.Method:
+    # Use default input and output messages if they are not provided.
+    input_message = input_message or make_message('MethodInput')
+    output_message = output_message or make_message('MethodOutput')
+
+    # Create the method pb2.
+    method_pb = descriptor_pb2.MethodDescriptorProto(
+        name=name,
+        input_type=str(input_message.meta.address),
+        output_type=str(output_message.meta.address),
+        **kwargs
+    )
+
+    # If there is an HTTP rule, process it.
+    if http_rule:
+        ext_key = annotations_pb2.http
+        method_pb.options.Extensions[ext_key].MergeFrom(http_rule)
+
+    # If there are signatures, include them.
+    for sig in signatures:
+        ext_key = client_pb2.method_signature
+        method_pb.options.Extensions[ext_key].append(sig)
+
+    # Instantiate the wrapper class.
+    return wrappers.Method(
+        method_pb=method_pb,
+        input=input_message,
+        output=output_message,
+        meta=metadata.Metadata(address=metadata.Address(
+            name=name,
+            package=package,
+            module=module,
+            parent=(f'{name}Service',),
+        )),
+    )
+
+
+def make_field(name: str, repeated: bool = False,
+               message: wrappers.MessageType = None,
+               enum: wrappers.EnumType = None,
+               meta: metadata.Metadata = None, **kwargs) -> wrappers.Method:
+    if message:
+        kwargs['type_name'] = str(message.meta.address)
+    if enum:
+        kwargs['type_name'] = str(enum.meta.address)
+    field_pb = descriptor_pb2.FieldDescriptorProto(
+        name=name,
+        label=3 if repeated else 1,
+        **kwargs
+    )
+    return wrappers.Field(
+        enum=enum,
+        field_pb=field_pb,
+        message=message,
+        meta=meta or metadata.Metadata(),
+    )
+
+
+def make_message(name: str, package: str = 'foo.bar.v1', module: str = 'baz',
+                 fields: typing.Sequence[wrappers.Field] = (),
+                 meta: metadata.Metadata = None,
+                 options: descriptor_pb2.MethodOptions = None,
+                 ) -> wrappers.MessageType:
+    message_pb = descriptor_pb2.DescriptorProto(
+        name=name,
+        field=[i.field_pb for i in fields],
+        options=options,
+    )
+    return wrappers.MessageType(
+        message_pb=message_pb,
+        fields=collections.OrderedDict((i.name, i) for i in fields),
+        nested_messages={},
+        nested_enums={},
+        meta=meta or metadata.Metadata(address=metadata.Address(
+            name=name,
+            package=tuple(package.split('.')),
+            module=module,
+        )),
+    )
+
+
 def get_enum(dot_path: str) -> wrappers.EnumType:
     pieces = dot_path.split('.')
     pkg, module, name = pieces[:-2], pieces[-2], pieces[-1]