Adopt central API interface

executorlib/api.py

@@ -0,0 +1,33 @@
+"""
+External application programming interface (API) following the semantic versioning this inteface is promised to remain
+stable during minor releases and any change in the interface leads to a major version bump. External libraries should
+only use the functionality in this API in combination with the user interface defined in the root __init__.py, all other
+functionality is considered internal and might change during minor releases.
+"""
+
+from executorlib.standalone.command import get_command_path
+from executorlib.standalone.interactive.communication import (
+    SocketInterface,
+    interface_bootup,
+    interface_connect,
+    interface_receive,
+    interface_send,
+    interface_shutdown,
+)
+from executorlib.standalone.interactive.spawner import MpiExecSpawner, SubprocessSpawner
+from executorlib.standalone.queue import cancel_items_in_queue
+from executorlib.standalone.serialize import cloudpickle_register
+
+__all__: list[str] = [
+    "cancel_items_in_queue",
+    "cloudpickle_register",
+    "get_command_path",
+    "interface_bootup",
+    "interface_connect",
+    "interface_receive",
+    "interface_send",
+    "interface_shutdown",
+    "MpiExecSpawner",
+    "SocketInterface",
+    "SubprocessSpawner",
+]

executorlib/standalone/__init__.py

@@ -3,30 +3,3 @@
 separation simplifies the development, testing and debugging. The functionality in executorlib.standalone is designed
 to be used independently in other libraries.
 """
-
-from executorlib.standalone.command import get_command_path
-from executorlib.standalone.interactive.communication import (
-    SocketInterface,
-    interface_bootup,
-    interface_connect,
-    interface_receive,
-    interface_send,
-    interface_shutdown,
-)
-from executorlib.standalone.interactive.spawner import MpiExecSpawner, SubprocessSpawner
-from executorlib.standalone.queue import cancel_items_in_queue
-from executorlib.standalone.serialize import cloudpickle_register
-
-__all__: list[str] = [
-    "cancel_items_in_queue",
-    "cloudpickle_register",
-    "get_command_path",
-    "interface_bootup",
-    "interface_connect",
-    "interface_receive",
-    "interface_send",
-    "interface_shutdown",
-    "MpiExecSpawner",
-    "SocketInterface",
-    "SubprocessSpawner",
-]

notebooks/4-developer.ipynb

@@ -116,7 +116,7 @@
     "leveraged to up-scale any executable independent of the programming language it is developed in.\n",
     "\n",
     "## External Libraries\n",
-    "For external libraries executorlib provides a standardized interface for a subset of its internal functionality, which is designed to remain stable with minor version updates. Developers can import the following functionality from `executorlib.standalone`:\n",
+    "For external libraries executorlib provides a standardized interface for a subset of its internal functionality, which is designed to remain stable with minor version updates. Developers can import the following functionality from `executorlib.api`:\n",
     "* `cancel_items_in_queue()` - Cancel items which are still waiting in the Python standard library queue - `queue.queue`.\n",
     "* `cloudpickle_register()` - Cloudpickle can either pickle by value or pickle by reference. The functions which are communicated have to be pickled by value rather than by reference, so the module which calls the map function is pickled by value.\n",
     "* `get_command_path()` - Get path of the backend executable script `executorlib.backend`.\n",
@@ -129,7 +129,7 @@
     "* `SocketInterface` - The `SocketInterface` is an abstraction layer on top of the zero message queue.\n",
     "* `SubprocessSpawner` - Subprocess interface to start serial Python process.\n",
     "\n",
-    "It is not recommended to import components from other parts of executorlib in other libraries, only the interfaces in `executorlib` and `executorlib.standalone` are designed to be stable. All other classes and functions are considered for internal use only."
+    "It is not recommended to import components from other parts of executorlib in other libraries, only the interfaces in `executorlib` and `executorlib.api` are designed to be stable. All other classes and functions are considered for internal use only."
    ]
   },
   {