ObservablesArray docstring improvement (#13423)

* ObservablesArray docstring improvement * Update qiskit/primitives/containers/observables_array.py Co-authored-by: Elena Peña Tapia <[email protected]> * Update qiskit/primitives/containers/observables_array.py Co-authored-by: Elena Peña Tapia <[email protected]> * Linting * Added `ObservableLike` as possible return type --------- Co-authored-by: Elena Peña Tapia <[email protected]>
Qiskit · Jan 7, 2025 · b9cba9f · b9cba9f
1 parent 0d4ee23
commit b9cba9f
Show file tree

Hide file tree

Showing 2 changed files with 25 additions and 2 deletions.
diff --git a/qiskit/primitives/containers/observables_array.py b/qiskit/primitives/containers/observables_array.py
@@ -97,8 +97,25 @@ def __repr__(self):
         array = np.array2string(self._array, prefix=prefix, suffix=suffix, threshold=50)
         return prefix + array + suffix
 
-    def tolist(self) -> list:
-        """Convert to a nested list"""
+    def tolist(self) -> list | ObservableLike:
+        """Convert to a nested list.
+
+        Similar to Numpy's ``tolist`` method, the level of nesting
+        depends on the dimension of the observables array. In the
+        case of dimension 0 the method returns a single observable
+        (``dict`` in the case of a weighted sum of Paulis) instead of a list.
+
+        Examples::
+            Return values for a one-element list vs one element:
+
+                >>> from qiskit.primitives.containers.observables_array import ObservablesArray
+                >>> oa = ObservablesArray.coerce(["Z"])
+                >>> print(type(oa.tolist()))
+                <class 'list'>
+                >>> oa = ObservablesArray.coerce("Z")
+                >>> print(type(oa.tolist()))
+                <class 'dict'>
+        """
         return self._array.tolist()
 
     def __array__(self, dtype=None, copy=None):

diff --git a/releasenotes/notes/improve_observables_array_docstring-d6e74b1871e3145c.yaml b/releasenotes/notes/improve_observables_array_docstring-d6e74b1871e3145c.yaml
@@ -0,0 +1,6 @@
+---
+features_primitives:
+  - |
+    Expanded the docstring of :meth:`.ObservablesArray.tolist`
+    to make it clear it might return a scalar in the case
+    the observables array is of dimension 0.