Add constructing unpack routine to Python Protobuf Any API.

The main benefit here is enabling unpacking in an expression context whereas previously multiple statements were required. The return/raise API is also more idiomatic to Python than the current one using an out parameter and status return.

PiperOrigin-RevId: 731911306

Author: jakobcornell

python/google/protobuf/any.py

@@ -7,14 +7,17 @@
 
 """Contains the Any helper APIs."""
 
-from typing import Optional
+from typing import Optional, TypeVar
 
 from google.protobuf import descriptor
 from google.protobuf.message import Message
 
 from google.protobuf.any_pb2 import Any
 
 
+_MessageT = TypeVar('_MessageT', bound=Message)
+
+
 def pack(
     msg: Message,
     type_url_prefix: Optional[str] = 'type.googleapis.com/',
@@ -31,6 +34,17 @@ def unpack(any_msg: Any, msg: Message) -> bool:
   return any_msg.Unpack(msg=msg)
 
 
+def unpack_as(any_msg: Any, message_type: type[_MessageT]) -> _MessageT:
+  unpacked = message_type()
+  if unpack(any_msg, unpacked):
+    return unpacked
+  else:
+    raise TypeError(
+        f'Attempted to unpack {type_name(any_msg)} to'
+        f' {message_type.__qualname__}'
+    )
+
+
 def type_name(any_msg: Any) -> str:
   return any_msg.TypeName()
 

python/google/protobuf/internal/any_test.py

@@ -10,7 +10,7 @@
 
 import unittest
 
-from google.protobuf import any
+from google.protobuf import any as proto_any
 
 from google.protobuf import any_pb2
 from google.protobuf import unittest_pb2
@@ -20,27 +20,42 @@ class AnyTest(unittest.TestCase):
 
   def test_pack_unpack(self):
     all_types = unittest_pb2.TestAllTypes()
-    any_msg = any.pack(all_types)
+    any_msg = proto_any.pack(all_types)
     all_descriptor = all_types.DESCRIPTOR
     self.assertEqual(
         any_msg.type_url, 'type.googleapis.com/%s' % all_descriptor.full_name
     )
+
+    # Any can be successfully unpacked to the correct message type.
     unpacked_message = unittest_pb2.TestAllTypes()
-    self.assertTrue(any.unpack(any_msg, unpacked_message))
+    self.assertTrue(proto_any.unpack(any_msg, unpacked_message))
+
+    proto_any.unpack_as(any_msg, unittest_pb2.TestAllTypes)
+
+    # Any can't be unpacked to an incorrect message type.
+    self.assertFalse(
+        proto_any.unpack(any_msg, unittest_pb2.TestAllTypes.NestedMessage())
+    )
+
+    with self.assertRaises(TypeError) as catcher:
+      proto_any.unpack_as(any_msg, unittest_pb2.TestAllTypes.NestedMessage)
+    self.assertIn('Attempted to unpack', catcher.exception.args[0])
 
   def test_type_name(self):
     all_types = unittest_pb2.TestAllTypes()
-    any_msg = any.pack(all_types)
-    self.assertEqual(any.type_name(any_msg), 'proto2_unittest.TestAllTypes')
+    any_msg = proto_any.pack(all_types)
+    self.assertEqual(
+        proto_any.type_name(any_msg), 'proto2_unittest.TestAllTypes'
+    )
 
   def test_is_type(self):
     all_types = unittest_pb2.TestAllTypes()
-    any_msg = any.pack(all_types)
+    any_msg = proto_any.pack(all_types)
     all_descriptor = all_types.DESCRIPTOR
-    self.assertTrue(any.is_type(any_msg, all_descriptor))
+    self.assertTrue(proto_any.is_type(any_msg, all_descriptor))
 
     empty_any = any_pb2.Any()
-    self.assertFalse(any.is_type(empty_any, all_descriptor))
+    self.assertFalse(proto_any.is_type(empty_any, all_descriptor))
 
 
 if __name__ == '__main__':