Add examples to docstrings for new register/read methods

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Author: timsaucer

conftest.py

@@ -19,6 +19,7 @@
 
 import datafusion as dfn
 import numpy as np
+import pyarrow as pa
 import pytest
 from datafusion import col, lit
 from datafusion import functions as F
@@ -29,6 +30,8 @@ def _doctest_namespace(doctest_namespace: dict) -> None:
     """Add common imports to the doctest namespace."""
     doctest_namespace["dfn"] = dfn
     doctest_namespace["np"] = np
+    doctest_namespace["pa"] = pa
     doctest_namespace["col"] = col
     doctest_namespace["lit"] = lit
     doctest_namespace["F"] = F
+    doctest_namespace["ctx"] = dfn.SessionContext()

python/datafusion/context.py

@@ -900,6 +900,17 @@ def register_batch(self, name: str, batch: pa.RecordBatch) -> None:
         Args:
             name: Name of the resultant table.
             batch: Record batch to register as a table.
+
+        Examples:
+            >>> batch = pa.RecordBatch.from_pydict({"a": [1, 2, 3]})
+            >>> ctx.register_batch("batch_tbl", batch)
+            >>> ctx.sql("SELECT * FROM batch_tbl").collect()[0].column(0)
+            <pyarrow.lib.Int64Array object at ...>
+            [
+              1,
+              2,
+              3
+            ]
         """
         self.ctx.register_batch(name, batch)
 
@@ -1120,6 +1131,22 @@ def register_arrow(
             schema: The data source schema.
             file_extension: File extension to select.
             table_partition_cols: Partition columns.
+
+        Examples:
+            >>> import tempfile, os
+            >>> table = pa.table({"x": [10, 20, 30]})
+            >>> with tempfile.TemporaryDirectory() as tmpdir:
+            ...     path = os.path.join(tmpdir, "data.arrow")
+            ...     with pa.ipc.new_file(path, table.schema) as writer:
+            ...         writer.write_table(table)
+            ...     ctx.register_arrow("arrow_tbl", path)
+            ...     ctx.sql("SELECT * FROM arrow_tbl").collect()[0].column(0)
+            <pyarrow.lib.Int64Array object at ...>
+            [
+              10,
+              20,
+              30
+            ]
         """
         if table_partition_cols is None:
             table_partition_cols = []
@@ -1381,6 +1408,22 @@ def read_arrow(
 
         Returns:
             DataFrame representation of the read Arrow IPC file.
+
+        Examples:
+            >>> import tempfile, os
+            >>> table = pa.table({"a": [1, 2, 3]})
+            >>> with tempfile.TemporaryDirectory() as tmpdir:
+            ...     path = os.path.join(tmpdir, "data.arrow")
+            ...     with pa.ipc.new_file(path, table.schema) as writer:
+            ...         writer.write_table(table)
+            ...     df = ctx.read_arrow(path)
+            ...     df.collect()[0].column(0)
+            <pyarrow.lib.Int64Array object at ...>
+            [
+              1,
+              2,
+              3
+            ]
         """
         if file_partition_cols is None:
             file_partition_cols = []
@@ -1396,6 +1439,14 @@ def read_empty(self) -> DataFrame:
 
         Returns:
             An empty DataFrame.
+
+        Examples:
+            >>> df = ctx.read_empty()
+            >>> result = df.collect()
+            >>> len(result)
+            1
+            >>> result[0].num_columns
+            0
         """
         return self.empty_table()