docs: add columns for "requires ordering/index" to supported APIs summary (#892)

Author: tswast

bigframes/core/validations.py

@@ -17,14 +17,16 @@
 from __future__ import annotations
 
 import functools
-from typing import Optional, Protocol, TYPE_CHECKING
+from typing import Optional, Protocol, TYPE_CHECKING, Union
 
 import bigframes.constants
 import bigframes.exceptions
 
 if TYPE_CHECKING:
  from bigframes import Session
  from bigframes.core.blocks import Block
+ from bigframes.dataframe import DataFrame
+ from bigframes.operations.base import SeriesMethods
 
 
 class HasSession(Protocol):
@@ -37,13 +39,24 @@ def _block(self) -> Block:
  ...
 
 
+def requires_index(meth):
+ @functools.wraps(meth)
+ def guarded_meth(df: Union[DataFrame, SeriesMethods], *args, **kwargs):
+ df._throw_if_null_index(meth.__name__)
+ return meth(df, *args, **kwargs)
+
+ guarded_meth._validations_requires_index = True # type: ignore
+ return guarded_meth
+
+
 def requires_ordering(suggestion: Optional[str] = None):
  def decorator(meth):
  @functools.wraps(meth)
  def guarded_meth(object: HasSession, *args, **kwargs):
  enforce_ordered(object, meth.__name__, suggestion)
  return meth(object, *args, **kwargs)
 
+ guarded_meth._validations_requires_ordering = True # type: ignore
  return guarded_meth
 
  return decorator

bigframes/dataframe.py

@@ -17,7 +17,6 @@
 from __future__ import annotations
 
 import datetime
-import functools
 import inspect
 import re
 import sys
@@ -92,15 +91,6 @@
 )
 
 
-def requires_index(meth):
- @functools.wraps(meth)
- def guarded_meth(df: DataFrame, *args, **kwargs):
- df._throw_if_null_index(meth.__name__)
- return meth(df, *args, **kwargs)
-
- return guarded_meth
-
-
 # Inherits from pandas DataFrame so that we can use the same docstrings.
 @log_adapter.class_logger
 class DataFrame(vendored_pandas_frame.DataFrame):
