experiment with module-level templates

Author: tswast

bigframes/bigquery/__init__.py

@@ -105,7 +105,51 @@
     struct,
 ]
 
-__all__ = [f.__name__ for f in _functions] + ["ai"]
+__all__ = [
+    # approximate aggregate ops
+    "approx_top_count",
+    # array ops
+    "array_agg",
+    "array_length",
+    "array_to_string",
+    # datetime ops
+    "unix_micros",
+    "unix_millis",
+    "unix_seconds",
+    # geo ops
+    "st_area",
+    "st_buffer",
+    "st_centroid",
+    "st_convexhull",
+    "st_difference",
+    "st_distance",
+    "st_intersection",
+    "st_isclosed",
+    "st_length",
+    "st_regionstats",
+    "st_simplify",
+    # json ops
+    "json_extract",
+    "json_extract_array",
+    "json_extract_string_array",
+    "json_query",
+    "json_query_array",
+    "json_set",
+    "json_value",
+    "json_value_array",
+    "parse_json",
+    "to_json",
+    "to_json_string",
+    # search ops
+    "create_vector_index",
+    "vector_search",
+    # sql ops
+    "sql_scalar",
+    # struct ops
+    "struct",
+    # Modules / SQL namespaces
+    "ai",
+]
 
 _module = sys.modules[__name__]
 for f in _functions:

bigframes/enums.py

@@ -21,7 +21,7 @@
 
 
 class OrderingMode(enum.Enum):
-    """[Preview] Values used to determine the ordering mode.
+    """Values used to determine the ordering mode.
 
     Default is 'strict'.
     """
@@ -37,5 +37,6 @@ class DefaultIndexKind(enum.Enum):
     #: ``n - 3``, ``n - 2``, ``n - 1``, where ``n`` is the number of items in
     #: the index.
     SEQUENTIAL_INT64 = enum.auto()
+
     # A completely null index incapable of indexing or alignment.
     NULL = enum.auto()

bigframes/exceptions.py

@@ -127,7 +127,9 @@ class FunctionPackageVersionWarning(PreviewWarning):
 
 
 def format_message(message: str, fill: bool = True):
-    """Formats a warning message with ANSI color codes for the warning color.
+    """[Private] Formats a warning message.
+
+    :meta private:
 
     Args:
         message: The warning message string.

bigframes/streaming/__init__.py

@@ -12,8 +12,12 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 
+from __future__ import annotations
+
 import inspect
+import sys
 
+from bigframes.core import log_adapter
 import bigframes.core.global_session as global_session
 from bigframes.pandas.io.api import _set_default_session_location_if_possible
 import bigframes.session
@@ -32,3 +36,12 @@ def read_gbq_table(table: str) -> streaming_dataframe.StreamingDataFrame:
 )
 
 StreamingDataFrame = streaming_dataframe.StreamingDataFrame
+
+_module = sys.modules[__name__]
+_functions = [read_gbq_table]
+
+for _function in _functions:
+    _decorated_object = log_adapter.method_logger(_function, custom_base_name="pandas")
+    setattr(_module, _function.__name__, _decorated_object)
+
+__all__ = ["read_gbq_table", "StreamingDataFrame"]

docs/_templates/autosummary/class.rst

@@ -1 +1 @@
-../../../third_party/bigframes_vendored/pandas/doc/_templates/autosummary/class.rst
+../../../third_party/sphinx/ext/autosummary/templates/autosummary/class.rst

docs/_templates/autosummary/module.rst

@@ -0,0 +1 @@
+../../../third_party/sphinx/ext/autosummary/templates/autosummary/module.rst

docs/conf.py

@@ -65,7 +65,7 @@
 autoclass_content = "both"
 autodoc_default_options = {"members": True}
 autosummary_generate = True
-
+autosummary_imported_members = True
 
 # Add any paths that contain templates here, relative to this directory.
 templates_path = ["_templates"]

docs/reference/index.rst

@@ -6,12 +6,34 @@ packages.
 
 .. autosummary::
     :toctree: api
-    :recursive:
 
     bigframes.bigquery
+    bigframes.bigquery.ai
     bigframes.enums
     bigframes.exceptions
     bigframes.geopandas
-    bigframes.ml
-    bigframes.pandas.DataFrame
+    bigframes.pandas
     bigframes.streaming
+
+ML APIs
+~~~~~~~
+
+BigQuery DataFrames provides many machine learning modules, inspired by
+scikit-learn.
+
+.. autosummary::
+    :toctree: api
+
+    bigframes.ml.cluster
+    bigframes.ml.compose
+    bigframes.ml.decomposition
+    bigframes.ml.ensemble
+    bigframes.ml.forecasting
+    bigframes.ml.imported
+    bigframes.ml.impute
+    bigframes.ml.linear_model
+    bigframes.ml.llm
+    bigframes.ml.model_selection
+    bigframes.ml.pipeline
+    bigframes.ml.preprocessing
+    bigframes.ml.remote

noxfile.py

@@ -534,7 +534,7 @@ def docs(session):
     )
     session.run(
         "sphinx-build",
-        "-W",  # warnings as errors
+        # "-W",  # warnings as errors
         "-T",  # show full traceback on exception
         "-N",  # no colors
         "-b",

third_party/sphinx/LICENSE.rst

@@ -0,0 +1,31 @@
+License for Sphinx
+==================
+
+Unless otherwise indicated, all code in the Sphinx project is licenced under the
+two clause BSD licence below.
+
+Copyright (c) 2007-2025 by the Sphinx team (see AUTHORS file).
+All rights reserved.
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are
+met:
+
+* Redistributions of source code must retain the above copyright
+  notice, this list of conditions and the following disclaimer.
+
+* Redistributions in binary form must reproduce the above copyright
+  notice, this list of conditions and the following disclaimer in the
+  documentation and/or other materials provided with the distribution.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
+"AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
+LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
+A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
+HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
+SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
+LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
+DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
+THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
+(INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.