appose 0.1.0__py3-none-any.whl → 0.4.0__py3-none-any.whl

appose/__init__.py

@@ -2,7 +2,7 @@
 # #%L
 # Appose: multi-language interprocess cooperation with shared memory.
 # %%
-# Copyright (C) 2023 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
@@ -52,7 +50,7 @@ Here is a very simple example written in Python:
     Task task = groovy.task("""
         5 + 6
     """)
-    task.waitFor()
+    task.wait_for()
     result = task.outputs.get("result")
     assert 11 == result
 
@@ -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"]
@@ -103,7 +101,7 @@ And here is an example using a few more of Appose's features:
         # Task is taking too long; request a cancelation.
         task.cancel()
 
-    task.waitFor()
+    task.wait_for()
 
 Of course, the above examples could have been done all in Python. But
 hopefully they hint at the possibilities of easy cross-language integration.
@@ -127,13 +125,100 @@ 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
 
 from .environment import Builder, Environment
+from .types import NDArray, SharedMemory  # noqa: F401
 
 
 def base(directory: Path) -> Builder:

appose/environment.py

@@ -2,7 +2,7 @@
 # #%L
 # Appose: multi-language interprocess cooperation with shared memory.
 # %%
-# Copyright (C) 2023 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:
@@ -58,6 +58,7 @@ class Environment:
         """
         python_exes = [
             "python",
+            "python3",
             "python.exe",
             "bin/python",
             "bin/python.exe",
@@ -109,8 +110,9 @@ class Environment:
         # TODO: Ensure that the classpath includes Appose and its dependencies.
 
         # Append any explicitly requested classpath elements.
-        for element in class_path:
-            cp[element] = None
+        if class_path is not None:
+            for element in class_path:
+                cp[element] = None
 
         # Build up the service arguments.
         args = [

appose/paths.py

@@ -2,7 +2,7 @@
 # #%L
 # Appose: multi-language interprocess cooperation with shared memory.
 # %%
-# Copyright (C) 2023 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:
@@ -51,6 +51,6 @@ def find_exe(dirs: Sequence[str], exes: Sequence[str]) -> Optional[Path]:
             # Candidate is a relative path; check beneath each given directory.
             for d in dirs:
                 f = Path(d) / exe
-                if can_execute(f):
+                if can_execute(f) and not f.is_dir():
                     return f
     return None

appose/python_worker.py

@@ -2,7 +2,7 @@
 # #%L
 # Appose: multi-language interprocess cooperation with shared memory.
 # %%
-# Copyright (C) 2023 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:
@@ -28,39 +28,57 @@
 ###
 
 """
-TODO
+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
+from time import sleep
+from typing import Any, Dict, Optional
 
 # NB: Avoid relative imports so that this script can be run standalone.
 from appose.service import RequestType, ResponseType
-from appose.types import Args, decode, encode
+from appose.types import Args, _set_worker, decode, encode
 
 
 class Task:
     def __init__(self, uuid: str) -> None:
         self.uuid = uuid
         self.outputs = {}
+        self.finished = False
         self.cancel_requested = False
+        self.thread = None  # Initialize thread attribute
 
     def update(
         self,
         message: Optional[str] = None,
         current: Optional[int] = None,
         maximum: Optional[int] = None,
+        info: Optional[Dict[str, Any]] = None,
     ) -> None:
         args = {}
         if message is not None:
-            args["message"] = message
+            args["message"] = str(message)
         if current is not None:
-            args["current"] = current
+            try:
+                args["current"] = int(current)
+            except ValueError:
+                pass
         if maximum is not None:
-            args["maximum"] = maximum
+            try:
+                args["maximum"] = int(maximum)
+            except ValueError:
+                pass
+        args["info"] = info
         self._respond(ResponseType.UPDATE, args)
 
     def cancel(self) -> None:
@@ -74,7 +92,6 @@ class Task:
         def execute_script():
             # Populate script bindings.
             binding = {"task": self}
-            # TODO: Magically convert shared memory image inputs.
             if inputs is not None:
                 binding.update(inputs)
 
