feat(bigquery-magics): deprecate --engine=bigframes, run %load_ext bigframes and use %%bqsql magics instead (#16573)

Towards internal issue b/500399391 🦕

---------

Co-authored-by: gemini-code-assist[bot] <176961590+gemini-code-assist[bot]@users.noreply.github.com>

Author: tswast

packages/bigquery-magics/bigquery_magics/bigquery.py

@@ -78,8 +78,10 @@
           the variable name (ex. ``$my_dict_var``). See ``In[6]`` and ``In[7]``
           in the Examples section below.
     * ``--engine <engine>`` (Optional[line argument]):
-          Set the execution engine, either 'pandas' (default) or 'bigframes'
-          (experimental).
+          [Deprecated] Set the execution engine, either 'pandas' (default) or
+          'bigframes'.
+          Please use ``%load_ext bigframes`` and the ``%%bqsql`` magic instead.
+          See: https://dataframes.bigquery.dev/notebooks/getting_started/magics.html
     * ``--pyformat`` (Optional[line argument]):
           Warning! Do not use with user-provided values.
           This doesn't escape values. Use --params instead for proper SQL escaping.
@@ -397,8 +399,10 @@ def _create_dataset_if_necessary(client, dataset_id):
     type=str,
     default=None,
     help=(
-        "Set the execution engine, either 'pandas' or 'bigframes'."
-        "Defaults to engine set in the query setting in console."
+        "[Deprecated] Set the execution engine, either 'pandas' or 'bigframes'. "
+        "Defaults to engine set in the query setting in console. "
+        "Please use %%load_ext bigframes and the %%%%bqsql magic instead. "
+        "See: https://dataframes.bigquery.dev/notebooks/getting_started/magics.html"
     ),
 )
 @magic_arguments.argument(
@@ -510,6 +514,13 @@ def _split_args_line(line: str) -> Tuple[str, str]:
 
 
 def _query_with_bigframes(query: str, params: List[Any], args: Any):
+    warnings.warn(
+        "The bigframes engine is deprecated. Please use %load_ext bigframes "
+        "and the %%bqsql magic instead. "
+        "See: https://dataframes.bigquery.dev/notebooks/getting_started/magics.html",
+        FutureWarning,
+        stacklevel=2,
+    )
     if args.dry_run:
         raise ValueError("Dry run is not supported by bigframes engine.")
 

packages/bigquery-magics/bigquery_magics/config.py

@@ -14,6 +14,7 @@
 
 from dataclasses import dataclass
 from typing import Optional
+import warnings
 
 import google.api_core.client_options as client_options
 import google.cloud.bigquery as bigquery
@@ -183,10 +184,15 @@ def project(self, value):
 
     @property
     def engine(self) -> str:
-        """Engine to run the query. Could either be "pandas" or "bigframes".
+        """[Deprecated] Engine to run the query. Could either be "pandas" or
+        "bigframes".
 
         If using "pandas", the query result will be stored in a Pandas dataframe.
-        If using "bigframes", the query result will be stored in a bigframes dataframe instead.
+        If using "bigframes", the query result will be stored in a bigframes
+        dataframe instead.
+
+        Please use ``%load_ext bigframes`` and the ``%%bqsql`` magic instead.
+        See: https://dataframes.bigquery.dev/notebooks/getting_started/magics.html
 
         Example:
             Manully setting the content engine:
@@ -200,6 +206,14 @@ def engine(self) -> str:
     def engine(self, value):
         if value != "pandas" and value != "bigframes":
             raise ValueError("engine must be either 'pandas' or 'bigframes'")
+        if value == "bigframes":
+            warnings.warn(
+                "The bigframes engine is deprecated. Please use %load_ext bigframes "
+                "and the %%bqsql magic instead. "
+                "See: https://dataframes.bigquery.dev/notebooks/getting_started/magics.html",
+                FutureWarning,
+                stacklevel=2,
+            )
         self._engine = value
 
 

packages/bigquery-magics/tests/unit/bigquery/test_deprecation.py

@@ -0,0 +1,79 @@
+# Copyright 2026 Google LLC
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+import pytest
+
+from bigquery_magics import bigquery as magics
+import bigquery_magics.config
+
+
+@pytest.fixture(autouse=True)
+def mock_bq_client_and_credentials(mock_credentials):
+    from unittest import mock
+
+    with mock.patch("google.cloud.bigquery.Client", autospec=True):
+        with mock.patch("bigquery_magics.core.create_bq_client", autospec=True):
+            yield
+
+
+def test_config_engine_setter_warning():
+    context = bigquery_magics.config.Context()
+    with pytest.warns(FutureWarning, match="The bigframes engine is deprecated"):
+        context.engine = "bigframes"
+
+
+def test_query_with_bigframes_warning(mock_ipython):
+    # Mocking bigframes.pandas since it might not be installed
+    from unittest import mock
+
+    with mock.patch("bigquery_magics.bigquery.bpd") as mock_bpd:
+        mock_bpd.read_gbq_query.return_value = mock.MagicMock()
+
+        args = mock.MagicMock()
+        args.engine = "bigframes"
+        args.dry_run = False
+        args.max_results = None
+        args.destination_var = None
+        args.destination_table = None
+
+        with pytest.warns(FutureWarning, match="The bigframes engine is deprecated"):
+            magics._query_with_bigframes("SELECT 1", [], args)
+
+
+def test_cell_magic_engine_bigframes_warning(mock_ipython):
+    from unittest import mock
+
+    from IPython.testing.globalipapp import get_ipython
+
+    ip = get_ipython()
+    if ip is None:
+        from IPython.testing.globalipapp import start_ipython
+
+        ip = start_ipython()
+
+    ip.extension_manager.load_extension("bigquery_magics")
+
+    # Mock the actual execution to avoid needing real credentials/data
+    with mock.patch("bigquery_magics.bigquery.bpd") as mock_bpd:
+        mock_bpd.read_gbq_query.return_value = mock.MagicMock()
+        with pytest.warns(FutureWarning, match="The bigframes engine is deprecated"):
+            ip.run_cell_magic("bigquery", "--engine bigframes", "SELECT 1")
+
+
+@pytest.fixture
+def mock_ipython():
+    from unittest import mock
+
+    with mock.patch("bigquery_magics.bigquery.get_ipython") as mock_get_ipython:
+        yield mock_get_ipython