Skip to content

Commit

Permalink
docs: update DataFrame docstrings to include the errors section (#1127
Browse files Browse the repository at this point in the history 
)

* docs: update DataFrame docstrings to include the errors section.

* Fix markup

* Update third_party/bigframes_vendored/pandas/core/frame.py

---------

Co-authored-by: Tim Sweña (Swast) <[email protected]>
  • Loading branch information
@arwas11 @tswast
arwas11 and tswast authored Nov 6, 2024
1 parent 65e2e70 commit a38d4c4
Show file tree
Hide file tree
Showing 2 changed files with 201 additions and 26 deletions.
210 changes: 186 additions & 24 deletions third_party/bigframes_vendored/pandas/core/frame.py
View file
Original file line number Diff line number Diff line change
Expand Up @@ -487,6 +487,19 @@ def to_gbq(
str:
The fully-qualified ID for the written table, in the form
``project.dataset.tablename``.
Raises:
ValueError:
If an invalid value is provided for ``if_exists`` when ``destination_table``
is ``None``. ``None`` or ``replace`` are the only valid values for ``if_exists``.
ValueError:
If an invalid value is provided for ``destination_table`` that is
not one of ``datasetID.tableId`` or ``projectId.datasetId.tableId``.
ValueError:
If an invalid value is provided for ``if_exists`` that is not one of
``fail``, ``replace``, or ``append``.
"""
raise NotImplementedError(constants.ABSTRACT_METHOD_ERROR_MESSAGE)

Expand Down Expand Up @@ -531,7 +544,13 @@ def to_parquet(
If ``False``, they will not be written to the file.
Returns:
None or bytes: bytes if no path argument is provided else None
None or bytes:
bytes if no path argument is provided else None
Raises:
ValueError:
If an invalid value provided for `compression` that is not one of
``None``, ``snappy``, or ``gzip``.
"""
raise NotImplementedError(constants.ABSTRACT_METHOD_ERROR_MESSAGE)

Expand Down Expand Up @@ -1140,9 +1159,11 @@ def insert(self, loc, column, value, allow_duplicates=False):
Allow duplicate column labels to be created.
Raises:
IndexError:
If ``column`` index is out of bounds with the total count of columns.
ValueError:
If `column` is already contained in the DataFrame,
unless `allow_duplicates` is set to True.
If ``column`` is already contained in the DataFrame,
unless ``allow_duplicates`` is set to True.
"""
raise NotImplementedError(constants.ABSTRACT_METHOD_ERROR_MESSAGE)

Expand Down Expand Up @@ -1259,10 +1280,14 @@ def drop(
level:
For MultiIndex, level from which the labels will be removed.
Returns:
bigframes.pandas.DataFrame: DataFrame without the removed column labels.
bigframes.pandas.DataFrame:
DataFrame without the removed column labels.
Raises:
KeyError: If any of the labels is not found in the selected axis.
ValueError: If values for both ``labels`` and ``index``/``columns`` are provided.
ValueError: If a multi-index tuple is provided as ``level``.
ValueError: If either ``labels`` or ``index``/``columns`` is not provided.
"""
raise NotImplementedError(constants.ABSTRACT_METHOD_ERROR_MESSAGE)

Expand Down Expand Up @@ -1419,7 +1444,12 @@ def set_index(
Delete columns to be used as the new index.
Returns:
bigframes.pandas.DataFrame: Changed row labels.
bigframes.pandas.DataFrame:
Changed row labels.
Raises:
KeyError:
If key(s) are not in the columns.
"""
raise NotImplementedError(constants.ABSTRACT_METHOD_ERROR_MESSAGE)

Expand All @@ -1437,7 +1467,12 @@ def reorder_levels(
Where to reorder levels.
Returns:
bigframes.pandas.DataFrame: DataFrame of rearranged index.
bigframes.pandas.DataFrame:
DataFrame of rearranged index.
Raises:
ValueError:
If columns are not multi-index.
"""
raise NotImplementedError(constants.ABSTRACT_METHOD_ERROR_MESSAGE)

Expand All @@ -1455,7 +1490,12 @@ def swaplevel(self, i, j, axis: str | int = 0) -> DataFrame:
'columns' for column-wise.
Returns:
bigframes.pandas.DataFrame: DataFrame with levels swapped in MultiIndex.
bigframes.pandas.DataFrame:
DataFrame with levels swapped in MultiIndex.
Raises:
ValueError:
If columns are not multi-index.
"""
raise NotImplementedError(constants.ABSTRACT_METHOD_ERROR_MESSAGE)

Expand All @@ -1474,7 +1514,12 @@ def droplevel(self, level, axis: str | int = 0):
* 0 or 'index': remove level(s) in column.
* 1 or 'columns': remove level(s) in row.
Returns:
bigframes.pandas.DataFrame: DataFrame with requested index / column level(s) removed.
bigframes.pandas.DataFrame:
DataFrame with requested index / column level(s) removed.
Raises:
ValueError:
If columns are not multi-index
"""
raise NotImplementedError(constants.ABSTRACT_METHOD_ERROR_MESSAGE)

Expand Down Expand Up @@ -1724,7 +1769,12 @@ def dropna(
Returns:
bigframes.pandas.DataFrame: DataFrame with NA entries dropped from it.
bigframes.pandas.DataFrame:
DataFrame with NA entries dropped from it.
Raises:
ValueError:
If ``how`` is not one of ``any`` or ``all``.
"""
raise NotImplementedError(constants.ABSTRACT_METHOD_ERROR_MESSAGE)

Expand Down Expand Up @@ -1772,8 +1822,13 @@ def isin(self, values):
the column names, which must match.
Returns:
bigframes.pandas.DataFrame: DataFrame of booleans showing whether each element
in the DataFrame is contained in values.
bigframes.pandas.DataFrame:
DataFrame of booleans showing whether each element
in the DataFrame is contained in values.
Raises:
TypeError:
If values provided are not list-like objects.
"""
raise NotImplementedError(constants.ABSTRACT_METHOD_ERROR_MESSAGE)

Expand Down Expand Up @@ -2004,7 +2059,12 @@ def sort_values(
if `first`; `last` puts NaNs at the end.
Returns:
bigframes.pandas.DataFrame: DataFrame with sorted values.
bigframes.pandas.DataFrame:
DataFrame with sorted values.
Raises:
ValueError:
If value of ``na_position`` is not one of ``first`` or ``last``.
"""
raise NotImplementedError(constants.ABSTRACT_METHOD_ERROR_MESSAGE)

Expand All @@ -2014,7 +2074,14 @@ def sort_index(
"""Sort object by labels (along an axis).
Returns:
bigframes.pandas.DataFrame: The original DataFrame sorted by the labels.
bigframes.pandas.DataFrame:
The original DataFrame sorted by the labels.
Raises:
ValueError:
If value of ``na_position`` is not one of ``first`` or ``last``.
ValueError:
If length of ``ascending`` dose not equal length of ``by``.
"""
raise NotImplementedError(constants.ABSTRACT_METHOD_ERROR_MESSAGE)

Expand Down Expand Up @@ -3727,7 +3794,12 @@ def combine(
overwritten with NaNs.
Returns:
bigframes.pandas.DataFrame: Combination of the provided DataFrames.
bigframes.pandas.DataFrame:
Combination of the provided DataFrames.
Raises:
ValueError:
If ``func`` return value is not Series.
"""
raise NotImplementedError(constants.ABSTRACT_METHOD_ERROR_MESSAGE)

Expand Down Expand Up @@ -3813,8 +3885,17 @@ def explode(
If True, the resulting index will be labeled 0, 1, …, n - 1.
Returns:
bigframes.pandas.DataFrame: Exploded lists to rows of the subset columns;
bigframes.pandas.DataFrame:
Exploded lists to rows of the subset columns;
index will be duplicated for these rows.
Raises:
ValueError:
* If columns of the frame are not unique.
* If specified columns to explode is empty list.
* If specified columns to explode have not matching count of elements rowwise in the frame.
KeyError:
If incorrect column names are provided
"""
raise NotImplementedError(constants.ABSTRACT_METHOD_ERROR_MESSAGE)

Expand Down Expand Up @@ -3929,6 +4010,10 @@ def update(
Returns:
None: This method directly changes calling object.
Raises:
ValueError:
If a type of join other than ``left`` is provided as an argument.
"""
raise NotImplementedError(constants.ABSTRACT_METHOD_ERROR_MESSAGE)

Expand Down Expand Up @@ -4023,7 +4108,14 @@ def groupby(
values will also be treated as the key in groups.
Returns:
bigframes.core.groupby.SeriesGroupBy: A groupby object that contains information about the groups.
bigframes.core.groupby.SeriesGroupBy:
A groupby object that contains information about the groups.
Raises:
ValueError:
If both ``by`` and ``level`` are specified.
TypeError:
If one of ``by`` or `level`` is not specified.
"""
raise NotImplementedError(constants.ABSTRACT_METHOD_ERROR_MESSAGE)

Expand Down Expand Up @@ -4109,7 +4201,14 @@ def map(self, func, na_action: Optional[str] = None) -> DataFrame:
values, without passing them to func.
Returns:
bigframes.pandas.DataFrame: Transformed DataFrame.
bigframes.pandas.DataFrame:
Transformed DataFrame.
Raises:
TypeError:
If value provided for ``func`` is not callable.
ValueError:
If value provided for ``na_action`` is not ``None`` or ``ignore``.
"""
raise NotImplementedError(constants.ABSTRACT_METHOD_ERROR_MESSAGE)

Expand Down Expand Up @@ -4209,7 +4308,18 @@ def join(self, other, *, on: Optional[str] = None, how: str) -> DataFrame:
the order of the left keys.
Returns:
bigframes.pandas.DataFrame: A dataframe containing columns from both the caller and `other`.
bigframes.pandas.DataFrame:
A dataframe containing columns from both the caller and `other`.
Raises:
ValueError:
If value for ``on`` is specified for cross join.
ValueError:
If join on columns does not match the index level of the other
DataFrame. Join on columns with multi-index is not supported.
ValueError:
If left index to join on does not have the same number of levels
as the right index.
"""
raise NotImplementedError(constants.ABSTRACT_METHOD_ERROR_MESSAGE)

Expand Down Expand Up @@ -4354,7 +4464,20 @@ def merge(
no suffix. At least one of the values must not be None.
Returns:
bigframes.pandas.DataFrame: A DataFrame of the two merged objects.
bigframes.pandas.DataFrame:
A DataFrame of the two merged objects.
Raises:
ValueError:
If value for ``on`` is specified for cross join.
ValueError:
If ``on`` or ``left_on`` + ``right_on`` are not specified when ``on`` is ``None``.
ValueError:
If ``on`` and ``left_on`` + ``right_on`` are specified when ``on`` is not ``None``.
ValueError:
If no column with the provided label is found in ``self`` for left join.
ValueError:
If no column with the provided label is found in ``self`` for right join.
"""
raise NotImplementedError(constants.ABSTRACT_METHOD_ERROR_MESSAGE)

Expand Down Expand Up @@ -4469,6 +4592,16 @@ def apply(self, func, *, axis=0, args=(), **kwargs):
Returns:
bigframes.pandas.DataFrame or bigframes.pandas.Series:
Result of applying ``func`` along the given axis of the DataFrame.
Raises:
ValueError:
If a remote function is not provided when ``axis=1`` is specified.
ValueError:
If number or input params in the remote function are not the same as
the number of columns in the dataframe.
ValueError:
If the dtypes of the columns in the dataframe are not compatible with
the data types of the remote function input params.
"""
raise NotImplementedError(constants.ABSTRACT_METHOD_ERROR_MESSAGE)

Expand Down Expand Up @@ -5156,7 +5289,12 @@ def nlargest(self, n: int, columns, keep: str = "first"):
selecting more than `n` items.
Returns:
bigframes.pandas.DataFrame: The first `n` rows ordered by the given columns in descending order.
bigframes.pandas.DataFrame:
The first `n` rows ordered by the given columns in descending order.
Raises:
ValueError:
If value of ``keep`` is not ``first``, ``last``, or ``all``.
"""
raise NotImplementedError(constants.ABSTRACT_METHOD_ERROR_MESSAGE)

Expand Down Expand Up @@ -5244,7 +5382,12 @@ def nsmallest(self, n: int, columns, keep: str = "first"):
selecting more than `n` items.
Returns:
bigframes.pandas.DataFrame: The first `n` rows ordered by the given columns in ascending order.
bigframes.pandas.DataFrame:
The first `n` rows ordered by the given columns in ascending order.
Raises:
ValueError:
If value of ``keep`` is not ``first``, ``last``, or ``all``.
"""
raise NotImplementedError(constants.ABSTRACT_METHOD_ERROR_MESSAGE)

Expand Down Expand Up @@ -5513,7 +5656,12 @@ def cumsum(self) -> DataFrame:
[3 rows x 2 columns]
Returns:
bigframes.pandas.DataFrame: Return cumulative sum of DataFrame.
bigframes.pandas.DataFrame:
Return cumulative sum of DataFrame.
Raises:
ValueError:
If values are not of numeric type.
"""
raise NotImplementedError(constants.ABSTRACT_METHOD_ERROR_MESSAGE)

Expand Down Expand Up @@ -5545,7 +5693,12 @@ def cumprod(self) -> DataFrame:
[3 rows x 2 columns]
Returns:
bigframes.pandas.DataFrame: Return cumulative product of DataFrame.
bigframes.pandas.DataFrame:
Return cumulative product of DataFrame.
Raises:
ValueError:
If values are not of numeric type.
"""
raise NotImplementedError(constants.ABSTRACT_METHOD_ERROR_MESSAGE)

Expand Down Expand Up @@ -5695,7 +5848,12 @@ def describe(self):
[8 rows x 2 columns]
Returns:
bigframes.pandas.DataFrame: Summary statistics of the Series or Dataframe provided.
bigframes.pandas.DataFrame:
Summary statistics of the Series or Dataframe provided.
Raises:
ValueError:
If unsupported ``include`` type is provided.
"""
raise NotImplementedError(constants.ABSTRACT_METHOD_ERROR_MESSAGE)

Expand Down Expand Up @@ -6679,6 +6837,10 @@ def dot(self, other):
If `other` is a Series, return the matrix product between self and
other as a Series. If other is a DataFrame, return
the matrix product of self and other in a DataFrame.
Raises:
RuntimeError:
If unable to construct all columns.
"""
raise NotImplementedError(constants.ABSTRACT_METHOD_ERROR_MESSAGE)

Expand Down
Loading

0 comments on commit a38d4c4

Please sign in to comment.