@@ -99,7 +116,14 @@ class Task:
                     # Last statement of the script looks like an expression. Evaluate!
                     last = ast.Expression(block.body.pop().value)
 
-                _globals = {}
+                # 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(
@@ -119,10 +143,24 @@ class Task:
 
             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()
+        # HACK: Pre-load toplevel import statements before running the script
+        # as a whole on its own Thread. Why? Because on Windows, some imports
+        # (e.g. numpy) may lead to hangs if loaded from a separate thread.
+        # See https://github.com/apposed/appose/issues/13.
+        block = ast.parse(script, mode="exec")
+        import_nodes = [
+            node
+            for node in block.body
+            if isinstance(node, (ast.Import, ast.ImportFrom))
+        ]
+        import_block = ast.Module(body=import_nodes, type_ignores=[])
+        compiled_imports = compile(import_block, filename="<imports>", mode="exec")
+        exec(compiled_imports, globals())
+
+        # Create a thread and save a reference to it, in case its script
+        # ends up killing the thread. This happens e.g. if it calls sys.exit.
+        self.thread = Thread(target=execute_script, name=f"Appose-{self.uuid}")
+        self.thread.start()
 
     def _report_launch(self) -> None:
         self._respond(ResponseType.LAUNCH, None)
@@ -132,15 +170,56 @@ class Task:
         self._respond(ResponseType.COMPLETION, args)
 
     def _respond(self, response_type: ResponseType, args: Optional[Args]) -> None:
-        response = {"task": self.uuid, "responseType": response_type.value}
+        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!
-        print(encode(response), flush=True)
+        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())
 
 
 def main() -> None:
+    _set_worker(True)
+
     tasks = {}
+    running = True
+
+    def cleanup_threads():
+        while running:
+            sleep(0.05)
+            dead = {
+                uuid: task
+                for uuid, task in tasks.items()
+                if task.thread is not None and not task.thread.is_alive()
+            }
+            for uuid, task in dead.items():
+                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")
+
+    Thread(target=cleanup_threads, name="Appose-Janitor").start()
 
     while True:
         try:
@@ -165,12 +244,12 @@ def main() -> None:
             case RequestType.CANCEL:
                 task = tasks.get(uuid)
                 if task is None:
-                    # TODO: proper logging
-                    # Maybe should stdout the error back to Appose calling process.
                     print(f"No such task: {uuid}", file=sys.stderr)
                     continue
                 task.cancel_requested = True
 
+    running = False
+
 
 if __name__ == "__main__":
     main()

appose/service.py

@@ -2,7 +2,7 @@
 # #%L
 # Appose: multi-language interprocess cooperation with shared memory.
 # %%
-# Copyright (C) 2023 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:
@@ -61,6 +61,7 @@ class Service:
         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
 
     def debug(self, debug_callback: Callable[[Any], Any]) -> None:
@@ -101,8 +102,12 @@ class Service:
         self._stderr_thread = threading.Thread(
             target=self._stderr_loop, name=f"{prefix}-Stderr"
         )
+        self._monitor_thread = threading.Thread(
+            target=self._monitor_loop, name=f"{prefix}-Monitor"
+        )
         self._stdout_thread.start()
         self._stderr_thread.start()
+        self._monitor_thread.start()
 
     def task(self, script: str, inputs: Optional[Args] = None) -> "Task":
         """
@@ -131,15 +136,24 @@ class Service:
         """
         Input loop processing lines from the worker's stdout stream.
         """
-        # noinspection PyBroadException
-        try:
-            while True:
-                line = self._process.stdout.readline()
-                self._debug_service("<worker stdout closed>" if line is None else line)
+        while True:
+            stdout = self._process.stdout
+            # noinspection PyBroadException
+            try:
+                line = None if stdout is None else stdout.readline()
+            except Exception:
+                # Something went wrong reading the line. Panic!
+                self._debug_service(format_exc())
+                break
+
+            if not line:  # readline returns empty string upon EOF
+                self._debug_service("<worker stdout closed>")
+                return
 
-                if line is None:
-                    return  # pipe closed
+            # noinspection PyBroadException
+            try:
                 response = decode(line)
+                self._debug_service(line)  # Echo the line to the debug listener.
                 uuid = response.get("task")
                 if uuid is None:
                     self._debug_service("Invalid service message: {line}")
@@ -150,8 +164,10 @@ class Service:
                     continue
                 # noinspection PyProtectedMember
                 task._handle(response)
-        except Exception:
-            self._debug_service(format_exc())
+            except Exception:
+                # Something went wrong decoding the line of JSON.
+                # Skip it and keep going, but log it first.
+                self._debug_service(f"<INVALID> {line}")
 
     def _stderr_loop(self) -> None:
         """
