feat(bigquery-storage): add deprecation warning for to_dataframe (#18022)

Following the addition of `PendingDeprecationWarning` to
`ReadRowsPage.to_arrow()` in #17938, this PR adds
`PendingDeprecationWarning` to `ReadRowsPage.to_dataframe()` in
`google-cloud-bigquery-storage`.

This notifies developers to adopt direct `pandas-gbq` APIs
(`pandas_gbq.read_gbq()` or
`pandas_gbq.pandas.read_bigquery_stream_batches()`) ahead of future
deprecation phases.

Fixes #< 526614511 > 🦕

Author: shuoweil

packages/google-cloud-bigquery-storage/google/cloud/bigquery_storage_v1/reader.py

@@ -617,6 +617,12 @@ def to_dataframe(self, dtypes=None):
             pandas.DataFrame:
                 A data frame of all rows in the stream.
         """
+        warnings.warn(
+            "Retrieving DataFrames directly via google-cloud-bigquery-storage is deprecated. "
+            "Please use 'pandas_gbq.read_gbq()' or 'pandas_gbq.pandas.read_bigquery_stream_batches()'.",
+            PendingDeprecationWarning,
+            stacklevel=2,
+        )
         if pandas is None:
             raise ImportError(_PANDAS_REQUIRED)
 

packages/google-cloud-bigquery-storage/tests/unit/test_reader_v1.py

@@ -25,7 +25,6 @@
 import pandas
 import pandas.testing
 import pytest
-
 from google.cloud.bigquery_storage import types
 
 from .helpers import SCALAR_BLOCKS, SCALAR_COLUMN_NAMES, SCALAR_COLUMNS
@@ -700,3 +699,20 @@ def test_to_arrow_avro_consumes_first_page(class_under_test, mock_gapic_client):
     # Since read_session was not provided, to_arrow() had to consume the first message
     # to find out it was Avro. So offset should be 1.
     assert reader._offset == 1
+
+
+def test_to_dataframe_emits_pending_deprecation_warning(mut):
+    mock_parser = mock.Mock()
+    mock_message = mock.Mock()
+    mock_df = mock.Mock()
+    mock_parser.to_dataframe.return_value = mock_df
+
+    page = mut.ReadRowsPage(mock_parser, mock_message)
+    with pytest.warns(
+        PendingDeprecationWarning,
+        match="google-cloud-bigquery-storage is deprecated",
+    ):
+        actual_df = page.to_dataframe()
+
+    assert actual_df == mock_df
+    mock_parser.to_dataframe.assert_called_once_with(mock_message, dtypes=None)