From bf93e808daad2454e5c1aa933e0d2164d63084e7 Mon Sep 17 00:00:00 2001 From: Arwa Sharif <146148342+arwas11@users.noreply.github.com> Date: Tue, 22 Oct 2024 14:48:37 -0500 Subject: [PATCH] docs: Update docstrings of Session and related files (#1087) * docs: Update docstrings * Remove extra empty lines * Remove extra line * Fix docstrings return type description --- bigframes/session/__init__.py | 24 +++++++++++++++++++ .../bigframes_vendored/pandas/io/gbq.py | 2 +- .../bigframes_vendored/pandas/io/parquet.py | 2 +- .../pandas/io/parsers/readers.py | 15 +++++++++--- .../bigframes_vendored/pandas/io/pickle.py | 2 +- 5 files changed, 39 insertions(+), 6 deletions(-) diff --git a/bigframes/session/__init__.py b/bigframes/session/__init__.py index 27707c21fd..419e9d9a3b 100644 --- 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 index 47a6013c4c..4bd4353413 100644 --- 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 index 1f5563c962..aec911d2fe 100644 --- 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 index 35b2a1982a..90154d8a00 100644 --- 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 index 88684309f9..32ff2666c0 100644 --- 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)