From 2ac1cb0c5f629eb7cfebb98f82037becf770d5ef Mon Sep 17 00:00:00 2001
From: Jan Janssen <janssen@mpie.de>
Date: Thu, 8 May 2025 09:14:56 +0200
Subject: [PATCH] Adopt central API interface

Following the [decision for unifying programming interfaces](https://github.com/pyiron/decisions/blob/main/decisions/25-001-split-api.md) within the pyiron project.
---
 executorlib/api.py                 | 33 ++++++++++++++++++++++++++++++
 executorlib/standalone/__init__.py | 27 ------------------------
 notebooks/4-developer.ipynb        |  4 ++--
 3 files changed, 35 insertions(+), 29 deletions(-)
 create mode 100644 executorlib/api.py

diff --git a/executorlib/api.py b/executorlib/api.py
new file mode 100644
index 00000000..c7d4459f
--- /dev/null
+++ b/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",
+]
diff --git a/executorlib/standalone/__init__.py b/executorlib/standalone/__init__.py
index 9ff19574..3ffe5097 100644
--- a/executorlib/standalone/__init__.py
+++ b/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",
-]
diff --git a/notebooks/4-developer.ipynb b/notebooks/4-developer.ipynb
index e1a5f10a..3fd4baec 100644
--- a/notebooks/4-developer.ipynb
+++ b/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."
    ]
   },
   {