@@ -160,14 +176,37 @@ class Service:
         # noinspection PyBroadException
         try:
             while True:
-                line = self._process.stderr.readline()
-                if line is None:
+                stderr = self._process.stderr
+                line = None if stderr is None else stderr.readline()
+                if not line:  # readline returns empty string upon EOF
                     self._debug_service("<worker stderr closed>")
                     return
                 self._debug_worker(line)
         except Exception:
             self._debug_service(format_exc())
 
+    def _monitor_loop(self) -> None:
+        # Wait until the worker process terminates.
+        self._process.wait()
+
+        # Do some sanity checks.
+        exit_code = self._process.returncode
+        if exit_code != 0:
+            self._debug_service(
+                f"<worker process terminated with exit code {exit_code}>"
+            )
+        task_count = len(self._tasks)
+        if task_count > 0:
+            self._debug_service(
+                f"<worker process terminated with {task_count} pending tasks>"
+            )
+
+        # Notify any remaining tasks about the process crash.
+        for task in self._tasks.values():
+            task._crash()
+
+        self._tasks.clear()
+
     def _debug_service(self, message: str) -> None:
         self._debug("SERVICE", message)
 
@@ -190,15 +229,17 @@ class TaskStatus(Enum):
     COMPLETE = "COMPLETE"
     CANCELED = "CANCELED"
     FAILED = "FAILED"
+    CRASHED = "CRASHED"
 
     def is_finished(self):
         """
-        True iff status is COMPLETE, CANCELED, or FAILED.
+        True iff status is COMPLETE, CANCELED, FAILED, or CRASHED.
         """
         return self in (
             TaskStatus.COMPLETE,
             TaskStatus.CANCELED,
             TaskStatus.FAILED,
+            TaskStatus.CRASHED,
         )
 
 
@@ -213,12 +254,40 @@ class ResponseType(Enum):
     COMPLETION = "COMPLETION"
     CANCELATION = "CANCELATION"
     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: Optional[str] = None,
+        current: Optional[int] = None,
+        maximum: Optional[int] = None,
+        info: Optional[Dict[str, Any]] = None,
+    ) -> None:
         self.task: "Task" = task
         self.response_type: ResponseType = response_type
+        self.message: Optional[str] = message
+        self.current: Optional[int] = current
+        self.maximum: Optional[int] = maximum
+        self.info: Optional[Dict[str, Any]] = info
+
+    def __str__(self):
+        return f"[{self.response_type}] {self.task}"
 
 
 # noinspection PyProtectedMember
@@ -309,13 +378,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
@@ -335,10 +399,25 @@ 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)
 
         if self.status.is_finished():
             with self.cv:
                 self.cv.notify_all()
+
+    def _crash(self):
+        event = TaskEvent(self, ResponseType.CRASH)
+        self.status = TaskStatus.CRASHED
+        for listener in self.listeners:
+            listener(event)
+        with self.cv:
+            self.cv.notify_all()
+
+    def __str__(self):
+        return f"{self.uuid=}, {self.status=}, {self.error=}"

appose/types.py

@@ -2,7 +2,7 @@
 # #%L
 # Appose: multi-language interprocess cooperation with shared memory.
 # %%
-# Copyright (C) 2023 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:
@@ -28,14 +28,216 @@
 ###
 
 import json
