From ccd77244bbedaee7a1f138bcab5aef6e4e165e57 Mon Sep 17 00:00:00 2001
From: Joseph Perez <joperez@hotmail.fr>
Date: Wed, 4 Dec 2024 16:33:20 +0100
Subject: [PATCH 1/3] docs: add _unstable decorator

---
 docs/stubs_to_sources.py | 20 ++++++++++++++++++--
 1 file changed, 18 insertions(+), 2 deletions(-)

diff --git a/docs/stubs_to_sources.py b/docs/stubs_to_sources.py
index 4c3595ff..7ea6bdad 100644
--- a/docs/stubs_to_sources.py
+++ b/docs/stubs_to_sources.py
@@ -22,6 +22,7 @@
 referencing a type not declared yet (i.e. forward reference)."""
 
 import ast
+import inspect
 from collections import defaultdict
 from pathlib import Path
 
@@ -29,6 +30,15 @@
 __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__":

From 67bdfad6d8709079902aa66b274c0ae10e25b7fb Mon Sep 17 00:00:00 2001
From: Joseph Perez <joperez@hotmail.fr>
Date: Wed, 4 Dec 2024 17:52:48 +0100
Subject: [PATCH 2/3] fix: add missing decorator

---
 zenoh/__init__.pyi | 3 +++
 1 file changed, 3 insertions(+)

diff --git a/zenoh/__init__.pyi b/zenoh/__init__.pyi
index 007fa6dd..cdc8ce6b 100644
--- a/zenoh/__init__.pyi
+++ b/zenoh/__init__.pyi
@@ -32,6 +32,9 @@ _RustHandler = (
 _PythonCallback = Callable[[_T], Any]
 _PythonHandler = tuple[_PythonCallback[_T], _H]
 
+def _unstable(item):
+    return item
+
 @final
 class ZError(Exception): ...
 

From 52397f955112126ddb37108a79f125be0c3a7ad0 Mon Sep 17 00:00:00 2001
From: Joseph Perez <joperez@hotmail.fr>
Date: Wed, 4 Dec 2024 17:55:59 +0100
Subject: [PATCH 3/3] fix: fix _unstable definition in stub

---
 zenoh/__init__.pyi | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/zenoh/__init__.pyi b/zenoh/__init__.pyi
index cdc8ce6b..d7360551 100644
--- a/zenoh/__init__.pyi
+++ b/zenoh/__init__.pyi
@@ -32,8 +32,8 @@ _RustHandler = (
 _PythonCallback = Callable[[_T], Any]
 _PythonHandler = tuple[_PythonCallback[_T], _H]
 
-def _unstable(item):
-    return item
+def _unstable(item: _T) -> _T:
+    """marker for unstable items"""
 
 @final
 class ZError(Exception): ...