refactor: Decorator to take docs rather than inheritance

Author: TrevorBergeron

bigframes/_tools/docs.py

@@ -0,0 +1,48 @@
+# Copyright 2026 Google LLC
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+
+def inherit_docs(source_class):
+    """
+    A class decorator that copies docstrings from source_class to the
+    decorated class for any methods or attributes that match names.
+    """
+
+    def decorator(target_class):
+        # 1. Steal the main class docstring if the target doesn't have one
+        if not target_class.__doc__ and source_class.__doc__:
+            target_class.__doc__ = source_class.__doc__
+
+        # 2. Iterate over all attributes in the source class
+        for name, source_item in vars(source_class).items():
+            # Check if the target class has the same attribute
+            if name in vars(target_class):
+                target_item = getattr(target_class, name)
+
+                # Only copy if the target doesn't have a docstring
+                # and the source does
+                if hasattr(target_item, "__doc__") and not target_item.__doc__:
+                    if hasattr(source_item, "__doc__") and source_item.__doc__:
+                        try:
+                            # Use functools.update_wrapper or manual assignment
+                            # for methods, properties, and static methods
+                            target_item.__doc__ = source_item.__doc__
+                        except AttributeError:
+                            # Read-only attributes or certain built-ins
+                            # might skip docstring assignment
+                            pass
+
+        return target_class
+
+    return decorator

bigframes/core/groupby/dataframe_group_by.py

@@ -24,6 +24,7 @@
 import pandas as pd
 
 from bigframes import session
+from bigframes._tools import docs
 from bigframes.core import agg_expressions
 from bigframes.core import expression as ex
 import bigframes.core.block_transforms as block_ops
@@ -44,9 +45,8 @@
 
 
 @log_adapter.class_logger
-class DataFrameGroupBy(vendored_pandas_groupby.DataFrameGroupBy):
-    __doc__ = vendored_pandas_groupby.GroupBy.__doc__
-
+@docs.inherit_docs(vendored_pandas_groupby.DataFrameGroupBy)
+class DataFrameGroupBy:
     def __init__(
         self,
         block: blocks.Block,

bigframes/core/groupby/series_group_by.py

@@ -24,6 +24,7 @@
 import pandas
 
 from bigframes import session
+from bigframes._tools import docs
 from bigframes.core import expression as ex
 import bigframes.core.block_transforms as block_ops
 import bigframes.core.blocks as blocks
@@ -43,9 +44,8 @@
 
 
 @log_adapter.class_logger
+@docs.inherit_docs(vendored_pandas_groupby.SeriesGroupBy)
 class SeriesGroupBy(vendored_pandas_groupby.SeriesGroupBy):
-    __doc__ = vendored_pandas_groupby.GroupBy.__doc__
-
     def __init__(
         self,
         block: blocks.Block,

bigframes/core/indexes/base.py

@@ -27,6 +27,7 @@
 import pandas
 
 from bigframes import dtypes
+from bigframes._tools import docs
 import bigframes.core.agg_expressions as ex_types
 import bigframes.core.block_transforms as block_ops
 import bigframes.core.blocks as blocks
@@ -47,8 +48,8 @@
     import bigframes.series
 
 
-class Index(vendored_pandas_index.Index):
-    __doc__ = vendored_pandas_index.Index.__doc__
+@docs.inherit_docs(vendored_pandas_index.Index)
+class Index:
     _query_job = None
     _block: blocks.Block
     _linked_frame: Union[

bigframes/core/indexes/datetimes.py

@@ -20,13 +20,14 @@
     datetimes as vendored_pandas_datetime_index,
 )
 
+from bigframes._tools import docs
 from bigframes.core import expression as ex
 from bigframes.core.indexes.base import Index
 from bigframes.operations import date_ops
 
 
-class DatetimeIndex(Index, vendored_pandas_datetime_index.DatetimeIndex):
-    __doc__ = vendored_pandas_datetime_index.DatetimeIndex.__doc__
+@docs.inherit_docs(vendored_pandas_datetime_index.DatetimeIndex)
+class DatetimeIndex(Index):
 
     # Must be above 5000 for pandas to delegate to bigframes for binops
     __pandas_priority__ = 12000

bigframes/core/indexes/multi.py

@@ -19,6 +19,7 @@
 import bigframes_vendored.pandas.core.indexes.multi as vendored_pandas_multindex
 import pandas
 
+from bigframes._tools import docs
 from bigframes.core import blocks
 from bigframes.core import expression as ex
 from bigframes.core.indexes.base import Index
@@ -27,9 +28,8 @@
     import bigframes.session
 
 
-class MultiIndex(Index, vendored_pandas_multindex.MultiIndex):
-    __doc__ = vendored_pandas_multindex.MultiIndex.__doc__
-
+@docs.inherit_docs(vendored_pandas_multindex.MultiIndex)
+class MultiIndex(Index):
     @classmethod
     def from_tuples(
         cls,

bigframes/core/window/rolling.py

@@ -22,6 +22,7 @@
 import pandas
 
 from bigframes import dtypes
+from bigframes._tools import docs
 from bigframes.core import agg_expressions
 from bigframes.core import expression as ex
 from bigframes.core import ordering, utils, window_spec
@@ -36,9 +37,8 @@
 
 
 @log_adapter.class_logger
-class Window(vendored_pandas_rolling.Window):
-    __doc__ = vendored_pandas_rolling.Window.__doc__
-
+@docs.inherit_docs(vendored_pandas_rolling.Window)
+class Window:
     def __init__(
         self,
         block: blocks.Block,