Revert "UNPICK changes to review"

This reverts commit e637505.

Author: kosiew

docs/source/user-guide/dataframe/index.rst

@@ -228,6 +228,33 @@ Core Classes
     * :py:meth:`~datafusion.SessionContext.from_pandas` - Create from Pandas DataFrame
     * :py:meth:`~datafusion.SessionContext.from_arrow` - Create from Arrow data
 
+    ``SessionContext`` can automatically resolve SQL table names that match
+    in-scope Python data objects. When automatic lookup is enabled, a query
+    such as ``ctx.sql("SELECT * FROM pdf")`` will register a pandas or
+    PyArrow object named ``pdf`` without calling
+    :py:meth:`~datafusion.SessionContext.from_pandas` or
+    :py:meth:`~datafusion.SessionContext.from_arrow` explicitly. This requires
+    the corresponding library (``pandas`` for pandas objects, ``pyarrow`` for
+    Arrow objects) to be installed.
+
+    .. code-block:: python
+
+        import pandas as pd
+        from datafusion import SessionContext
+
+        ctx = SessionContext(auto_register_python_objects=True)
+        pdf = pd.DataFrame({"value": [1, 2, 3]})
+
+        df = ctx.sql("SELECT SUM(value) AS total FROM pdf")
+        print(df.to_pandas())  # automatically registers `pdf`
+
+    Automatic lookup is disabled by default. Enable it by passing
+    ``auto_register_python_objects=True`` when constructing the session or by
+    configuring :py:class:`~datafusion.SessionConfig` with
+    :py:meth:`~datafusion.SessionConfig.with_python_table_lookup`. Use
+    :py:meth:`~datafusion.SessionContext.set_python_table_lookup` to toggle the
+    behaviour at runtime.
+
     See: :py:class:`datafusion.SessionContext`
 
 Expression Classes

docs/source/user-guide/sql.rst

@@ -36,4 +36,29 @@ DataFusion also offers a SQL API, read the full reference `here <https://arrow.a
     df = ctx.sql('SELECT "Attack"+"Defense", "Attack"-"Defense" FROM pokemon')
 
     # collect and convert to pandas DataFrame
-    df.to_pandas()
+    df.to_pandas()
+
+Automatic variable registration
+-------------------------------
+
+You can opt-in to DataFusion automatically registering Arrow-compatible Python
+objects that appear in SQL queries. This removes the need to call
+``register_*`` helpers explicitly when working with in-memory data structures.
+
+.. code-block:: python
+
+    import pyarrow as pa
+    from datafusion import SessionContext
+
+    ctx = SessionContext(auto_register_python_objects=True)
+
+    orders = pa.Table.from_pydict({"item": ["apple", "pear"], "qty": [5, 2]})
+
+    result = ctx.sql("SELECT item, qty FROM orders WHERE qty > 2")
+    print(result.to_pandas())
+
+The feature inspects the call stack for variables whose names match missing
+tables and registers them if they expose Arrow data (including pandas and
+Polars DataFrames). Existing contexts can enable or disable the behavior at
+runtime through :py:meth:`SessionContext.set_python_table_lookup` or by passing
+``auto_register_python_objects`` when constructing the session.