diff --git a/extension/pybindings/portable_lib.py b/extension/pybindings/portable_lib.py index b9ed089f918..d094710e67e 100644 --- a/extension/pybindings/portable_lib.py +++ b/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 diff --git a/extension/pybindings/pybindings.pyi b/extension/pybindings/pybindings.pyi index e02ae0046f1..71f5598ad9d 100644 --- a/extension/pybindings/pybindings.pyi +++ b/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. + """ + ... diff --git a/shim/xplat/executorch/extension/pybindings/pybindings.bzl b/shim/xplat/executorch/extension/pybindings/pybindings.bzl index 5ef9fe59266..52191eb978a 100644 --- a/shim/xplat/executorch/extension/pybindings/pybindings.bzl +++ b/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 = [