Give examples of the binsparse descriptor.

Author: hameerabbasi

spec/draft/extensions/sparse_interchange.rst

@@ -3,7 +3,7 @@
 Sparse interchange
 ==================
 
-    Array API specification for sparse interchange functions.
+    Array API specification for sparse interchange functions using `binsparse <https://graphblas.org/binsparse-specification/>`_.
 
 Extension name and usage
 ------------------------
@@ -14,11 +14,66 @@ If implemented, this extension must be retrievable via::
     >>> if hasattr(xp, 'sparse'):
     >>>     # Use the extension
 
-.. currentmodule:: array_api
+To convert an object from another library supporting also supporting the sparse interchange extension::
+
+    >>> xp1 = xp1.sparse.from_binsparse(xp2_array)  # Convert with the same formats
+    >>> xp1 = xp1.sparse.from_binsparse(xp2_array, descriptor=binsparse_descriptor)
+
+.. _binsparse_descriptor_examples:
+
+Examples of binsparse descriptors
+---------------------------------
+
+While the `binsparse specification <https://graphblas.org/binsparse-specification/>`_ uses JSON for its descriptor,
+we will work with equivalent Python objects instead. Here are some examples of binsparse descriptors::
+
+    >>> coo_2d_descriptor = {
+        "binsparse": {
+          "version": "0.1",
+          "format": "COOR",
+          "shape": [10, 12],
+          "number_of_stored_values": 20,
+          "data_types": {
+            "indices_0": "uint64",
+            "indices_1": "uint64",
+            "values": "float32",
+          },
+        },
+        "original_source": f"{library_name!s}, version {library_version!s}",
+    }
+    >>> csr_2d_descriptor = {
+        "binsparse": {
+          "version": "0.1",
+          "format": "CSR",
+          "shape": [20, 24],
+          "number_of_stored_values": 20,
+          "data_types": {
+            "pointers_to_1": "uint64",
+            "indices_1": "uint64",
+            "values": "float32",
+          },
+        },
+        "original_source": f"{library_name!s}, version {library_version!s}",
+    }
+    >>> compressed_vector_descriptor = {
+        "binsparse": {
+          "version": "0.1",
+          "format": "CVEC",
+          "shape": [30],
+          "number_of_stored_values": 3,
+          "data_types": {
+            "indices_0": "uint64",
+            "values": "float32",
+          },
+        },
+        "original_source": f"{library_name!s}, version {library_version!s}",
+    }
 
 Objects in API
 --------------
 
+.. currentmodule:: array_api
+
 A conforming implementation of this extension must provide and support the following
 functions/methods. In addition, the ``asarray`` method must also be able to convert
 objects with supported formats which implement the protocol.

src/array_api_stubs/_draft/array_object.py

@@ -1272,7 +1272,7 @@ def __binsparse__(
         self: array
             array instance.
         descriptor: Optional[dict]
-            If ``descriptor`` is not ``None``, the data returned must be in the format specified by it. If the format is unsupported, a ``TypeError`` must be raised.
+            If ``descriptor`` is not ``None``, the data returned must be in the format specified by it.
 
         Returns
         -------
@@ -1283,6 +1283,14 @@ def __binsparse__(
         ------
         TypeError
             If ``descriptor`` is not ``None``, and the array library does not support converting to a format specified by it.
+        ValueError
+            If ``descriptor`` is not a valid binsparse descriptor.
+
+        Notes
+        -----
+
+        - ``x.__binsparse_descriptor__()["binsparse"]["data_types"].keys() == x.__binsparse__().keys()`` must hold.
+        - ``descriptor["binsparse"]["data_types"].keys() == x.__binsparse__(descriptor=descriptor).keys()`` must hold.
         """
 
 

src/array_api_stubs/_draft/sparse.py

@@ -67,7 +67,8 @@ def from_binsparse(
         on the input array. This may happen for libraries that are never able
         to export their data with binsparse.
     ValueError
-        If data exchange is possible via an explicit copy but ``copy`` is set to ``False``.
+        If data exchange is possible via an explicit copy but ``copy`` is set to ``False``, or if the specified
+        descriptor is not valid.
     TypeError
         If ``descriptor`` is ``None``, the data received from the source library is not guaranteed to
         be in a format that the target array library supports. In this case, a ``TypeError`` must be raised.