Annotate and clarify that metadata keys should be strings (#11736)

(cherry picked from commit d8ef5c3)

qiskit/primitives/containers/primitive_result.py

@@ -29,7 +29,8 @@ def __init__(self, pub_results: Iterable[T], metadata: dict[str, Any] | None = N
         """
         Args:
             pub_results: Pub results.
-            metadata: Any metadata that doesn't make sense to put inside of pub results.
+            metadata: Metadata that is common to all pub results; metadata specific to particular
+                pubs should be placed in their metadata fields. Keys are expected to be strings.
         """
         self._pub_results = list(pub_results)
         self._metadata = metadata or {}

qiskit/primitives/containers/pub_result.py

@@ -16,6 +16,8 @@
 
 from __future__ import annotations
 
+from typing import Any
+
 from .data_bin import DataBin
 
 
@@ -24,12 +26,12 @@ class PubResult:
 
     __slots__ = ("_data", "_metadata")
 
-    def __init__(self, data: DataBin, metadata: dict | None = None):
+    def __init__(self, data: DataBin, metadata: dict[str, Any] | None = None):
         """Initialize a pub result.
 
         Args:
-            data: result data bin.
-            metadata: metadata dictionary.
+            data: Result data.
+            metadata: Metadata specific to this pub. Keys are expected to be strings.
         """
         self._data = data
         self._metadata = metadata or {}

test/python/primitives/containers/test_primitive_result.py

@@ -36,9 +36,10 @@ def test_primitive_result(self):
             PubResult(data_bin_cls(alpha, beta)),
             PubResult(data_bin_cls(alpha, beta)),
         ]
-        result = PrimitiveResult(pub_results, {1: 2})
+        result = PrimitiveResult(pub_results, {"x": 2})
 
         self.assertTrue(result[0] is pub_results[0])
         self.assertTrue(result[1] is pub_results[1])
         self.assertTrue(list(result)[0] is pub_results[0])
         self.assertEqual(len(result), 2)
+        self.assertEqual(result.metadata, {"x": 2})