-from typing import Any, Dict
+import re
+from math import ceil, prod
+from multiprocessing import resource_tracker, shared_memory
+from typing import Any, Dict, Sequence, Union
 
 Args = Dict[str, Any]
 
 
+class SharedMemory(shared_memory.SharedMemory):
+    """
+    An enhanced version of Python's multiprocessing.shared_memory.SharedMemory
+    class which can be used with a `with` statement. When the program flow
+    exits the `with` block, this class's `dispose()` method will be invoked,
+    which might call `close()` or `unlink()` depending on the value of its
+    `unlink_on_dispose` flag.
+    """
+
+    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 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
+            # are shutting down, even when other processes still need them.
+            #
+            # 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.
+            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:
+        """
+        Set whether the `unlink()` method should be invoked to destroy
+        the shared memory block when the `dispose()` method is called.
+
+        Note: dispose() is the method called when exiting a `with` block.
+
+        By default, shared memory objects constructed with `create=True`
+        will behave this way, whereas shared memory objects constructed
+        with `create=False` will not. But this method allows to override
+        the behavior.
+        """
+        self._unlink_on_dispose = value
+
+    def dispose(self) -> None:
+        if self._unlink_on_dispose:
+            self.unlink()
+        else:
+            self.close()
+
+    def __enter__(self) -> "SharedMemory":
+        return self
+
+    def __exit__(self, exc_type, exc_value, exc_tb) -> None:
+        self.dispose()
+
+
 def encode(data: Args) -> str:
-    return json.dumps(data)
+    return json.dumps(data, cls=_ApposeJSONEncoder, separators=(",", ":"))
 
 
 def decode(the_json: str) -> Args:
-    return json.loads(the_json)
+    return json.loads(the_json, object_hook=_appose_object_hook)
+
+
+class NDArray:
+    """
+    Data structure for a multi-dimensional array.
+    The array contains elements of a data type, arranged in
+    a particular shape, and flattened into SharedMemory.
+    """
+
+    def __init__(self, dtype: str, shape: Sequence[int], shm: SharedMemory = None):
+        """
+        Create an NDArray.
+        :param dtype: The type of the data elements; e.g. int8, uint8, float32, float64.
+        :param shape: The dimensional extents; e.g. a stack of 7 image planes
+                      with resolution 512x512 would have shape [7, 512, 512].
+        :param shm: The SharedMemory containing the array data, or None to create it.
+        """
+        self.dtype = dtype
+        self.shape = shape
+        self.shm = (
+            SharedMemory(
+                create=True, rsize=ceil(prod(shape) * _bytes_per_element(dtype))
+            )
+            if shm is None
+            else shm
+        )
+
+    def __str__(self):
+        return (
+            f"NDArray("
+            f"dtype='{self.dtype}', "
+            f"shape={self.shape}, "
+            f"shm='{self.shm.name}' ({self.shm.rsize}))"
+        )
+
+    def ndarray(self):
+        """
+        Create a NumPy ndarray object for working with the array data.
+        No array data is copied; the NumPy array wraps the same SharedMemory.
+        Requires the numpy package to be installed.
+        """
+        try:
+            import numpy
+
+            return numpy.ndarray(
+                prod(self.shape), dtype=self.dtype, buffer=self.shm.buf
+            ).reshape(self.shape)
+        except ModuleNotFoundError:
+            raise ImportError("NumPy is not available.")
+
+    def __enter__(self) -> "NDArray":
+        return self
+
+    def __exit__(self, exc_type, exc_value, exc_tb) -> None:
+        self.shm.dispose()
+
+
+class _ApposeJSONEncoder(json.JSONEncoder):
+    def default(self, obj):
+        if isinstance(obj, SharedMemory):
+            return {
+                "appose_type": "shm",
+                "name": obj.name,
+                "rsize": obj.rsize,
+            }
+        if isinstance(obj, NDArray):
+            return {
+                "appose_type": "ndarray",
+                "dtype": obj.dtype,
+                "shape": obj.shape,
+                "shm": obj.shm,
+            }
+        return super().default(obj)
+
+
+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"]), rsize=(obj["rsize"]))
+    elif atype == "ndarray":
+        return NDArray(obj["dtype"], obj["shape"], obj["shm"])
+    else:
+        return obj
+
+
+def _bytes_per_element(dtype: str) -> Union[int, float]:
+    try:
+        bits = int(re.sub("[^0-9]", "", dtype))
+    except ValueError:
+        raise ValueError(f"Invalid dtype: {dtype}")
+    return bits / 8
+
+
+_is_worker = False
+
+
+def _set_worker(value: bool) -> None:
+    global _is_worker
+    _is_worker = value

