fix: fix docstring for map fields (#1249)

* fix: fix docstring for map fields

* chore: format

* chore: fix typing

Co-authored-by: Anthonios Partheniou <partheniou@google.com>

gapic/schema/metadata.py

@@ -27,7 +27,7 @@
 """
 
 import dataclasses
-from typing import FrozenSet, Tuple
+from typing import FrozenSet, Tuple, Optional
 
 from google.protobuf import descriptor_pb2
 
@@ -362,14 +362,19 @@ def with_context(self, *, collisions: FrozenSet[str]) -> 'Metadata':
 class FieldIdentifier:
     ident: Address
     repeated: bool
+    mapping: Optional[tuple] = None
 
     def __str__(self) -> str:
+        if self.mapping:
+            return f'Mapping[{self.mapping[0].ident}, {self.mapping[1].ident}]'
         if self.repeated:
             return f'Sequence[{self.ident}]'
         return str(self.ident)
 
     @property
     def sphinx(self) -> str:
+        if self.mapping:
+            return f'Mapping[{self.mapping[0].ident.sphinx}, {self.mapping[1].ident.sphinx}]'
         if self.repeated:
             return f'Sequence[{self.ident.sphinx}]'
         return self.ident.sphinx

gapic/schema/wrappers.py

@@ -80,9 +80,13 @@ def name(self) -> str:
     @utils.cached_property
     def ident(self) -> metadata.FieldIdentifier:
         """Return the identifier to be used in templates."""
+        mapping: Union[None, Tuple[Field, Field]] = None
+        if self.map:
+            mapping = (self.type.fields["key"], self.type.fields["value"])
         return metadata.FieldIdentifier(
             ident=self.type.ident,
             repeated=self.repeated,
+            mapping=mapping,
         )
 
     @property

tests/integration/goldens/asset/google/cloud/asset_v1/types/assets.py

@@ -428,7 +428,7 @@ class ResourceSearchResult(proto.Message):
 
             -  use a field query. Example: ``location:us-west*``
             -  use a free text query. Example: ``us-west*``
-        labels (Sequence[google.cloud.asset_v1.types.ResourceSearchResult.LabelsEntry]):
+        labels (Mapping[str, str]):
             Labels associated with this resource. See `Labelling and
             grouping GCP
             resources <https://cloud.google.com/blog/products/gcp/labelling-and-grouping-your-google-cloud-platform-resources>`__
@@ -724,7 +724,7 @@ class Explanation(proto.Message):
         r"""Explanation about the IAM policy search result.
 
         Attributes:
-            matched_permissions (Sequence[google.cloud.asset_v1.types.IamPolicySearchResult.Explanation.MatchedPermissionsEntry]):
+            matched_permissions (Mapping[str, google.cloud.asset_v1.types.IamPolicySearchResult.Explanation.Permissions]):
                 The map from roles to their included permissions that match
                 the permission query (i.e., a query containing
                 ``policy.role.permissions:``). Example: if query

tests/integration/goldens/logging/google/cloud/logging_v2/services/logging_service_v2/async_client.py

@@ -296,7 +296,7 @@ async def write_log_entries(self,
             *,
             log_name: str = None,
             resource: monitored_resource_pb2.MonitoredResource = None,
-            labels: Sequence[logging.WriteLogEntriesRequest.LabelsEntry] = None,
+            labels: Mapping[str, str] = None,
             entries: Sequence[log_entry.LogEntry] = None,
             retry: OptionalRetry = gapic_v1.method.DEFAULT,
             timeout: float = None,
@@ -380,7 +380,7 @@ def sample_write_log_entries():
                 This corresponds to the ``resource`` field
                 on the ``request`` instance; if ``request`` is provided, this
                 should not be set.
-            labels (:class:`Sequence[google.cloud.logging_v2.types.WriteLogEntriesRequest.LabelsEntry]`):
+            labels (:class:`Mapping[str, str]`):
                 Optional. Default labels that are added to the
                 ``labels`` field of all log entries in ``entries``. If a
                 log entry already has a label with the same key as a

tests/integration/goldens/logging/google/cloud/logging_v2/services/logging_service_v2/client.py

@@ -475,7 +475,7 @@ def write_log_entries(self,
             *,
             log_name: str = None,
             resource: monitored_resource_pb2.MonitoredResource = None,
-            labels: Sequence[logging.WriteLogEntriesRequest.LabelsEntry] = None,
+            labels: Mapping[str, str] = None,
             entries: Sequence[log_entry.LogEntry] = None,
             retry: OptionalRetry = gapic_v1.method.DEFAULT,
             timeout: float = None,
@@ -559,7 +559,7 @@ def sample_write_log_entries():
                 This corresponds to the ``resource`` field
                 on the ``request`` instance; if ``request`` is provided, this
                 should not be set.
-            labels (Sequence[google.cloud.logging_v2.types.WriteLogEntriesRequest.LabelsEntry]):
+            labels (Mapping[str, str]):
                 Optional. Default labels that are added to the
                 ``labels`` field of all log entries in ``entries``. If a
                 log entry already has a label with the same key as a

tests/integration/goldens/logging/google/cloud/logging_v2/types/log_entry.py

@@ -142,7 +142,7 @@ class LogEntry(proto.Message):
         http_request (google.logging.type.http_request_pb2.HttpRequest):
             Optional. Information about the HTTP request
             associated with this log entry, if applicable.
-        labels (Sequence[google.cloud.logging_v2.types.LogEntry.LabelsEntry]):
+        labels (Mapping[str, str]):
             Optional. A set of user-defined (key, value)
             data that provides additional information about
             the log entry.

tests/integration/goldens/logging/google/cloud/logging_v2/types/logging.py

@@ -106,7 +106,7 @@ class WriteLogEntriesRequest(proto.Message):
                     "zone": "us-central1-a", "instance_id": "00000000000000000000" }}
 
             See [LogEntry][google.logging.v2.LogEntry].
-        labels (Sequence[google.cloud.logging_v2.types.WriteLogEntriesRequest.LabelsEntry]):
+        labels (Mapping[str, str]):
             Optional. Default labels that are added to the ``labels``
             field of all log entries in ``entries``. If a log entry
             already has a label with the same key as a label in this
@@ -196,7 +196,7 @@ class WriteLogEntriesPartialErrors(proto.Message):
     r"""Error details for WriteLogEntries with partial success.
 
     Attributes:
-        log_entry_errors (Sequence[google.cloud.logging_v2.types.WriteLogEntriesPartialErrors.LogEntryErrorsEntry]):
+        log_entry_errors (Mapping[int, google.rpc.status_pb2.Status]):
             When ``WriteLogEntriesRequest.partial_success`` is true,
             records the error status for entries that were not written
             due to a permanent error, keyed by the entry's zero-based

tests/integration/goldens/logging/google/cloud/logging_v2/types/logging_metrics.py

@@ -125,7 +125,7 @@ class LogMetric(proto.Message):
 
             Example:
             ``REGEXP_EXTRACT(jsonPayload.request, ".*quantity=(\d+).*")``
-        label_extractors (Sequence[google.cloud.logging_v2.types.LogMetric.LabelExtractorsEntry]):
+        label_extractors (Mapping[str, str]):
             Optional. A map from a label key string to an extractor
             expression which is used to extract data from a log entry
             field and assign as the label value. Each label key

tests/integration/goldens/redis/google/cloud/redis_v1/types/cloud_redis.py

@@ -65,7 +65,7 @@ class Instance(proto.Message):
         display_name (str):
             An arbitrary and optional user-provided name
             for the instance.
-        labels (Sequence[google.cloud.redis_v1.types.Instance.LabelsEntry]):
+        labels (Mapping[str, str]):
             Resource labels to represent user provided
             metadata
         location_id (str):
@@ -124,7 +124,7 @@ class Instance(proto.Message):
         status_message (str):
             Output only. Additional information about the
             current status of this instance, if available.
-        redis_configs (Sequence[google.cloud.redis_v1.types.Instance.RedisConfigsEntry]):
+        redis_configs (Mapping[str, str]):
             Optional. Redis configuration parameters, according to
             http://redis.io/topics/config. Currently, the only supported
             parameters are:
@@ -697,7 +697,7 @@ class LocationMetadata(proto.Message):
     ``google.cloud.location.Location.metadata`` field.
 
     Attributes:
-        available_zones (Sequence[google.cloud.redis_v1.types.LocationMetadata.AvailableZonesEntry]):
+        available_zones (Mapping[str, google.cloud.redis_v1.types.ZoneMetadata]):
             Output only. The set of available zones in the location. The
             map is keyed by the lowercase ID of each zone, as defined by
             GCE. These keys can be specified in ``location_id`` or

tests/unit/schema/wrappers/test_field.py

@@ -86,6 +86,46 @@ def test_not_repeated():
     assert not field.repeated
 
 
+def test_map():
+    entry_msg = make_message(
+        name='SquidEntry',
+        fields=(
+            make_field(name='key', type='TYPE_STRING'),
+            make_field(name='value', type='TYPE_STRING'),
+        ),
+        options=descriptor_pb2.MessageOptions(map_entry=True),
+    )
+    field = make_field(
+        name='squids',
+        type_name='mollusc.SquidEntry',
+        message=entry_msg,
+        label=3,
+        type='TYPE_MESSAGE',
+    )
+
+    assert field.map
+
+
+def test_ident_map():
+    entry_msg = make_message(
+        name='SquidEntry',
+        fields=(
+            make_field(name='key', type='TYPE_STRING'),
+            make_field(name='value', type='TYPE_STRING'),
+        ),
+        options=descriptor_pb2.MessageOptions(map_entry=True),
+    )
+    field = make_field(
+        name='squids',
+        type_name='mollusc.SquidEntry',
+        message=entry_msg,
+        label=3,
+        type='TYPE_MESSAGE',
+    )
+
+    assert str(field.ident) == "Mapping[str, str]"
+
+
 def test_required():
     field = make_field()
     field.options.Extensions[field_behavior_pb2.field_behavior].append(
@@ -110,6 +150,25 @@ def test_ident_sphinx_repeated():
     assert field.ident.sphinx == 'Sequence[bool]'
 
 
+def test_ident_sphinx_map():
+    entry_msg = make_message(
+        name='SquidEntry',
+        fields=(
+            make_field(name='key', type='TYPE_STRING'),
+            make_field(name='value', type='TYPE_STRING'),
+        ),
+        options=descriptor_pb2.MessageOptions(map_entry=True),
+    )
+    field = make_field(
+        name='squids',
+        type_name='mollusc.SquidEntry',
+        message=entry_msg,
+        label=3,
+        type='TYPE_MESSAGE',
+    )
+    assert field.ident.sphinx == 'Mapping[str, str]'
+
+
 def test_resource_reference():
     field = make_field(type='TYPE_STRING')
     field.options.Extensions[resource_pb2.resource_reference].type = "translate.googleapis.com/Glossary"