fix docs generation

Author: DenisBiryukov91

docs/stubs_to_sources.py

@@ -28,6 +28,7 @@
 
 PACKAGE = (Path(__file__) / "../../zenoh").resolve()
 __INIT__ = PACKAGE / "__init__.py"
+EXT = PACKAGE / "ext.py"
 
 
 def _unstable(item):
@@ -98,23 +99,26 @@ def visit_FunctionDef(self, node: ast.FunctionDef):
 
 
 def main():
-    # remove __init__.pyi
-    __INIT__.unlink()
+    fnames = [__INIT__, EXT]
+    for fname in fnames:
+        # remove *.py
+        fname.unlink()
     # rename stubs
     for entry in PACKAGE.glob("*.pyi"):
         entry.rename(PACKAGE / f"{entry.stem}.py")
-    # read stub code
-    with open(__INIT__) as f:
-        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(stub))
+    for fname in fnames:
+        # read stub code
+        with open(fname) as f:
+            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(fname, "w") as f:
+            f.write(ast.unparse(stub))
 
 
 if __name__ == "__main__":

zenoh/ext.pyi

@@ -246,46 +246,41 @@ class Miss:
 @_unstable
 @final
 class MissDetectionConfig:
-    @overload
-    def __new__(cls) -> Self: ...
-    @overload
-    def __new__(cls, *, heartbeat: float | int) -> Self:
+    def __new__(
+        cls, *, heartbeat: float | int | None, sporadic_heartbeat: float | int | None
+    ) -> Self:
         """
         :param heartbeat: period in seconds, allow last sample miss detection through periodic heartbeat;
-            periodically send the last published Sample's sequence number to allow last sample recovery
-            `AdvancedSubscriber`(crate::AdvancedSubscriber) can recover the last sample with the `heartbeat` option
-        """
+            periodically send the last published Sample's sequence number to allow last sample recovery.
+            `AdvancedSubscriber can only recover the last sample with the `heartbeat` option enabled.
+            This option can not be enabled simultaneously with `sporadic_heartbeat`.
 
-    @overload
-    def __new__(cls, sporadic_heartbeat: float | int) -> Self:
-        """
         :param sporadic_heartbeat: period in seconds, allow last sample miss detection through sporadic heartbeat;
             each period, the last published Sample's sequence number is sent with `CongestionControl.Block` but only if
             it has changed since the last period.
+            `AdvancedSubscriber can only recover the last sample with the `heartbeat` option enabled.
+            This option can not be enabled simultaneously with `heartbeat`.
         """
 
 @_unstable
 @final
 class RecoveryConfig:
-    @overload
-    def __new__(cls) -> Self: ...
-    @overload
-    def __new__(cls, *, periodic_queries: float | int) -> Self:
+    def __new__(
+        cls, *, periodic_queries: float | int | None, heartbeat: Literal[True] | None
+    ) -> Self:
         """
         :param periodic_queries: enable periodic queries for not yet received Samples and specify their period;
             it allows retrieving the last Sample(s) if the last Sample(s) is/are lost,
             so it is useful for sporadic publications but useless for periodic publications
-            with a period smaller or equal to this period
-            retransmission can only be achieved by `AdvancedPublisher` that enable `cache` and `sample_miss_detection`
-        """
+            with a period smaller or equal to this period.
+            Retransmission can only be achieved by `AdvancedPublisher` that enable `cache` and `sample_miss_detection`.
+            This option can not be enabled simultaneously with `heartbeat`.
 
-    @overload
-    def __new__(cls, *, heartbeat: Literal[True]) -> Self:
-        """
         :param heartbeat: subscribe to heartbeats of `AdvancedPublisher`;
-            it allows receiving the last published Sample's sequence number and check for misses
-            heartbeat subscriber must be paired with `AdvancedPublishers` that enable `cache` and
-            `sample_miss_detection` with `heartbeat` or `sporadic_heartbeat`
+            it allows receiving the last published Sample's sequence number and check for misses.
+            Heartbeat subscriber must be paired with `AdvancedPublishers` that enable `cache` and
+            `sample_miss_detection` with `heartbeat` or `sporadic_heartbeat`.
+            This option can not be enabled simultaneously with `periodic_queries`.
         """
 
 @_unstable
@@ -302,7 +297,6 @@ class RepliesConfig:
 @_unstable
 @final
 class SampleMissListener(Generic[_H]):
-    @property
     def undeclare(self): ...
     @overload
     def try_recv(self: SampleMissListener[Handler[Miss]]) -> Miss | None: ...