appose 0.2.0__tar.gz → 0.6.0__tar.gz

{appose-0.2.0 → appose-0.6.0}/LICENSE.txt

@@ -1,4 +1,4 @@
-Copyright (c) 2023 - 2024, Appose developers.
+Copyright (c) 2023 - 2025, Appose developers.
 All rights reserved.
 
 Redistribution and use in source and binary forms, with or without modification,

{appose-0.2.0/src/appose.egg-info → appose-0.6.0}/PKG-INFO

@@ -1,9 +1,9 @@
-Metadata-Version: 2.1
+Metadata-Version: 2.4
 Name: appose
-Version: 0.2.0
+Version: 0.6.0
 Summary: Appose: multi-language interprocess cooperation with shared memory.
 Author: Appose developers
-License: Simplified BSD License
+License-Expression: BSD-2-Clause
 Project-URL: homepage, https://github.com/apposed/appose-python
 Project-URL: documentation, https://github.com/apposed/appose-python/blob/main/README.md
 Project-URL: source, https://github.com/apposed/appose-python
@@ -17,7 +17,7 @@ Classifier: Intended Audience :: Science/Research
 Classifier: Programming Language :: Python :: 3 :: Only
 Classifier: Programming Language :: Python :: 3.10
 Classifier: Programming Language :: Python :: 3.11
-Classifier: License :: OSI Approved :: BSD License
+Classifier: Programming Language :: Python :: 3.12
 Classifier: Operating System :: Microsoft :: Windows
 Classifier: Operating System :: Unix
 Classifier: Operating System :: MacOS
@@ -40,6 +40,7 @@ Requires-Dist: pytest; extra == "dev"
 Requires-Dist: numpy; extra == "dev"
 Requires-Dist: toml; extra == "dev"
 Requires-Dist: validate-pyproject[all]; extra == "dev"
+Dynamic: license-file
 
 # Appose Python
 

{appose-0.2.0 → appose-0.6.0}/pyproject.toml

@@ -4,9 +4,9 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "appose"
-version = "0.2.0"
+version = "0.6.0"
 description = "Appose: multi-language interprocess cooperation with shared memory."
-license = {text = "Simplified BSD License"}
+license = "BSD-2-Clause"
 authors = [{name = "Appose developers"}]
 readme = "README.md"
 keywords = ["java", "javascript", "python", "cross-language", "interprocess"]
