tag unstable functionality

docs/index.rst

@@ -69,7 +69,7 @@ module zenoh
     :undoc-members:
 
 module zenoh.handlers
-============
+=====================
 
 .. automodule:: zenoh.handlers
     :members:

docs/stubs_to_sources.py

@@ -22,13 +22,23 @@
 referencing a type not declared yet (i.e. forward reference)."""
 
 import ast
+import inspect
 from collections import defaultdict
 from pathlib import Path
 
 PACKAGE = (Path(__file__) / "../../zenoh").resolve()
 __INIT__ = PACKAGE / "__init__.py"
 
 
+def _unstable(item):
+    warning = ".. warning:: This API has been marked as unstable: it works as advertised, but it may be changed in a future release."
+    if item.__doc__:
+        item.__doc__ += "\n" + warning
+    else:
+        item.__doc__ = warning
+    return item
+
+
 class RemoveOverload(ast.NodeTransformer):
     def __init__(self):
         self.current_cls = None
@@ -95,10 +105,16 @@ def main():
         entry.rename(PACKAGE / f"{entry.stem}.py")
     # read stub code
     with open(__INIT__) as f:
-        stub = ast.parse(f.read())
+        stub: ast.Module = ast.parse(f.read())
+        # replace _unstable
+        for i, stmt in enumerate(stub.body):
+            if isinstance(stmt, ast.FunctionDef) and stmt.name == "_unstable":
+                stub.body[i] = ast.parse(inspect.getsource(_unstable))
+        # remove overload
+        stub = RemoveOverload().visit(stub)
     # write modified code
     with open(__INIT__, "w") as f:
-        f.write(ast.unparse(RemoveOverload().visit(stub)))
+        f.write(ast.unparse(stub))
 
 
 if __name__ == "__main__":

zenoh/__init__.py

@@ -17,3 +17,7 @@
     from . import ext
 except ImportError:
     pass
+
+
+def _unstable(item):
+    return item

zenoh/__init__.pyi

@@ -32,6 +32,9 @@ _RustHandler = (
 _PythonCallback = Callable[[_T], Any]
 _PythonHandler = tuple[_PythonCallback[_T], _H]
 
+def _unstable(item: _T) -> _T:
+    """marker for unstable functionality"""
+
 @final
 class ZError(Exception): ...
 
@@ -349,6 +352,7 @@ class KeyExpr:
 _IntoKeyExpr = KeyExpr | str
 
 @final
+@_unstable
 class Liveliness:
     def declare_token(self, key_expr: _IntoKeyExpr) -> LivelinessToken:
         """Create a LivelinessToken for the given key expression."""
@@ -414,6 +418,7 @@ class Liveliness:
         """Create a Subscriber for liveliness changes matching the given key expression."""
 
 @final
+@_unstable
 class LivelinessToken:
     def __enter__(self) -> Self: ...
     def __exit__(self, *_args, **_kwargs): ...
@@ -484,6 +489,7 @@ class Publisher:
     @property
     def priority(self) -> Priority: ...
     @property
+    @_unstable
     def reliability(self) -> Reliability: ...
     def put(
         self,
@@ -574,8 +580,9 @@ class Queryable(Generic[_H]):
     def __iter__(self) -> Never: ...
 
 @final
+@_unstable
 class Querier:
-    """A querier that allows to send queries to a queryable..
+    """A querier that allows to send queries to a queryable.
     Queriers are automatically undeclared when dropped."""
 
     def __enter__(self) -> Self: ...
@@ -642,6 +649,7 @@ class QueryTarget(Enum):
     DEFAULT = BEST_MATCHING
 
 @final
+@_unstable
 class Reliability(Enum):
     BEST_EFFORT = auto()
     RELIABLE = auto()
@@ -944,6 +952,7 @@ class Session:
     ) -> Publisher:
         """Create a Publisher for the given key expression."""
 
+    @_unstable
     def declare_querier(
         self,
         key_expr: _IntoKeyExpr,