PY-233 Add @experimental decorator to fetch_metric_buckets

src/neptune_query/__init__.py

@@ -59,6 +59,7 @@
 from neptune_query.internal.composition import list_attributes as _list_attributes
 from neptune_query.internal.composition import list_containers as _list_containers
 from neptune_query.internal.context import set_api_token
+from neptune_query.internal.experimental import experimental
 from neptune_query.internal.query_metadata_context import use_query_metadata
 from neptune_query.internal.retrieval import search as _search
 
@@ -430,6 +431,7 @@ def download_files(
     )
 
 
+@experimental
 @use_query_metadata(api_function="fetch_metric_buckets")
 def fetch_metric_buckets(
     *,

src/neptune_query/internal/experimental.py

@@ -0,0 +1,50 @@
+#
+# Copyright (c) 2025, Neptune Labs Sp. z o.o.
+#
+# 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.
+
+import functools
+import warnings
+from typing import (
+    Any,
+    Callable,
+)
+
+
+class ExperimentalWarning(UserWarning):
+    """Warning for use of experimental API elements."""
+
+
+# registry of functions already warned
+_warned_experimentals = set()
+
+
+def experimental(func: Callable) -> Callable:
+    """Decorator to mark functions as experimental.
+    It will result in a warning being emitted when the function is used
+    for the first time.
+    """
+
+    @functools.wraps(func)
+    def wrapper(*args: Any, **kwargs: Any) -> object:
+        if func not in _warned_experimentals:
+            warnings.warn(
+                f"{func.__qualname__} is experimental and may change or be removed "
+                "in a future minor release. Use with caution in production code.",
+                category=ExperimentalWarning,
+                stacklevel=2,
+            )
+            _warned_experimentals.add(func)
+        return func(*args, **kwargs)
+
+    return wrapper