Merge pull request #22306 from Skyscanner/issue-21953_type-of-metadata

[Aio] Initial modelling of the metadata abstraction

src/python/grpcio/grpc/experimental/aio/__init__.py

@@ -36,6 +36,7 @@ from ._server import server
 from ._base_server import Server, ServicerContext
 from ._typing import ChannelArgumentType
 from ._channel import insecure_channel, secure_channel
+from ._metadata import Metadata
 
 ###################################  __all__  #################################
 
@@ -68,4 +69,5 @@ __all__ = (
     'BaseError',
     'UsageError',
     'InternalError',
+    'Metadata',
 )

src/python/grpcio/grpc/experimental/aio/_metadata.py

@@ -0,0 +1,105 @@
+# Copyright 2020 gRPC authors.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+"""Implementation of the metadata abstraction for gRPC Asyncio Python."""
+from typing import List, Tuple, Iterator, Any, Text, Union
+from collections import abc, OrderedDict
+
+MetadataKey = Text
+MetadataValue = Union[str, bytes]
+
+
+class Metadata(abc.Mapping):
+    """Metadata abstraction for the asynchronous calls and interceptors.
+
+    The metadata is a mapping from str -> List[str]
+
+    Traits
+        * Multiple entries are allowed for the same key
+        * The order of the values by key is preserved
+        * Getting by an element by key, retrieves the first mapped value
+        * Supports an immutable view of the data
+        * Allows partial mutation on the data without recreating the new object from scratch.
+    """
+
+    def __init__(self, *args: Tuple[MetadataKey, MetadataValue]) -> None:
+        self._metadata = OrderedDict()
+        for md_key, md_value in args:
+            self.add(md_key, md_value)
+
+    def add(self, key: MetadataKey, value: MetadataValue) -> None:
+        self._metadata.setdefault(key, [])
+        self._metadata[key].append(value)
+
+    def __len__(self) -> int:
+        """Return the total number of elements that there are in the metadata,
+        including multiple values for the same key.
+        """
+        return sum(map(len, self._metadata.values()))
+
+    def __getitem__(self, key: MetadataKey) -> MetadataValue:
+        """When calling <metadata>[<key>], the first element of all those
+        mapped for <key> is returned.
+        """
+        try:
+            return self._metadata[key][0]
+        except (ValueError, IndexError) as e:
+            raise KeyError("{0!r}".format(key)) from e
+
+    def __setitem__(self, key: MetadataKey, value: MetadataValue) -> None:
+        """Calling metadata[<key>] = <value>
+        Maps <value> to the first instance of <key>.
+        """
+        if key not in self:
+            self._metadata[key] = [value]
+        else:
+            current_values = self.get_all(key)
+            self._metadata[key] = [value, *current_values[1:]]
+
+    def __delitem__(self, key: MetadataKey) -> None:
+        """``del metadata[<key>]`` deletes the first mapping for <key>."""
+        current_values = self.get_all(key)
+        if not current_values:
+            raise KeyError(repr(key))
+        self._metadata[key] = current_values[1:]
+
+    def delete_all(self, key: MetadataKey) -> None:
+        """Delete all mappings for <key>."""
+        del self._metadata[key]
+
+    def __iter__(self) -> Iterator[Tuple[MetadataKey, MetadataValue]]:
+        for key, values in self._metadata.items():
+            for value in values:
+                yield (key, value)
+
+    def get_all(self, key: MetadataKey) -> List[MetadataValue]:
+        """For compatibility with other Metadata abstraction objects (like in Java),
+        this would return all items under the desired <key>.
+        """
+        return self._metadata.get(key, [])
+
+    def set_all(self, key: MetadataKey, values: List[MetadataValue]) -> None:
+        self._metadata[key] = values
+
+    def __contains__(self, key: MetadataKey) -> bool:
+        return key in self._metadata
+
+    def __eq__(self, other: Any) -> bool:
+        if not isinstance(other, self.__class__):
+            return NotImplemented  # pytype: disable=bad-return-type
+
+        return self._metadata == other._metadata
+
+    def __repr__(self) -> str:
+        view = tuple(self)
+        return "{0}({1!r})".format(self.__class__.__name__, view)

src/python/grpcio_tests/tests_aio/tests.json

@@ -3,6 +3,7 @@
   "health_check.health_servicer_test.HealthServicerTest",
   "interop.local_interop_test.InsecureLocalInteropTest",
   "interop.local_interop_test.SecureLocalInteropTest",
