docs: clarify return values for Arrow C Array export in documentation and type hints

Author: kosiew

docs/source/user-guide/io/arrow.rst

@@ -35,7 +35,12 @@ To import an Arrow table, use :py:func:`datafusion.context.SessionContext.from_a
 This will accept any Python object that implements
 `__arrow_c_stream__ <https://arrow.apache.org/docs/format/CDataInterface/PyCapsuleInterface.html#arrowstream-export>`_
 or `__arrow_c_array__ <https://arrow.apache.org/docs/format/CDataInterface/PyCapsuleInterface.html#arrowarray-export>`_
-and returns a ``StructArray``. Common pyarrow sources you can use are:
+and returns a ``StructArray``.
+
+.. note::
+    ``__arrow_c_array__`` must return ``(array_capsule, schema_capsule)``.
+
+Common pyarrow sources you can use are:
 
 - `Array <https://arrow.apache.org/docs/python/generated/pyarrow.Array.html>`_ (but it must return a Struct Array)
 - `Record Batch <https://arrow.apache.org/docs/python/generated/pyarrow.RecordBatch.html>`_

python/datafusion/context.py

@@ -64,6 +64,8 @@ class ArrowArrayExportable(Protocol):
     """Type hint for object exporting Arrow C Array via Arrow PyCapsule Interface.
 
     https://arrow.apache.org/docs/format/CDataInterface/PyCapsuleInterface.html
+
+    The method should return ``(array_capsule, schema_capsule)``.
     """
 
     def __arrow_c_array__(  # noqa: D105

python/datafusion/record_batch.py

@@ -57,7 +57,11 @@ def __arrow__(self, *args: object, **kwargs: object) -> pa.RecordBatch:
     def __arrow_c_array__(
         self, requested_schema: object | None = None
     ) -> tuple[object, object]:
-        """Arrow C Data Interface export."""
+        """Arrow C Data Interface export.
+
+        Returns:
+            tuple[object, object]: ``(array_capsule, schema_capsule)``
+        """
         return self.record_batch.__arrow_c_array__(requested_schema)
 
 

src/record_batch.rs

@@ -142,7 +142,7 @@ impl PyRecordBatch {
                 .downcast_into::<PyCapsule>()
                 .unwrap();
 
-            Ok((schema_capsule, array_capsule))
+            Ok((array_capsule, schema_capsule))
         }
     }
 }