add preview doc and warning

Author: chelsea-lin

bigframes/bigquery/_operations/json.py

@@ -23,20 +23,26 @@
 
 from typing import Any, cast, Optional, Sequence, Tuple, Union
 
+import bigframes.core.utils as utils
 import bigframes.dtypes
 import bigframes.operations as ops
 import bigframes.series as series
 
 from . import array
 
 
+@utils.preview(name="The JSON-related API `json_set`")
 def json_set(
     input: series.Series,
     json_path_value_pairs: Sequence[Tuple[str, Any]],
 ) -> series.Series:
     """Produces a new JSON value within a Series by inserting or replacing values at
     specified paths.
 
+    .. warning::
+        The JSON-related API `parse_json` is in preview. Its behavior may change in
+        future versions.
+
     **Examples:**
 
         >>> import bigframes.pandas as bpd
@@ -225,11 +231,16 @@ def json_extract_string_array(
     return array_series
 
 
+@utils.preview(name="The JSON-related API `parse_json`")
 def parse_json(
     input: series.Series,
 ) -> series.Series:
     """Converts a series with a JSON-formatted STRING value to a JSON value.
 
+    .. warning::
+        The JSON-related API `parse_json` is in preview. Its behavior may change in
+        future versions.
+
     **Examples:**
 
         >>> import bigframes.pandas as bpd

bigframes/core/utils.py

@@ -11,14 +11,18 @@
 # 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.
+import functools
 import re
 import typing
 from typing import Hashable, Iterable, List
+import warnings
 
 import bigframes_vendored.pandas.io.common as vendored_pandas_io_common
 import pandas as pd
 import typing_extensions
 
+import bigframes.exceptions as exc
+
 UNNAMED_COLUMN_ID = "bigframes_unnamed_column"
 UNNAMED_INDEX_ID = "bigframes_unnamed_index"
 
@@ -164,3 +168,24 @@ def merge_column_labels(
             result_labels.append(col_label)
 
     return pd.Index(result_labels)
+
+
+def warn_preview(msg=""):
+    """Warn a preview API."""
+    warnings.warn(msg, exc.PreviewWarning)
+
+
+def preview(*, name: str):
+    """Decorate to warn of a preview API."""
+
+    def decorator(func):
+        msg = f"{name} is in preview. Its behavior may change in future versions."
+
+        @functools.wraps(func)
+        def wrapper(*args, **kwargs):
+            warn_preview(msg=msg)
+            return func(*args, **kwargs)
+
+        return wrapper
+
+    return decorator