@@ -18,7 +18,7 @@ classifiers = [
     "Programming Language :: Python :: 3 :: Only",
     "Programming Language :: Python :: 3.10",
     "Programming Language :: Python :: 3.11",
-    "License :: OSI Approved :: BSD License",
+    "Programming Language :: Python :: 3.12",
     "Operating System :: Microsoft :: Windows",
     "Operating System :: Unix",
     "Operating System :: MacOS",

{appose-0.2.0 → appose-0.6.0}/src/appose/__init__.py

@@ -2,7 +2,7 @@
 # #%L
 # Appose: multi-language interprocess cooperation with shared memory.
 # %%
-# Copyright (C) 2023 - 2024 Appose developers.
+# Copyright (C) 2023 - 2025 Appose developers.
 # %%
 # Redistribution and use in source and binary forms, with or without
 # modification, are permitted provided that the following conditions are met:
@@ -42,8 +42,6 @@ The steps for using Appose are:
 
 ## Examples
 
-* TODO - move the below code somewhere linkable, for succinctness here.
-
 Here is a very simple example written in Python:
 
     import appose
@@ -84,7 +82,7 @@ And here is an example using a few more of Appose's features:
     def task_listener(event):
         match event.responseType:
             case UPDATE:
-                print(f"Progress {task.current}/{task.maximum}")
+                print(f"Progress {event.current}/{event.maximum}")
             case COMPLETION:
                 numer = task.outputs["numer"]
                 denom = task.outputs["denom"]
@@ -127,8 +125,94 @@ But Appose is compatible with any program that abides by the
 2. The worker must issue responses in Appose's response format on its
    standard output (stdout) stream.
 
-TODO - write up the request and response formats in detail here!
-JSON, one line per request/response.
+### Requests to worker from service
+
+A *request* is a single line of JSON sent to the worker process via
+its standard input stream. It has a `task` key taking the form of a
+UUID, and a `requestType` key with one of the following values:
+
+#### EXECUTE
+
+Asynchronously execute a script within the worker process. E.g.:
+
+    {
+       "task" : "87427f91-d193-4b25-8d35-e1292a34b5c4",
+       "requestType" : "EXECUTE",
+       "script" : "task.outputs[\"result\"] = computeResult(gamma)\n",
+       "inputs" : {"gamma": 2.2}
+    }
+
+#### CANCEL
+
+Cancel a running script. E.g.:
+
+    {
+       "task" : "87427f91-d193-4b25-8d35-e1292a34b5c4",
+       "requestType" : "CANCEL"
+    }
+
+### Responses from worker to service
+
+A *response* is a single line of JSON with a `task` key taking the form
+of a UUID, and a `responseType` key with one of the following values:
+
+#### LAUNCH
+
+A LAUNCH response is issued to confirm the success of an EXECUTE
+request.
+
+    {
+       "task" : "87427f91-d193-4b25-8d35-e1292a34b5c4",
+       "responseType" : "LAUNCH"
+    }
+
+#### UPDATE
+
+An UPDATE response is issued to convey that a task has somehow made
+progress. The UPDATE response typically comes bundled with a
+`message` string indicating what has changed, `current` and/or
+`maximum` progress indicators conveying the step the task has
+reached, or both.
+
+    {
+       "task" : "87427f91-d193-4b25-8d35-e1292a34b5c4",
+       "responseType" : "UPDATE",
+       "message" : "Processing step 0 of 91",
+       "current" : 0,
+       "maximum" : 91
+    }
+
+#### COMPLETION
+
+A COMPLETION response is issued to convey that a task has successfully
+completed execution, as well as report the values of any task outputs.
+
+    {
+       "task" : "87427f91-d193-4b25-8d35-e1292a34b5c4",
+       "responseType" : "COMPLETION",
+       "outputs" : {"result" : 91}
+    }
+
+#### CANCELATION
+
+A CANCELATION response is issued to confirm the success of a CANCEL
+request.
+
+    {
+       "task" : "87427f91-d193-4b25-8d35-e1292a34b5c4",
+       "responseType" : "CANCELATION"
+    }
+
+#### FAILURE
+
+A FAILURE response is issued to convey that a task did not completely
+and successfully execute, such as an exception being raised.
+
+    {
+       "task" : "87427f91-d193-4b25-8d35-e1292a34b5c4",
+       "responseType" : "FAILURE",
+       "error", "Invalid gamma value"
+    }
 '''
 
 from pathlib import Path

{appose-0.2.0 → appose-0.6.0}/src/appose/environment.py

@@ -2,7 +2,7 @@
 # #%L
 # Appose: multi-language interprocess cooperation with shared memory.
 # %%
-# Copyright (C) 2023 - 2024 Appose developers.
+# Copyright (C) 2023 - 2025 Appose developers.
 # %%
 # Redistribution and use in source and binary forms, with or without
 # modification, are permitted provided that the following conditions are met:

{appose-0.2.0 → appose-0.6.0}/src/appose/paths.py

@@ -2,7 +2,7 @@
 # #%L
 # Appose: multi-language interprocess cooperation with shared memory.
 # %%
-# Copyright (C) 2023 - 2024 Appose developers.
+# Copyright (C) 2023 - 2025 Appose developers.
 # %%
 # Redistribution and use in source and binary forms, with or without
 # modification, are permitted provided that the following conditions are met:

appose-0.6.0/src/appose/python_worker.py

@@ -0,0 +1,265 @@
+###
+# #%L
+# Appose: multi-language interprocess cooperation with shared memory.
+# %%
+# Copyright (C) 2023 - 2025 Appose developers.
+# %%
+# Redistribution and use in source and binary forms, with or without
+# modification, are permitted provided that the following conditions are met:
+#
+# 1. Redistributions of source code must retain the above copyright notice,
+#    this list of conditions and the following disclaimer.
+# 2. Redistributions in binary form must reproduce the above copyright notice,
+#    this list of conditions and the following disclaimer in the documentation
+#    and/or other materials provided with the distribution.
+#
+# THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+# AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+# IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
+# ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDERS OR CONTRIBUTORS BE
+# LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
+# CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
+# SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
+# INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
+# CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
+# ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
+# POSSIBILITY OF SUCH DAMAGE.
+# #L%
+###
+
+"""
+The Appose worker for running Python scripts.
+
+Like all Appose workers, this program conforms to the Appose worker process
+contract, meaning it accepts requests on stdin and produces responses on
+stdout, both formatted according to Appose's assumptions.
+
+For details, see the Appose README:
+https://github.com/apposed/appose/blob/-/README.md#workers
+"""
+
+import ast
+import sys
+import traceback
+from threading import Thread
+from time import sleep
+from typing import Any
+
+# NB: Avoid relative imports so that this script can be run standalone.
+from appose.service import RequestType, ResponseType
+from appose.types import Args, _set_worker, decode, encode
+
+
+class Task:
+    def __init__(self, uuid: str, script: str, inputs: Args | None = None) -> None:
+        self._uuid = uuid
+        self._script = script
+        self._inputs = inputs
+        self._finished = False
+        self._thread = None
+
+        # Public-facing fields for use within the task script.
+        self.outputs = {}
+        self.cancel_requested = False
+
+    def update(
+        self,
+        message: str | None = None,
+        current: int | None = None,
+        maximum: int | None = None,
+        info: dict[str, Any] | None = None,
+    ) -> None:
+        args = {}
+        if message is not None:
+            args["message"] = str(message)
+        if current is not None:
+            try:
+                args["current"] = int(current)
+            except ValueError:
+                pass
+        if maximum is not None:
+            try:
+                args["maximum"] = int(maximum)
+            except ValueError:
+                pass
+        args["info"] = info
+        self._respond(ResponseType.UPDATE, args)
+
+    def cancel(self) -> None:
+        self._respond(ResponseType.CANCELATION, None)
+
+    def fail(self, error: str | None = None) -> None:
+        args = None if error is None else {"error": error}
+        self._respond(ResponseType.FAILURE, args)
+
+    def _run(self) -> None:
+        try:
+            # Populate script bindings.
+            binding = {"task": self}
+            if self._inputs is not None:
+                binding.update(self._inputs)
+
+            # Inform the calling process that the script is launching.
+            self._report_launch()
+
+            # Execute the script.
+            # result = exec(script, locals=binding)
+            result = None
+
+            # NB: Execute the block, except for the last statement,
+            # which we evaluate instead to get its return value.
+            # Credit: https://stackoverflow.com/a/39381428/1207769
+
+            block = ast.parse(self._script, mode="exec")
+            last = None
+            if (
+                len(block.body) > 0
+                and hasattr(block.body[-1], "value")
+                and not isinstance(block.body[-1], ast.Assign)
+            ):
+                # Last statement of the script looks like an expression. Evaluate!
+                last = ast.Expression(block.body.pop().value)
+
+            # NB: When `exec` gets two separate objects as *globals* and
+            # *locals*, the code will be executed as if it were embedded in
+            # a class definition. This means functions and classes defined
+            # in the executed code will not be able to access variables
+            # assigned at the top level, because the "top level" variables
+            # are treated as class variables in a class definition.
+            # See: https://docs.python.org/3/library/functions.html#exec
+            _globals = binding
+            exec(compile(block, "<string>", mode="exec"), _globals, binding)
+            if last is not None:
+                result = eval(compile(last, "<string>", mode="eval"), _globals, binding)
+
+            # Report the results to the Appose calling process.
+            if isinstance(result, dict):
+                # Script produced a dict; add all entries to the outputs.
+                self.outputs.update(result)
+            elif result is not None:
+                # Script produced a non-dict; add it alone to the outputs.
+                self.outputs["result"] = result
+            self._report_completion()
+        except Exception:
+            self.fail(traceback.format_exc())
+
+    def _report_launch(self) -> None:
+        self._respond(ResponseType.LAUNCH, None)
+
+    def _report_completion(self) -> None:
+        args = None if self.outputs is None else {"outputs": self.outputs}
+        self._respond(ResponseType.COMPLETION, args)
+
+    def _respond(self, response_type: ResponseType, args: Args | None) -> None:
+        already_terminated = False
+        if response_type.is_terminal():
+            if self._finished:
+                # This is not the first terminal response. Let's
+                # remember, in case an exception is generated below,
+                # so that we can avoid infinite recursion loops.
+                already_terminated = True
+            self._finished = True
+
+        response = {}
+        if args is not None:
+            response.update(args)
+        response.update({"task": self._uuid, "responseType": response_type.value})
+        # NB: Flush is necessary to ensure service receives the data!
+        try:
+            print(encode(response), flush=True)
+        except Exception:
+            if already_terminated:
+                # An exception triggered a failure response which
+                # then triggered another exception. Let's stop here
+                # to avoid the risk of infinite recursion loops.
+                return
+            # Encoding can fail due to unsupported types, when the
+            # response or its elements are not supported by JSON encoding.
+            # No matter what goes wrong, we want to tell the caller.
+            self.fail(traceback.format_exc())
+
+
+class Worker:
+
+    def __init__(self):
+        self.tasks = {}
+        self.queue: list[Task] = []
+        self.running = True
+
+        # Flag this process as a worker, not a service.
+        _set_worker(True)
+
+        Thread(target=self._process_input, name="Appose-Receiver").start()
+        Thread(target=self._cleanup_threads, name="Appose-Janitor").start()
+
+    def run(self) -> None:
+        """
+        Processes tasks from the task queue.
+        """
+        while self.running:
+            if len(self.queue) == 0:
+                # Nothing queued, so wait a bit.
+                sleep(0.05)
+                continue
+            task = self.queue.pop()
+            task._run()
+
+    def _process_input(self) -> None:
+        while True:
+            try:
+                line = input().strip()
+            except EOFError:
+                line = None
+            if not line:
+                self.running = False
+                return
+
+            request = decode(line)
+            uuid = request.get("task")
+            request_type = request.get("requestType")
+
+            match RequestType(request_type):
+                case RequestType.EXECUTE:
+                    script = request.get("script")
+                    inputs = request.get("inputs")
+                    queue = request.get("queue")
+                    task = Task(uuid, script, inputs)
+                    self.tasks[uuid] = task
+                    if queue == "main":
+                        # Add the task to the main thread queue.
+                        self.queue.append(task)
+                    else:
+                        # Create a thread and save a reference to it, in case its script
+                        # kills the thread. This happens e.g. if it calls sys.exit.
+                        task._thread = Thread(target=task._run, name=f"Appose-{uuid}")
+                        task._thread.start()
+
+                case RequestType.CANCEL:
+                    task = self.tasks.get(uuid)
+                    if task is None:
+                        print(f"No such task: {uuid}", file=sys.stderr)
+                        continue
+                    task.cancel_requested = True
+
+    def _cleanup_threads(self) -> None:
+        while self.running:
+            sleep(0.05)
+            dead = {
+                uuid: task
+                for uuid, task in self.tasks.items()
+                if task._thread is not None and not task._thread.is_alive()
+            }
+            for uuid, task in dead.items():
+                self.tasks.pop(uuid)
+                if not task._finished:
+                    # The task died before reporting a terminal status.
+                    # We report this situation as failure by thread death.
+                    task.fail("thread death")
+
+
+def main() -> None:
+    Worker().run()
+
+
+if __name__ == "__main__":
+    main()

{appose-0.2.0 → appose-0.6.0}/src/appose/service.py

@@ -2,7 +2,7 @@
 # #%L
 # Appose: multi-language interprocess cooperation with shared memory.
 # %%
-# Copyright (C) 2023 - 2024 Appose developers.
+# Copyright (C) 2023 - 2025 Appose developers.
 # %%
 # Redistribution and use in source and binary forms, with or without
 # modification, are permitted provided that the following conditions are met:
@@ -36,7 +36,7 @@ import threading
 from enum import Enum
 from pathlib import Path
 from traceback import format_exc
-from typing import Any, Callable, Dict, List, Optional, Sequence, Union
+from typing import Any, Callable
 from uuid import uuid4
 
 from .types import Args, decode, encode
@@ -52,17 +52,17 @@ class Service:
 
     _service_count = 0
 
-    def __init__(self, cwd: Union[str, Path], args: Sequence[str]) -> None:
+    def __init__(self, cwd: str | Path, args: list[str]) -> None:
         self._cwd = cwd
         self._args = args[:]
-        self._tasks: Dict[str, "Task"] = {}
+        self._tasks: dict[str, "Task"] = {}
         self._service_id = Service._service_count
         Service._service_count += 1
-        self._process: Optional[subprocess.Popen] = None
-        self._stdout_thread: Optional[threading.Thread] = None
-        self._stderr_thread: Optional[threading.Thread] = None
-        self._monitor_thread: Optional[threading.Thread] = None
-        self._debug_callback: Optional[Callable[[Any], Any]] = None
+        self._process: subprocess.Popen | None = None
+        self._stdout_thread: threading.Thread | None = None
+        self._stderr_thread: threading.Thread | None = None
+        self._monitor_thread: threading.Thread | None = None
+        self._debug_callback: Callable[[Any], Any] | None = None
 
     def debug(self, debug_callback: Callable[[Any], Any]) -> None:
         """
@@ -109,16 +109,20 @@ class Service:
         self._stderr_thread.start()
         self._monitor_thread.start()
 
-    def task(self, script: str, inputs: Optional[Args] = None) -> "Task":
+    def task(
+        self, script: str, inputs: Args | None = None, queue: str | None = None
+    ) -> "Task":
         """
         Create a new task, passing the given script to the worker for execution.
         :param script:
             The script for the worker to execute in its environment.
         :param inputs:
             Optional list of key/value pairs to feed into the script as inputs.
+        :param queue:
+            Optional queue target. Pass "main" to queue to worker's main thread.
         """
         self.start()
-        return Task(self, script, inputs)
+        return Task(self, script, inputs, queue)
 
     def close(self) -> None:
         """
@@ -256,11 +260,35 @@ class ResponseType(Enum):
     FAILURE = "FAILURE"
     CRASH = "CRASH"
 
+    """
+    True iff response type is COMPLETE, CANCELED, FAILED, or CRASHED.
+    """
+
+    def is_terminal(self):
+        return self in (
+            ResponseType.COMPLETION,
+            ResponseType.CANCELATION,
+            ResponseType.FAILURE,
+            ResponseType.CRASH,
+        )
+
 
 class TaskEvent:
-    def __init__(self, task: "Task", response_type: ResponseType) -> None:
+    def __init__(
+        self,
+        task: "Task",
+        response_type: ResponseType,
+        message: str | None = None,
+        current: int | None = None,
+        maximum: int | None = None,
+        info: dict[str, Any] | None = None,
+    ) -> None:
         self.task: "Task" = task
         self.response_type: ResponseType = response_type
+        self.message: str | None = message
+        self.current: int | None = current
+        self.maximum: int | None = maximum
+        self.info: dict[str, Any] | None = info
 
     def __str__(self):
         return f"[{self.response_type}] {self.task}"
@@ -274,21 +302,26 @@ class Task:
     """
 
     def __init__(
-        self, service: Service, script: str, inputs: Optional[Args] = None
+        self,
+        service: Service,
+        script: str,
+        inputs: Args | None = None,
+        queue: str | None = None,
     ) -> None:
         self.uuid = uuid4().hex
         self.service = service
         self.script = script
         self.inputs: Args = {}
+        self.queue: str | None = queue
         if inputs is not None:
             self.inputs.update(inputs)
         self.outputs: Args = {}
         self.status: TaskStatus = TaskStatus.INITIAL
-        self.message: Optional[str] = None
+        self.message: str | None = None
         self.current: int = 0
         self.maximum: int = 1
-        self.error: Optional[str] = None
-        self.listeners: List[Callable[["TaskEvent"], None]] = []
+        self.error: str | None = None
+        self.listeners: list[Callable[["TaskEvent"], None]] = []
         self.cv = threading.Condition()
         self.service._tasks[self.uuid] = self
 
@@ -299,7 +332,7 @@ class Task:
 
             self.status = TaskStatus.QUEUED
 
-        args = {"script": self.script, "inputs": self.inputs}
+        args = {"script": self.script, "inputs": self.inputs, "queue": self.queue}
         self._request(RequestType.EXECUTE, args)
 
         return self
@@ -354,13 +387,8 @@ class Task:
             case ResponseType.LAUNCH:
                 self.status = TaskStatus.RUNNING
             case ResponseType.UPDATE:
-                self.message = response.get("message")
-                current = response.get("current")
-                maximum = response.get("maximum")
-                if current is not None:
-                    self.current = int(current)
-                if maximum is not None:
-                    self.maximum = int(maximum)
+                # No extra action needed.
+                pass
             case ResponseType.COMPLETION:
                 self.service._tasks.pop(self.uuid, None)
                 self.status = TaskStatus.COMPLETE
@@ -380,7 +408,11 @@ class Task:
                 )
                 return
 
-        event = TaskEvent(self, response_type)
+        message = response.get("message")
+        current = response.get("current")
+        maximum = response.get("maximum")
+        info = response.get("info")
+        event = TaskEvent(self, response_type, message, current, maximum, info)
         for listener in self.listeners:
             listener(event)
 
@@ -397,7 +429,4 @@ class Task:
             self.cv.notify_all()
 
     def __str__(self):
-        return (
-            f"{self.uuid=}, {self.status=}, {self.message=}, "
-            f"{self.current=}, {self.maximum=}, {self.error=}"
-        )
+        return f"{self.uuid=}, {self.status=}, {self.error=}"

{appose-0.2.0 → appose-0.6.0}/src/appose/types.py

@@ -2,7 +2,7 @@
 # #%L
 # Appose: multi-language interprocess cooperation with shared memory.
 # %%
-# Copyright (C) 2023 - 2024 Appose developers.
+# Copyright (C) 2023 - 2025 Appose developers.
 # %%
 # Redistribution and use in source and binary forms, with or without
 # modification, are permitted provided that the following conditions are met:
@@ -45,13 +45,29 @@ class SharedMemory(shared_memory.SharedMemory):
     `unlink_on_dispose` flag.
     """
 
-    def __init__(self, name: str = None, create: bool = False, size: int = 0):
-        super().__init__(name=name, create=create, size=size)
+    def __init__(self, name: str = None, create: bool = False, rsize: int = 0):
+        """
+        Create a new shared memory block, or attach to an existing one.
+
+        :param name:
+            The unique name for the requested shared memory, specified as a
+            string. If create is True (i.e. a new shared memory block) and
+            no name is given, a novel name will be generated.
+        :param create:
+            Whether a new shared memory block is created (True)
+            or an existing one is attached to (False).
+        :param rsize:
+            Requested size in bytes. The true allocated size will be at least
+            this much, but may be rounded up to the next block size multiple,
+            depending on the running platform.
+        """
+        super().__init__(name=name, create=create, size=rsize)
+        self.rsize = rsize
         self._unlink_on_dispose = create
         if _is_worker:
             # HACK: Remove this shared memory block from the resource_tracker,
-            # which wants to clean up shared memory blocks after all known
-            # references are done using them.
+            # which would otherwise want to clean up shared memory blocks
+            # after all known references are done using them.
             #
             # There is one resource_tracker per Python process, and they will
             # each try to delete shared memory blocks known to them when they
@@ -60,7 +76,37 @@ class SharedMemory(shared_memory.SharedMemory):
             # As such, the rule Appose follows is: let the service process
             # always handle cleanup of shared memory blocks, regardless of
             # which process initially allocated it.
-            resource_tracker.unregister(self._name, "shared_memory")
+            try:
+                resource_tracker.unregister(self._name, "shared_memory")
+            except ModuleNotFoundError:
+                # Unfortunately, on (some?) Windows systems, we see the error:
+                #
+                # Traceback (most recent call last):                                                # noqa: E501
+                #   File "...\site-packages\appose\types.py", line 97, in decode                    # noqa: E501
+                #     return json.loads(the_json, object_hook=_appose_object_hook)                  # noqa: E501
+                #   File "...\lib\json\__init__.py", line 359, in loads                             # noqa: E501
+                #     return cls(**kw).decode(s)                                                    # noqa: E501
+                #   File "...\lib\json\decoder.py", line 337, in decode                             # noqa: E501
+                #     obj, end = self.raw_decode(s, idx=_w(s, 0).end())                             # noqa: E501
+                #   File "...\lib\json\decoder.py", line 353, in raw_decode                         # noqa: E501
+                #     obj, end = self.scan_once(s, idx)                                             # noqa: E501
+                #   File "...\site-packages\appose\types.py", line 177, in _appose_object_hook      # noqa: E501
+                #     return SharedMemory(name=(obj["name"]), size=(obj["size"]))                   # noqa: E501
+                #   File "...\site-packages\appose\types.py", line 63, in __init__                  # noqa: E501
+                #     resource_tracker.unregister(self._name, "shared_memory")                      # noqa: E501
+                #   File "...\lib\multiprocessing\resource_tracker.py", line 159, in unregister     # noqa: E501
+                #     self._send('UNREGISTER', name, rtype)                                         # noqa: E501
+                #   File "...\lib\multiprocessing\resource_tracker.py", line 162, in _send          # noqa: E501
+                #     self.ensure_running()                                                         # noqa: E501
+                #   File "...\lib\multiprocessing\resource_tracker.py", line 129, in ensure_running # noqa: E501
+                #     pid = util.spawnv_passfds(exe, args, fds_to_pass)                             # noqa: E501
+                #   File "...\lib\multiprocessing\util.py", line 448, in spawnv_passfds             # noqa: E501
+                #     import _posixsubprocess                                                       # noqa: E501
+                # ModuleNotFoundError: No module named '_posixsubprocess'                           # noqa: E501
+                #
+                # A bug in Python? Regardless: we guard against it here.
+                # See also: https://github.com/imglib/imglib2-appose/issues/1
+                pass
 
     def unlink_on_dispose(self, value: bool) -> None:
         """
@@ -116,7 +162,7 @@ class NDArray:
         self.shape = shape
         self.shm = (
             SharedMemory(
-                create=True, size=ceil(prod(shape) * _bytes_per_element(dtype))
+                create=True, rsize=ceil(prod(shape) * _bytes_per_element(dtype))
             )
             if shm is None
             else shm
@@ -127,7 +173,7 @@ class NDArray:
             f"NDArray("
             f"dtype='{self.dtype}', "
             f"shape={self.shape}, "
-            f"shm='{self.shm.name}' ({self.shm.size}))"
+            f"shm='{self.shm.name}' ({self.shm.rsize}))"
         )
 
     def ndarray(self):
@@ -158,7 +204,7 @@ class _ApposeJSONEncoder(json.JSONEncoder):
             return {
                 "appose_type": "shm",
                 "name": obj.name,
-                "size": obj.size,
+                "rsize": obj.rsize,
             }
         if isinstance(obj, NDArray):
             return {
@@ -174,7 +220,7 @@ def _appose_object_hook(obj: Dict):
     atype = obj.get("appose_type")
     if atype == "shm":
         # Attach to existing shared memory block.
-        return SharedMemory(name=(obj["name"]), size=(obj["size"]))
+        return SharedMemory(name=(obj["name"]), rsize=(obj["rsize"]))
     elif atype == "ndarray":
         return NDArray(obj["dtype"], obj["shape"], obj["shm"])
     else:

{appose-0.2.0 → appose-0.6.0/src/appose.egg-info}/PKG-INFO

@@ -1,9 +1,9 @@
-Metadata-Version: 2.1
+Metadata-Version: 2.4
 Name: appose
-Version: 0.2.0
+Version: 0.6.0
 Summary: Appose: multi-language interprocess cooperation with shared memory.
 Author: Appose developers
-License: Simplified BSD License
+License-Expression: BSD-2-Clause
 Project-URL: homepage, https://github.com/apposed/appose-python
 Project-URL: documentation, https://github.com/apposed/appose-python/blob/main/README.md
 Project-URL: source, https://github.com/apposed/appose-python
@@ -17,7 +17,7 @@ Classifier: Intended Audience :: Science/Research
 Classifier: Programming Language :: Python :: 3 :: Only
 Classifier: Programming Language :: Python :: 3.10
 Classifier: Programming Language :: Python :: 3.11
-Classifier: License :: OSI Approved :: BSD License
+Classifier: Programming Language :: Python :: 3.12
 Classifier: Operating System :: Microsoft :: Windows
 Classifier: Operating System :: Unix
 Classifier: Operating System :: MacOS
@@ -40,6 +40,7 @@ Requires-Dist: pytest; extra == "dev"
 Requires-Dist: numpy; extra == "dev"
 Requires-Dist: toml; extra == "dev"
 Requires-Dist: validate-pyproject[all]; extra == "dev"
+Dynamic: license-file
 
 # Appose Python
 

{appose-0.2.0 → appose-0.6.0}/tests/test_appose.py

@@ -2,7 +2,7 @@
 # #%L
 # Appose: multi-language interprocess cooperation with shared memory.
 # %%
-# Copyright (C) 2023 - 2024 Appose developers.
+# Copyright (C) 2023 - 2025 Appose developers.
 # %%
 # Redistribution and use in source and binary forms, with or without
 # modification, are permitted provided that the following conditions are met:
@@ -27,6 +27,8 @@
 # #L%
 ###
 
+import os
+
 import appose
 from appose.service import ResponseType, Service, TaskStatus
 
@@ -55,18 +57,36 @@ while v != 1:
 task.outputs["result"] = time
 """
 
+sqrt_import = """
+from math import sqrt
+def sqrt_age(age):
+    return sqrt(age)
+task.outputs["result"] = sqrt_age(age)
+"""
+
+main_thread_check_groovy = """
+task.outputs["thread"] = Thread.currentThread().getName()
+"""
+
+main_thread_check_python = """
+import threading
+task.outputs["thread"] = threading.current_thread().name
+"""
+
 
 def test_groovy():
     env = appose.system()
     # NB: For now, use bin/test.sh to copy the needed JARs.
     class_path = ["target/dependency/*"]
     with env.groovy(class_path=class_path) as service:
+        maybe_debug(service)
         execute_and_assert(service, collatz_groovy)
 
 
 def test_python():
     env = appose.system()
     with env.python() as service:
+        maybe_debug(service)
         execute_and_assert(service, collatz_python)
 
 
@@ -83,6 +103,49 @@ def test_service_startup_failure():
         ) == str(e)
 
 
+def test_scope():
+    env = appose.system()
+    with env.python() as service:
+        maybe_debug(service)
+        task = service.task(sqrt_import, {"age": 100})
+        task.start()
+        task.wait_for()
+        result = round(task.outputs.get("result"))
+        assert result == 10
+
+
+def test_main_thread_queue_groovy():
+    env = appose.system()
+    # NB: For now, use bin/test.sh to copy the needed JARs.
+    class_path = ["target/dependency/*"]
+    with env.groovy(class_path=class_path) as service:
+        maybe_debug(service)
+
+        task = service.task(main_thread_check_groovy, queue="main")
+        task.wait_for()
+        thread = task.outputs.get("thread")
+        assert thread == "main"
+
+        task = service.task(main_thread_check_groovy)
+        task.wait_for()
+        thread = task.outputs.get("thread")
+        assert thread != "main"
+
+
+def test_main_thread_queue_python():
+    env = appose.system()
+    with env.python() as service:
+        task = service.task(main_thread_check_python, queue="main")
+        task.wait_for()
+        thread = task.outputs.get("thread")
+        assert thread == "MainThread"
+
+        task = service.task(main_thread_check_python)
+        task.wait_for()
+        thread = task.outputs.get("thread")
+        assert thread != "MainThread"
+
+
 def execute_and_assert(service: Service, script: str):
     task = service.task(script)
 
@@ -91,10 +154,10 @@ def execute_and_assert(service: Service, script: str):
     class TaskState:
         def __init__(self, event):
             self.response_type = event.response_type
+            self.message = event.message
+            self.current = event.current
+            self.maximum = event.maximum
             self.status = event.task.status
-            self.message = event.task.message
-            self.current = event.task.current
-            self.maximum = event.task.maximum
             self.error = event.task.error
 
     events = []
@@ -116,8 +179,8 @@ def execute_and_assert(service: Service, script: str):
     assert ResponseType.LAUNCH == launch.response_type
     assert TaskStatus.RUNNING == launch.status
     assert launch.message is None
-    assert 0 == launch.current
-    assert 1 == launch.maximum
+    assert launch.current is None
+    assert launch.maximum is None
     assert launch.error is None
 
     v = 9999
@@ -128,13 +191,19 @@ def execute_and_assert(service: Service, script: str):
         assert TaskStatus.RUNNING == update.status
         assert f"[{i}] -> {v}" == update.message
         assert i == update.current
-        assert 1 == update.maximum
+        assert update.maximum is None
         assert update.error is None
 
     completion = events[92]
     assert ResponseType.COMPLETION == completion.response_type
     assert TaskStatus.COMPLETE == completion.status
-    assert "[90] -> 1" == completion.message
-    assert 90 == completion.current
-    assert 1 == completion.maximum
+    assert completion.message is None  # no message from non-UPDATE response
+    assert completion.current is None  # no current from non-UPDATE response
+    assert completion.maximum is None  # no maximum from non-UPDATE response
     assert completion.error is None
+
+
+def maybe_debug(service):
+    debug = os.getenv("DEBUG")
+    if debug:
+        service.debug(print)

{appose-0.2.0 → appose-0.6.0}/tests/test_shm.py

@@ -2,7 +2,7 @@
 # #%L
 # Appose: multi-language interprocess cooperation with shared memory.
 # %%
-# Copyright (C) 2023 - 2024 Appose developers.
+# Copyright (C) 2023 - 2025 Appose developers.
 # %%
 # Redistribution and use in source and binary forms, with or without
 # modification, are permitted provided that the following conditions are met:
@@ -31,6 +31,7 @@ import appose
 from appose.service import TaskStatus
 
 ndarray_inspect = """
+task.outputs["rsize"] = data.shm.rsize
 task.outputs["size"] = data.shm.size
 task.outputs["dtype"] = data.dtype
 task.outputs["shape"] = data.shape
@@ -41,7 +42,7 @@ task.outputs["sum"] = sum(v for v in data.shm.buf)
 def test_ndarray():
     env = appose.system()
     with env.python() as service:
-        with appose.SharedMemory(create=True, size=2 * 2 * 20 * 25) as shm:
+        with appose.SharedMemory(create=True, rsize=2 * 2 * 20 * 25) as shm:
             # Construct the data.
             shm.buf[0] = 123
             shm.buf[456] = 78
@@ -54,7 +55,10 @@ def test_ndarray():
 
             # Validate the execution result.
             assert TaskStatus.COMPLETE == task.status
-            assert 2 * 20 * 25 * 2 == task.outputs["size"]
+            # The requested size is 2*20*25*2=2000, but actual allocated
+            # shm size varies by platform; e.g. on macOS it is 16384.
+            assert 2 * 20 * 25 * 2 == task.outputs["rsize"]
+            assert task.outputs["size"] >= task.outputs["rsize"]
             assert "uint16" == task.outputs["dtype"]
             assert [2, 20, 25] == task.outputs["shape"]
             assert 123 + 78 + 210 == task.outputs["sum"]

{appose-0.2.0 → appose-0.6.0}/tests/test_types.py

@@ -2,7 +2,7 @@
 # #%L
 # Appose: multi-language interprocess cooperation with shared memory.
 # %%
-# Copyright (C) 2023 - 2024 Appose developers.
+# Copyright (C) 2023 - 2025 Appose developers.
 # %%
 # Redistribution and use in source and binary forms, with or without
 # modification, are permitted provided that the following conditions are met:
@@ -56,7 +56,7 @@ class TypesTest(unittest.TestCase):
             '"shm":{'                   # noqa: E131
                 '"appose_type":"shm",'  # noqa: E131
                 '"name":"SHM_NAME",'    # noqa: E131
-                '"size":4000'           # noqa: E131
+                '"rsize":4000'          # noqa: E131
             "}"                         # noqa: E131
         "}"
         # fmt: on
@@ -103,7 +103,7 @@ class TypesTest(unittest.TestCase):
             self.assertEqual(expected, json_str)
 
     def test_decode(self):
-        with appose.SharedMemory(create=True, size=4000) as shm:
+        with appose.SharedMemory(create=True, rsize=4000) as shm:
             shm_name = shm.name
             data = appose.types.decode(self.JSON.replace("SHM_NAME", shm_name))
             self.assertIsNotNone(data)

appose-0.2.0/src/appose/python_worker.py

@@ -1,198 +0,0 @@
-###
-# #%L
-# Appose: multi-language interprocess cooperation with shared memory.
-# %%
-# Copyright (C) 2023 - 2024 Appose developers.
-# %%
-# Redistribution and use in source and binary forms, with or without
-# modification, are permitted provided that the following conditions are met:
-#
-# 1. Redistributions of source code must retain the above copyright notice,
-#    this list of conditions and the following disclaimer.
-# 2. Redistributions in binary form must reproduce the above copyright notice,
-#    this list of conditions and the following disclaimer in the documentation
-#    and/or other materials provided with the distribution.
-#
-# THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
-# AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
-# IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
-# ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDERS OR CONTRIBUTORS BE
-# LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
-# CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
-# SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
-# INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
-# CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
-# ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
-# POSSIBILITY OF SUCH DAMAGE.
-# #L%
-###
-
-"""
-The Appose worker for running Python scripts.
-
-Like all Appose workers, this program conforms to the Appose worker process
-contract, meaning it accepts requests on stdin and produces responses on
-stdout, both formatted according to Appose's assumptions.
-
-For details, see the Appose README:
-https://github.com/apposed/appose/blob/-/README.md#workers
-"""
-
-import ast
-import sys
-import traceback
-from threading import Thread
-from typing import Optional
-
-# NB: Avoid relative imports so that this script can be run standalone.
-from appose.service import RequestType, ResponseType
-from appose.types import Args, _set_worker, decode, encode
-
-
-class Task:
-    def __init__(self, uuid: str) -> None:
-        self.uuid = uuid
-        self.outputs = {}
-        self.cancel_requested = False
-
-    def update(
-        self,
-        message: Optional[str] = None,
-        current: Optional[int] = None,
-        maximum: Optional[int] = None,
-    ) -> None:
-        args = {}
-        if message is not None:
-            args["message"] = str(message)
-        if current is not None:
-            try:
-                args["current"] = int(current)
-            except ValueError:
-                pass
-        if maximum is not None:
-            try:
-                args["maximum"] = int(maximum)
-            except ValueError:
-                pass
-        self._respond(ResponseType.UPDATE, args)
-
-    def cancel(self) -> None:
-        self._respond(ResponseType.CANCELATION, None)
-
-    def fail(self, error: Optional[str] = None) -> None:
-        args = None if error is None else {"error": error}
-        self._respond(ResponseType.FAILURE, args)
-
-    def _start(self, script: str, inputs: Optional[Args]) -> None:
-        def execute_script():
-            # Populate script bindings.
-            binding = {"task": self}
-            if inputs is not None:
-                binding.update(inputs)
-
-            # Inform the calling process that the script is launching.
-            self._report_launch()
-
-            # Execute the script.
-            # result = exec(script, locals=binding)
-            result = None
-            try:
-                # NB: Execute the block, except for the last statement,
-                # which we evaluate instead to get its return value.
-                # Credit: https://stackoverflow.com/a/39381428/1207769
-
-                block = ast.parse(script, mode="exec")
-                last = None
-                if (
-                    len(block.body) > 0
-                    and hasattr(block.body[-1], "value")
-                    and not isinstance(block.body[-1], ast.Assign)
-                ):
-                    # Last statement of the script looks like an expression. Evaluate!
-                    last = ast.Expression(block.body.pop().value)
-
-                _globals = {}
-                exec(compile(block, "<string>", mode="exec"), _globals, binding)
-                if last is not None:
-                    result = eval(
-                        compile(last, "<string>", mode="eval"), _globals, binding
-                    )
-            except Exception:
-                self.fail(traceback.format_exc())
-                return
-
-            # Report the results to the Appose calling process.
-            if isinstance(result, dict):
-                # Script produced a dict; add all entries to the outputs.
-                self.outputs.update(result)
-            elif result is not None:
-                # Script produced a non-dict; add it alone to the outputs.
-                self.outputs["result"] = result
-
-            self._report_completion()
-
-        # TODO: Consider whether to retain a reference to this Thread, and
-        # expose a "force" option for cancelation that kills it forcibly; see:
-        # https://www.geeksforgeeks.org/python-different-ways-to-kill-a-thread/
-        Thread(target=execute_script, name=f"Appose-{self.uuid}").start()
-
-    def _report_launch(self) -> None:
-        self._respond(ResponseType.LAUNCH, None)
-
-    def _report_completion(self) -> None:
-        args = None if self.outputs is None else {"outputs": self.outputs}
-        self._respond(ResponseType.COMPLETION, args)
-
-    def _respond(self, response_type: ResponseType, args: Optional[Args]) -> None:
-        response = {"task": self.uuid, "responseType": response_type.value}
-        if args is not None:
-            response.update(args)
-        # NB: Flush is necessary to ensure service receives the data!
-        try:
-            print(encode(response), flush=True)
-        except Exception:
-            # Encoding can fail due to unsupported types, when the response
-            # or its elements are not supported by JSON encoding.
-            # No matter what goes wrong, we want to tell the caller.
-            if response_type is ResponseType.FAILURE:
-                # TODO: How to address this hypothetical case
-                # of a failure message triggering another failure?
-                raise
-            self.fail(traceback.format_exc())
-
-
-def main() -> None:
-    _set_worker(True)
-
-    tasks = {}
-
-    while True:
-        try:
-            line = input().strip()
-        except EOFError:
-            break
-        if not line:
-            break
-
-        request = decode(line)
-        uuid = request.get("task")
-        request_type = request.get("requestType")
-
-        match RequestType(request_type):
-            case RequestType.EXECUTE:
-                script = request.get("script")
-                inputs = request.get("inputs")
-                task = Task(uuid)
-                tasks[uuid] = task
-                task._start(script, inputs)
-
-            case RequestType.CANCEL:
-                task = tasks.get(uuid)
-                if task is None:
-                    print(f"No such task: {uuid}", file=sys.stderr)
-                    continue
-                task.cancel_requested = True
-
-
-if __name__ == "__main__":
-    main()