docs: Update docstrings of Session and related files (#1087)

* docs: Update docstrings * Remove extra empty lines * Remove extra line * Fix docstrings return type description
googleapis · Oct 22, 2024 · bf93e80 · bf93e80
1 parent 2a0ffac
commit bf93e80
Show file tree

Hide file tree

Showing 5 changed files with 39 additions and 6 deletions.
diff --git a/bigframes/session/__init__.py b/bigframes/session/__init__.py
@@ -477,6 +477,14 @@ def read_gbq_query(
             [2 rows x 3 columns]
 
         See also: :meth:`Session.read_gbq`.
+
+        Returns:
+            bigframes.pandas.DataFrame:
+                A DataFrame representing results of the query or table.
+
+        Raises:
+            ValueError:
+                When both columns (preferred) and col_order are specified.
         """
         # NOTE: This method doesn't (yet) exist in pandas or pandas-gbq, so
         # these docstrings are inline.
@@ -521,6 +529,14 @@ def read_gbq_table(
             >>> df = bpd.read_gbq_table("bigquery-public-data.ml_datasets.penguins")
 
         See also: :meth:`Session.read_gbq`.
+
+        Returns:
+            bigframes.pandas.DataFrame:
+                A DataFrame representing results of the query or table.
+
+        Raises:
+            ValueError:
+                When both columns (preferred) and col_order are specified.
         """
         # NOTE: This method doesn't (yet) exist in pandas or pandas-gbq, so
         # these docstrings are inline.
@@ -557,6 +573,10 @@ def read_gbq_table_streaming(
             >>> bpd.options.display.progress_bar = None
 
             >>> sdf = bst.read_gbq_table("bigquery-public-data.ml_datasets.penguins")
+
+        Returns:
+            bigframes.streaming.dataframe.StreamingDataFrame:
+               A StreamingDataFrame representing results of the table.
         """
         warnings.warn(
             "The bigframes.streaming module is a preview feature, and subject to change.",
@@ -654,6 +674,10 @@ def read_pandas(
 
         Returns:
             An equivalent bigframes.pandas.(DataFrame/Series/Index) object
+
+        Raises:
+            ValueError:
+                When the object is not a Pandas DataFrame.
         """
         import bigframes.series as series
 

diff --git a/third_party/bigframes_vendored/pandas/io/gbq.py b/third_party/bigframes_vendored/pandas/io/gbq.py
@@ -162,6 +162,6 @@ def read_gbq(
                 or partitioned tables without primary keys.
 
         Returns:
-            bigframes.dataframe.DataFrame: A DataFrame representing results of the query or table.
+            bigframes.pandas.DataFrame: A DataFrame representing results of the query or table.
         """
         raise NotImplementedError(constants.ABSTRACT_METHOD_ERROR_MESSAGE)
diff --git a/third_party/bigframes_vendored/pandas/io/parquet.py b/third_party/bigframes_vendored/pandas/io/parquet.py
@@ -41,6 +41,6 @@ def read_parquet(
                 order is not preserved. Default, ``'auto'``.
 
         Returns:
-            bigframes.dataframe.DataFrame: A BigQuery DataFrames.
+            bigframes.pandas.DataFrame: A BigQuery DataFrames.
         """
         raise NotImplementedError(constants.ABSTRACT_METHOD_ERROR_MESSAGE)
diff --git a/third_party/bigframes_vendored/pandas/io/parsers/readers.py b/third_party/bigframes_vendored/pandas/io/parsers/readers.py
@@ -145,9 +145,13 @@ def read_csv(
             **kwargs:
                 keyword arguments for `pandas.read_csv` when not using the BigQuery engine.
 
-
         Returns:
-            bigframes.dataframe.DataFrame: A BigQuery DataFrames.
+            bigframes.pandas.DataFrame: A BigQuery DataFrames.
+
+        Raises:
+            bigframes.exceptions.DefaultIndexWarning:
+                Using the default index is discouraged, such as with clustered
+                or partitioned tables without primary keys.
         """
         raise NotImplementedError(constants.ABSTRACT_METHOD_ERROR_MESSAGE)
 
@@ -226,7 +230,12 @@ def read_json(
                 keyword arguments for `pandas.read_json` when not using the BigQuery engine.
 
         Returns:
-            bigframes.dataframe.DataFrame:
+            bigframes.pandas.DataFrame:
                 The DataFrame representing JSON contents.
+
+        Raises:
+            bigframes.exceptions.DefaultIndexWarning:
+                Using the default index is discouraged, such as with clustered
+                or partitioned tables without primary keys.
         """
         raise NotImplementedError(constants.ABSTRACT_METHOD_ERROR_MESSAGE)
diff --git a/third_party/bigframes_vendored/pandas/io/pickle.py b/third_party/bigframes_vendored/pandas/io/pickle.py
@@ -64,7 +64,7 @@ def read_pickle(
                 examples on storage options refer here.
 
         Returns:
-            bigframes.dataframe.DataFrame or bigframes.series.Series: same type as object
+            bigframes.pandas.DataFrame or bigframes.pandas.Series: same type as object
                 stored in file.
         """
         raise NotImplementedError(constants.ABSTRACT_METHOD_ERROR_MESSAGE)