appose 0.1.0__tar.gz → 0.4.0__tar.gz

{appose-0.1.0 → appose-0.4.0}/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/src/appose.egg-info → appose-0.4.0}/PKG-INFO

@@ -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
@@ -27,8 +27,20 @@ Classifier: Topic :: Software Development :: Libraries :: Python Modules
 Classifier: Topic :: Utilities
 Requires-Python: >=3.10
 Description-Content-Type: text/markdown
-Provides-Extra: dev
 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"
+Dynamic: license-file
 
 # Appose Python
 
@@ -60,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),
@@ -87,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:
@@ -96,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:
 
@@ -158,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.1.0 → appose-0.4.0}/README.md

@@ -28,16 +28,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),
@@ -55,6 +45,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:
@@ -64,12 +64,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:
 
@@ -126,3 +126,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.1.0 → appose-0.4.0}/pyproject.toml

@@ -4,9 +4,9 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "appose"
-version = "0.1.0"
+version = "0.4.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",
@@ -54,7 +54,7 @@ homepage = "https://github.com/apposed/appose-python"
 documentation = "https://github.com/apposed/appose-python/blob/main/README.md"
 source = "https://github.com/apposed/appose-python"
 download = "https://pypi.org/project/appose-python"
-tracker = "https://github.com/apposed/appose-python/issues"
+tracker = "https://github.com/apposed/appose/issues"
 
 [tool.setuptools]
 package-dir = {"" = "src"}

{appose-0.1.0 → appose-0.4.0}/src/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-0.1.0 → appose-0.4.0}/src/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-0.1.0 → appose-0.4.0}/src/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-0.1.0 → appose-0.4.0}/src/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()