Mark all pybindings.portable_lib names as @experimental (#5329)

Summary:
Pull Request resolved: #5329

We plan to replace this with a new API, but it's not likely to happen for beta. Mark this as experimental to set expectations better.

Turns out that decorating the `.pyi` file doesn't actually raise any warnings, but doing so will be more clear to users who read it.

Reviewed By: mergennachin, larryliu0820

Differential Revision: D62608680

fbshipit-source-id: a43cc71a0d3d84078c3dd640ca958f21c2f5aef2

Author: dbort

extension/pybindings/portable_lib.py

@@ -6,6 +6,22 @@
 
 # pyre-strict
 
+"""API for loading and executing ExecuTorch PTE files using the C++ runtime.
+
+.. warning::
+
+    This API is experimental and subject to change without notice.
+"""
+
+import warnings as _warnings
+
+import executorch.exir._warnings as _exir_warnings
+
+_warnings.warn(
+    "This API is experimental and subject to change without notice.",
+    _exir_warnings.ExperimentalWarning,
+)
+
 # When installed as a pip wheel, we must import `torch` before trying to import
 # the pybindings shared library extension. This will load libtorch.so and
 # related libs, ensuring that the pybindings lib can resolve those runtime
@@ -15,6 +31,8 @@
 # Let users import everything from the C++ _portable_lib extension as if this
 # python file defined them. Although we could import these dynamically, it
 # wouldn't preserve the static type annotations.
+#
+# Note that all of these are experimental, and subject to change without notice.
 from executorch.extension.pybindings._portable_lib import (  # noqa: F401
     # Disable "imported but unused" (F401) checks.
     _create_profile_block,  # noqa: F401
@@ -32,3 +50,5 @@
 # Clean up so that `dir(portable_lib)` is the same as `dir(_portable_lib)`
 # (apart from some __dunder__ names).
 del _torch
+del _exir_warnings
+del _warnings

extension/pybindings/pybindings.pyi

@@ -7,7 +7,17 @@
 # pyre-strict
 from typing import Any, Dict, List, Optional, Sequence, Tuple
 
+from executorch.exir._warnings import experimental
+
+@experimental("This API is experimental and subject to change without notice.")
 class ExecuTorchModule:
+    """ExecuTorchModule is a Python wrapper around a C++ ExecuTorch program.
+
+    .. warning::
+
+        This API is experimental and subject to change without notice.
+    """
+
     # pyre-ignore[2, 3]: "Any" in parameter and return type annotations.
     def __call__(self, inputs: Any) -> List[Any]: ...
     # pyre-ignore[2, 3]: "Any" in parameter and return type annotations.
@@ -34,12 +44,26 @@ class ExecuTorchModule:
         self, path: str, debug_buffer_path: Optional[str] = None
     ) -> None: ...
 
-class BundledModule: ...
+@experimental("This API is experimental and subject to change without notice.")
+class BundledModule:
+    """
+    .. warning::
 
+        This API is experimental and subject to change without notice.
+    """
+
+    ...
+
+@experimental("This API is experimental and subject to change without notice.")
 def _load_for_executorch(
     path: str, enable_etdump: bool = False, debug_buffer_size: int = 0
 ) -> ExecuTorchModule:
     """Load an ExecuTorch Program from a file.
+
+    .. warning::
+
+        This API is experimental and subject to change without notice.
+
     Args:
         path: File path to the ExecuTorch program as a string.
         enable_etdump: If true, enables an ETDump which can store profiling information.
@@ -53,23 +77,75 @@ def _load_for_executorch(
     """
     ...
 
+@experimental("This API is experimental and subject to change without notice.")
 def _load_for_executorch_from_buffer(
     buffer: bytes, enable_etdump: bool = False, debug_buffer_size: int = 0
 ) -> ExecuTorchModule:
-    """Same as _load_for_executorch, but takes a byte buffer instead of a file path."""
+    """Same as _load_for_executorch, but takes a byte buffer instead of a file path.
+
+    .. warning::
+
+        This API is experimental and subject to change without notice.
+    """
     ...
 
+@experimental("This API is experimental and subject to change without notice.")
 def _load_for_executorch_from_bundled_program(
     module: BundledModule, enable_etdump: bool = False, debug_buffer_size: int = 0
 ) -> ExecuTorchModule:
     """Same as _load_for_executorch, but takes a bundled program instead of a file path.
-    See https://pytorch.org/executorch/stable/sdk-bundled-io.html for documentation."""
+
+    See https://pytorch.org/executorch/stable/sdk-bundled-io.html for documentation.
+
+    .. warning::
+
+        This API is experimental and subject to change without notice.
+    """
     ...
 
+@experimental("This API is experimental and subject to change without notice.")
 def _load_bundled_program_from_buffer(
     buffer: bytes, non_const_pool_size: int = ...
-) -> BundledModule: ...
-def _get_operator_names() -> List[str]: ...
-def _create_profile_block(name: str) -> None: ...
-def _dump_profile_results() -> bytes: ...
-def _reset_profile_results() -> None: ...
+) -> BundledModule:
+    """
+    .. warning::
+
+        This API is experimental and subject to change without notice.
+    """
+    ...
+
+@experimental("This API is experimental and subject to change without notice.")
+def _get_operator_names() -> List[str]:
+    """
+    .. warning::
+
+        This API is experimental and subject to change without notice.
+    """
+    ...
+
+@experimental("This API is experimental and subject to change without notice.")
+def _create_profile_block(name: str) -> None:
+    """
+    .. warning::
+
+        This API is experimental and subject to change without notice.
+    """
+    ...
+
+@experimental("This API is experimental and subject to change without notice.")
+def _dump_profile_results() -> bytes:
+    """
+    .. warning::
+
+        This API is experimental and subject to change without notice.
+    """
+    ...
+
+@experimental("This API is experimental and subject to change without notice.")
+def _reset_profile_results() -> None:
+    """
+    .. warning::
+
+        This API is experimental and subject to change without notice.
+    """
+    ...

shim/xplat/executorch/extension/pybindings/pybindings.bzl

@@ -52,6 +52,7 @@ def executorch_pybindings(python_module_name, srcs = [], cppdeps = [], visibilit
             "-DEXECUTORCH_PYTHON_MODULE_NAME={}".format(python_module_name),
         ],
         deps = [
+            "//executorch/exir:_warnings",
             "//executorch/runtime/core:core",
         ] + cppdeps,
         external_deps = [