+  "unit._metadata_test.TestTypeMetadata",
   "unit.abort_test.TestAbort",
   "unit.aio_rpc_error_test.TestAioRpcError",
   "unit.call_test.TestStreamStreamCall",

src/python/grpcio_tests/tests_aio/unit/_metadata_test.py

@@ -0,0 +1,125 @@
+# Copyright 2020 gRPC authors.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+"""Tests for the metadata abstraction that's used in the asynchronous driver."""
+import logging
+import unittest
+
+from grpc.experimental.aio import Metadata
+
+
+class TestTypeMetadata(unittest.TestCase):
+    """Tests for the metadata type"""
+
+    _DEFAULT_DATA = (("key1", "value1"), ("key2", "value2"))
+    _MULTI_ENTRY_DATA = (("key1", "value1"), ("key1", "other value 1"),
+                         ("key2", "value2"))
+
+    def test_init_metadata(self):
+        test_cases = {
+            "emtpy": (),
+            "with-single-data": self._DEFAULT_DATA,
+            "with-multi-data": self._MULTI_ENTRY_DATA,
+        }
+        for case, args in test_cases.items():
+            with self.subTest(case=case):
+                metadata = Metadata(*args)
+                self.assertEqual(len(metadata), len(args))
+
+    def test_get_item(self):
+        metadata = Metadata(("key", "value1"), ("key", "value2"),
+                            ("key2", "other value"))
+        self.assertEqual(metadata["key"], "value1")
+        self.assertEqual(metadata["key2"], "other value")
+        self.assertEqual(metadata.get("key"), "value1")
+        self.assertEqual(metadata.get("key2"), "other value")
+
+        with self.assertRaises(KeyError):
+            metadata["key not found"]
+        self.assertIsNone(metadata.get("key not found"))
+
+    def test_add_value(self):
+        metadata = Metadata()
+        metadata.add("key", "value")
+        metadata.add("key", "second value")
+        metadata.add("key2", "value2")
+
+        self.assertEqual(metadata["key"], "value")
+        self.assertEqual(metadata["key2"], "value2")
+
+    def test_get_all_items(self):
+        metadata = Metadata(*self._MULTI_ENTRY_DATA)
+        self.assertEqual(metadata.get_all("key1"), ["value1", "other value 1"])
+        self.assertEqual(metadata.get_all("key2"), ["value2"])
+        self.assertEqual(metadata.get_all("non existing key"), [])
+
+    def test_container(self):
+        metadata = Metadata(*self._MULTI_ENTRY_DATA)
+        self.assertIn("key1", metadata)
+
+    def test_equals(self):
+        metadata = Metadata()
+        for key, value in self._DEFAULT_DATA:
+            metadata.add(key, value)
+        metadata2 = Metadata(*self._DEFAULT_DATA)
+
+        self.assertEqual(metadata, metadata2)
+        self.assertNotEqual(metadata, "foo")
+
+    def test_repr(self):
+        metadata = Metadata(*self._DEFAULT_DATA)
+        expected = "Metadata({0!r})".format(self._DEFAULT_DATA)
+        self.assertEqual(repr(metadata), expected)
+
+    def test_set(self):
+        metadata = Metadata(*self._MULTI_ENTRY_DATA)
+        override_value = "override value"
+        for _ in range(3):
+            metadata["key1"] = override_value
+
+        self.assertEqual(metadata["key1"], override_value)
+        self.assertEqual(metadata.get_all("key1"),
+                         [override_value, "other value 1"])
+
+        empty_metadata = Metadata()
+        for _ in range(3):
+            empty_metadata["key"] = override_value
+
+        self.assertEqual(empty_metadata["key"], override_value)
+        self.assertEqual(empty_metadata.get_all("key"), [override_value])
+
+    def test_set_all(self):
+        metadata = Metadata(*self._DEFAULT_DATA)
+        metadata.set_all("key", ["value1", b"new value 2"])
+
+        self.assertEqual(metadata["key"], "value1")
+        self.assertEqual(metadata.get_all("key"), ["value1", b"new value 2"])
+
+    def test_delete_values(self):
+        metadata = Metadata(*self._MULTI_ENTRY_DATA)
+        del metadata["key1"]
+        self.assertEqual(metadata.get("key1"), "other value 1")
+
+        metadata.delete_all("key1")
+        self.assertNotIn("key1", metadata)
+
+        metadata.delete_all("key2")
+        self.assertEqual(len(metadata), 0)
+
+        with self.assertRaises(KeyError):
+            del metadata["other key"]
+
+
+if __name__ == '__main__':
+    logging.basicConfig()
+    unittest.main(verbosity=2)