@@ -261,7 +251,7 @@ def _sql_names(
  return results
 
  @property
- @requires_index
+ @validations.requires_index
  def index(
  self,
  ) -> indexes.Index:
@@ -277,7 +267,7 @@ def index(self, value):
  self.index.name = value.name if hasattr(value, "name") else None
 
  @property
- @requires_index
+ @validations.requires_index
  def loc(self) -> indexers.LocDataFrameIndexer:
  return indexers.LocDataFrameIndexer(self)
 
@@ -292,7 +282,7 @@ def iat(self) -> indexers.IatDataFrameIndexer:
  return indexers.IatDataFrameIndexer(self)
 
  @property
- @requires_index
+ @validations.requires_index
  def at(self) -> indexers.AtDataFrameIndexer:
  return indexers.AtDataFrameIndexer(self)
 
@@ -348,7 +338,7 @@ def _has_index(self) -> bool:
  def T(self) -> DataFrame:
  return DataFrame(self._get_block().transpose())
 
- @requires_index
+ @validations.requires_index
  @validations.requires_ordering()
  def transpose(self) -> DataFrame:
  return self.T
@@ -417,7 +407,7 @@ def memory_usage(self, index: bool = True):
  column_sizes = pandas.concat([index_size, column_sizes])
  return column_sizes
 
- @requires_index
+ @validations.requires_index
  def info(
  self,
  verbose: Optional[bool] = None,
@@ -1682,7 +1672,7 @@ def set_index(
  col_ids_strs: List[str] = [col_id for col_id in col_ids if col_id is not None]
  return DataFrame(self._block.set_index(col_ids_strs, append=append, drop=drop))
 
- @requires_index
+ @validations.requires_index
  def sort_index(
  self, ascending: bool = True, na_position: Literal["first", "last"] = "last"
  ) -> DataFrame:
@@ -1884,7 +1874,7 @@ def reindex(
  if columns is not None:
  return self._reindex_columns(columns)
 
- @requires_index
+ @validations.requires_index
  def _reindex_rows(
  self,
  index,
@@ -1931,12 +1921,12 @@ def _reindex_columns(self, columns):
  result_df.columns = new_column_index
  return result_df
 
- @requires_index
+ @validations.requires_index
  def reindex_like(self, other: DataFrame, *, validate: typing.Optional[bool] = None):
  return self.reindex(index=other.index, columns=other.columns, validate=validate)
 
  @validations.requires_ordering()
- @requires_index
+ @validations.requires_index
  def interpolate(self, method: str = "linear") -> DataFrame:
  if method == "pad":
  return self.ffill()
@@ -2231,12 +2221,12 @@ def agg(
  aggregate = agg
  aggregate.__doc__ = inspect.getdoc(vendored_pandas_frame.DataFrame.agg)
 
- @requires_index
+ @validations.requires_index
  @validations.requires_ordering()
  def idxmin(self) -> bigframes.series.Series:
  return bigframes.series.Series(block_ops.idxmin(self._block))
 
- @requires_index
+ @validations.requires_index
  @validations.requires_ordering()
  def idxmax(self) -> bigframes.series.Series:
  return bigframes.series.Series(block_ops.idxmax(self._block))
@@ -2345,7 +2335,7 @@ def _pivot(
  )
  return DataFrame(pivot_block)
 
- @requires_index
+ @validations.requires_index
  @validations.requires_ordering()
  def pivot(
  self,
@@ -2360,7 +2350,7 @@ def pivot(
  ) -> DataFrame:
  return self._pivot(columns=columns, index=index, values=values)
 
- @requires_index
+ @validations.requires_index
  @validations.requires_ordering()
  def pivot_table(
  self,
@@ -2460,7 +2450,7 @@ def _stack_multi(self, level: LevelsType = -1):
  block = block.stack(levels=len(level))
  return DataFrame(block)
 
- @requires_index
+ @validations.requires_index
  @validations.requires_ordering()
  def unstack(self, level: LevelsType = -1):
  if not utils.is_list_like(level):
@@ -2711,7 +2701,7 @@ def groupby(
  else:
  raise TypeError("You have to supply one of 'by' and 'level'")
 
- @requires_index
+ @validations.requires_index
  def _groupby_level(
  self,
  level: LevelsType,

bigframes/operations/base.py

@@ -14,7 +14,6 @@
 
 from __future__ import annotations
 
-import functools
 import typing
 from typing import List, Sequence
 
@@ -35,15 +34,6 @@
 import bigframes.session
 
 
-def requires_index(meth):
- @functools.wraps(meth)
- def guarded_meth(df: SeriesMethods, *args, **kwargs):
- df._throw_if_null_index(meth.__name__)
- return meth(df, *args, **kwargs)
-
- return guarded_meth
-
-
 class SeriesMethods:
  def __init__(
  self,

bigframes/series.py

@@ -52,7 +52,6 @@
 import bigframes.operations as ops
 import bigframes.operations.aggregations as agg_ops
 import bigframes.operations.base
-from bigframes.operations.base import requires_index
 import bigframes.operations.datetimes as dt
 import bigframes.operations.plotting as plotting
 import bigframes.operations.strings as strings
@@ -88,7 +87,7 @@ def dtypes(self):
  return self._dtype
 
  @property
- @requires_index
+ @validations.requires_index
  def loc(self) -> bigframes.core.indexers.LocSeriesIndexer:
  return bigframes.core.indexers.LocSeriesIndexer(self)
 
@@ -103,7 +102,7 @@ def iat(self) -> bigframes.core.indexers.IatSeriesIndexer:
  return bigframes.core.indexers.IatSeriesIndexer(self)
 
  @property
- @requires_index
+ @validations.requires_index
  def at(self) -> bigframes.core.indexers.AtSeriesIndexer:
  return bigframes.core.indexers.AtSeriesIndexer(self)
 
@@ -142,7 +141,7 @@ def values(self) -> numpy.ndarray:
  return self.to_numpy()
 
  @property
- @requires_index
+ @validations.requires_index
  def index(self) -> indexes.Index:
  return indexes.Index.from_frame(self)
 
@@ -245,7 +244,7 @@ def rename(
 
  raise ValueError(f"Unsupported type of parameter index: {type(index)}")
 
- @requires_index
+ @validations.requires_index
  def rename_axis(
  self,
  mapper: typing.Union[blocks.Label, typing.Sequence[blocks.Label]],
@@ -404,12 +403,12 @@ def drop(
  block = block.drop_columns([condition_id])
  return Series(block.select_column(self._value_column))
 
- @requires_index
+ @validations.requires_index
  def droplevel(self, level: LevelsType, axis: int | str = 0):
  resolved_level_ids = self._resolve_levels(level)
  return Series(self._block.drop_levels(resolved_level_ids))
 
- @requires_index
+ @validations.requires_index
  def swaplevel(self, i: int = -2, j: int = -1):
  level_i = self._block.index_columns[i]
  level_j = self._block.index_columns[j]
@@ -419,7 +418,7 @@ def swaplevel(self, i: int = -2, j: int = -1):
  ]
  return Series(self._block.reorder_levels(reordering))
 
- @requires_index
+ @validations.requires_index
  def reorder_levels(self, order: LevelsType, axis: int | str = 0):
  resolved_level_ids = self._resolve_levels(order)
  return Series(self._block.reorder_levels(resolved_level_ids))
@@ -609,7 +608,7 @@ def _mapping_replace(self, mapping: dict[typing.Hashable, typing.Hashable]):
  return Series(block.select_column(result))
 
  @validations.requires_ordering()
- @requires_index
+ @validations.requires_index
  def interpolate(self, method: str = "linear") -> Series:
  if method == "pad":
  return self.ffill()
@@ -1162,7 +1161,7 @@ def argmin(self) -> int:
  scalars.Scalar, Series(block.select_column(row_nums)).iloc[0]
  )
 
- @requires_index
+ @validations.requires_index
  def unstack(self, level: LevelsType = -1):
  if isinstance(level, int) or isinstance(level, str):
  level = [level]
@@ -1186,7 +1185,7 @@ def unstack(self, level: LevelsType = -1):
  )
  return bigframes.dataframe.DataFrame(pivot_block)
 
- @requires_index
+ @validations.requires_index
  def idxmax(self) -> blocks.Label:
  block = self._block.order_by(
  [
@@ -1200,7 +1199,7 @@ def idxmax(self) -> blocks.Label:
  block = block.slice(0, 1)
  return indexes.Index(block).to_pandas()[0]
 
- @requires_index
+ @validations.requires_index
  def idxmin(self) -> blocks.Label:
  block = self._block.order_by(
  [
@@ -1314,7 +1313,7 @@ def sort_values(
  )
  return Series(block)
 
- @requires_index
+ @validations.requires_index
  def sort_index(self, *, axis=0, ascending=True, na_position="last") -> Series:
  # TODO(tbergeron): Support level parameter once multi-index introduced.
  if na_position not in ["first", "last"]:
@@ -1377,7 +1376,7 @@ def groupby(
  else:
  raise TypeError("You have to supply one of 'by' and 'level'")
 
- @requires_index
+ @validations.requires_index
  def _groupby_level(
  self,
  level: int | str | typing.Sequence[int] | typing.Sequence[str],
@@ -1518,11 +1517,11 @@ def combine(
  materialized_series = result_series._cached()
  return materialized_series
 
- @requires_index
+ @validations.requires_index
  def add_prefix(self, prefix: str, axis: int | str | None = None) -> Series:
  return Series(self._get_block().add_prefix(prefix))
 
- @requires_index
+ @validations.requires_index
  def add_suffix(self, suffix: str, axis: int | str | None = None) -> Series:
  return Series(self._get_block().add_suffix(suffix))
 
@@ -1574,7 +1573,7 @@ def filter(
  else:
  raise ValueError("Need to provide 'items', 'like', or 'regex'")
 
- @requires_index
+ @validations.requires_index
  def reindex(self, index=None, *, validate: typing.Optional[bool] = None):
  if validate and not self.index.is_unique:
  raise ValueError("Original index must be unique to reindex")
@@ -1603,7 +1602,7 @@ def reindex(self, index=None, *, validate: typing.Optional[bool] = None):
  )._block
  return Series(result_block)
 
- @requires_index
+ @validations.requires_index
  def reindex_like(self, other: Series, *, validate: typing.Optional[bool] = None):
  return self.reindex(other.index, validate=validate)