{appose-0.1.0.dist-info → appose-0.4.0.dist-info}/METADATA

@@ -1,14 +1,14 @@
-Metadata-Version: 2.1
+Metadata-Version: 2.4
 Name: appose
-Version: 0.1.0
+Version: 0.4.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
 Project-URL: download, https://pypi.org/project/appose-python
-Project-URL: tracker, https://github.com/apposed/appose-python/issues
+Project-URL: tracker, https://github.com/apposed/appose/issues
 Keywords: java,javascript,python,cross-language,interprocess
 Classifier: Development Status :: 2 - Pre-Alpha
 Classifier: Intended Audience :: Developers
@@ -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
@@ -29,17 +29,18 @@ Requires-Python: >=3.10
 Description-Content-Type: text/markdown
 License-File: LICENSE.txt
 Provides-Extra: dev
-Requires-Dist: autopep8 ; extra == 'dev'
-Requires-Dist: black ; extra == 'dev'
-Requires-Dist: build ; extra == 'dev'
-Requires-Dist: flake8 ; extra == 'dev'
-Requires-Dist: flake8-pyproject ; extra == 'dev'
-Requires-Dist: flake8-typing-imports ; extra == 'dev'
-Requires-Dist: isort ; extra == 'dev'
-Requires-Dist: pytest ; extra == 'dev'
-Requires-Dist: numpy ; extra == 'dev'
-Requires-Dist: toml ; extra == 'dev'
-Requires-Dist: validate-pyproject[all] ; extra == 'dev'
+Requires-Dist: autopep8; extra == "dev"
+Requires-Dist: black; extra == "dev"
+Requires-Dist: build; extra == "dev"
+Requires-Dist: flake8; extra == "dev"
+Requires-Dist: flake8-pyproject; extra == "dev"
+Requires-Dist: flake8-typing-imports; extra == "dev"
+Requires-Dist: isort; extra == "dev"
+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
 
@@ -71,16 +72,6 @@ This is the **Python implementation of Appose**.
 
 The name of the package is `appose`.
 
-### Conda/Mamba
-
-To use [the conda-forge package](https://anaconda.org/conda-forge/appose),
-add `appose` to your `environment.yml`'s `dependencies` section:
-
-```yaml
-dependencies:
-  - appose
-```
-
 ### PyPI/Pip
 
 To use [the PyPI package](https://pypi.org/project/appose),
@@ -98,6 +89,16 @@ dependencies = [
 ]
 ```
 
+### Conda/Mamba
+
+To use [the conda-forge package](https://anaconda.org/conda-forge/appose),
+add `appose` to your `environment.yml`'s `dependencies` section:
+
+```yaml
+dependencies:
+  - appose
+```
+
 ## Examples
 
 Here is a minimal example for calling into Java from Python:
@@ -107,12 +108,12 @@ import appose
 env = appose.java(vendor="zulu", version="17").build()
 with env.groovy() as groovy:
     task = groovy.task("5 + 6")
-    task.waitFor()
-    result = task.outputs.get("result")
+    task.wait_for()
+    result = task.outputs["result"]
     assert 11 == result
 ```
 
-*Note: The `Appose.java` builder is planned, but not yet implemented.*
+*Note: The `appose.java` builder is planned, but not yet implemented.*
 
 Here is an example using a few more of Appose's features:
 
@@ -169,3 +170,9 @@ with env.groovy() as groovy:
 
 Of course, the above examples could have been done all in one language. But
 hopefully they hint at the possibilities of easy cross-language integration.
+
+## Issue tracker
+
+All implementations of Appose use the same issue tracker:
+
+https://github.com/apposed/appose/issues

appose-0.4.0.dist-info/RECORD

@@ -0,0 +1,11 @@
+appose/__init__.py,sha256=SRXmNEqFIAajVlwVCSAdhHQytRKZJiWI5Y5-xwioW0w,7544
+appose/environment.py,sha256=Kg-MfAcmVPDltwqvmrcvus-pP01SNUdn4bE2kdkIVuk,7597
+appose/paths.py,sha256=WgBHwnZdS3Ot8_hssFqUiTGnunolYRrHLf9rAfEU5r4,2182
+appose/python_worker.py,sha256=iQoz2t0glbXlR1lgynN-yXPIgtlAbCFtMYYpev-LZyU,9844
+appose/service.py,sha256=UQn1aoL3uQ8gPKS6nf5oYg0Ea1ZRsaQ3TfLCKeCZLPQ,14581
+appose/types.py,sha256=uidbt2JwWJ2D3Mbtc4Vl2sRP6WNgKjmfcHjJ9QLWkcs,10557
+appose-0.4.0.dist-info/licenses/LICENSE.txt,sha256=ZedidA6NyZclNlsx-vl9IVBWRAQSqXdNsCWgtFcwzIE,1313
+appose-0.4.0.dist-info/METADATA,sha256=cI_E4xetwcHlusk2UzSPOk6SWrNr_vBrGjOC_0H4CFo,5598
+appose-0.4.0.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
+appose-0.4.0.dist-info/top_level.txt,sha256=oqHhw2QGlaFfH3jMR9H5Cd6XYHdEv5DvK1am0iEFPW0,7
+appose-0.4.0.dist-info/RECORD,,

{appose-0.1.0.dist-info → appose-0.4.0.dist-info}/WHEEL

@@ -1,5 +1,5 @@
 Wheel-Version: 1.0
-Generator: bdist_wheel (0.40.0)
+Generator: setuptools (80.9.0)
 Root-Is-Purelib: true
 Tag: py3-none-any
 

{appose-0.1.0.dist-info → appose-0.4.0.dist-info/licenses}/LICENSE.txt

@@ -1,4 +1,4 @@
-Copyright (c) 2023, 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.1.0.dist-info/RECORD

@@ -1,11 +0,0 @@
-appose/__init__.py,sha256=IwFrDvIa6QOgV_RVgbIUfwyzswWB4RckLrzA9cts6IE,5340
-appose/environment.py,sha256=m1a7166dJq69XPWX53d63KoITqmH4fKMNPKbEGSxeC0,7524
-appose/paths.py,sha256=qBEWWf0LB0Cpk-l7u5uoPx9DTley6HltMTg0vJ2iFEQ,2156
-appose/python_worker.py,sha256=ZR6AtWXXk_Xcp0nSoWehbl7LYc6z18ZTTvo4QjO_MwU,6474
-appose/service.py,sha256=LqchMIxQXV6YF_l8sAGEyJapc2lSL6KBttcbLzdABFw,11966
-appose/types.py,sha256=uuVNLt21eT3JEPtRQCMQ_IcFnp2yLgrJTSxzAnxkKFY,1618
-appose-0.1.0.dist-info/LICENSE.txt,sha256=BOQExkI6YKvnUVMUqDbPuSxsY7XXL1XRUTTbnfEWII0,1306
-appose-0.1.0.dist-info/METADATA,sha256=6ohYqhKiVnCvof0UX4HAnMmarKKIyi7hRScNtEO1T9E,5477
-appose-0.1.0.dist-info/WHEEL,sha256=pkctZYzUS4AYVn6dJ-7367OJZivF2e8RA9b_ZBjif18,92
-appose-0.1.0.dist-info/top_level.txt,sha256=oqHhw2QGlaFfH3jMR9H5Cd6XYHdEv5DvK1am0iEFPW0,7
-appose-0.1.0.dist-info/RECORD,,