appose 0.1.0__tar.gz

appose-0.1.0/LICENSE.txt

@@ -0,0 +1,24 @@
+Copyright (c) 2023, Appose developers.
+All rights reserved.
+
+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 HOLDER 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.

appose-0.1.0/PKG-INFO

@@ -0,0 +1,160 @@
+Metadata-Version: 2.1
+Name: appose
+Version: 0.1.0
+Summary: Appose: multi-language interprocess cooperation with shared memory.
+Author: Appose developers
+License: Simplified BSD License
+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
+Keywords: java,javascript,python,cross-language,interprocess
+Classifier: Development Status :: 2 - Pre-Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Education
+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: Operating System :: Microsoft :: Windows
+Classifier: Operating System :: Unix
+Classifier: Operating System :: MacOS
+Classifier: Topic :: Scientific/Engineering
+Classifier: Topic :: Software Development :: Libraries :: Java Libraries
+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
+
+# Appose Python
+
+***WARNING: Appose is currently in incubation.
+Not all features described below are functional.
+This document has some aspirational aspects!***
+
+## What is Appose?
+
+Appose is a library for interprocess cooperation with shared memory.
+The guiding principles are *simplicity* and *efficiency*.
+
+Appose was written to enable **easy execution of Python-based deep learning
+from Java without copying tensors**, but its utility extends beyond that.
+The steps for using Appose are:
+
+* Build an Environment with the dependencies you need.
+* Create a Service linked to a *worker*, which runs in its own process.
+* Execute scripts on the worker by launching Tasks.
+* Receive status updates from the task asynchronously via callbacks.
+
+For more about Appose as a whole, see https://apposed.org.
+
+## What is this project?
+
+This is the **Python implementation of Appose**.
+
+## How do I use it?
+
+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),
+add `appose` to your project dependencies.
+
+Depending on how your project is set up, this might entail editing
+`requirements.txt`, `setup.py`, `setup.cfg`, and/or `pyproject.toml`.
+
+If you are just starting out, we recommend using `pyproject.toml` (see
+[this guide](https://packaging.python.org/en/latest/tutorials/packaging-projects/#creating-pyproject-toml)):
+
+```toml
+dependencies = [
+  "appose"
+]
+```
+
+## Examples
+
+Here is a minimal example for calling into Java from Python:
+
+```python
+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")
+    assert 11 == result
+```
+
+*Note: The `Appose.java` builder is planned, but not yet implemented.*
+
+Here is an example using a few more of Appose's features:
+
+```python
+import appose
+from time import sleep
+
+golden_ratio_in_groovy = """
+// Approximate the golden ratio using the Fibonacci sequence.
+previous = 0
+current = 1
+for (i=0; i<iterations; i++) {
+    if (task.cancelRequested) {
+        task.cancel()
+        break
+    }
+    task.update(null, i, iterations)
+    v = current
+    current += previous
+    previous = v
+}
+task.outputs["numer"] = current
+task.outputs["denom"] = previous
+"""
+
+env = appose.java(vendor="zulu", version="17").build()
+with env.groovy() as groovy:
+    task = groovy.task(golden_ratio_in_groovy)
+
+    def task_listener(event):
+        match event.responseType:
+            case ResponseType.UPDATE:
+                print(f"Progress {task.current}/{task.maximum}")
+            case ResponseType.COMPLETION:
+                numer = task.outputs["numer"]
+                denom = task.outputs["denom"]
+                ratio = numer / denom
+                print(f"Task complete. Result: {numer}/{denom} =~ {ratio}");
+            case ResponseType.CANCELATION:
+                print("Task canceled")
+            case ResponseType.FAILURE:
+                print(f"Task failed: {task.error}")
+
+    task.listen(task_listener)
+
+    task.start()
+    sleep(1)
+    if not task.status.is_finished():
+        # Task is taking too long; request a cancelation.
+        task.cancel()
+
+    task.wait_for()
+```
+
+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.

appose-0.1.0/README.md

@@ -0,0 +1,128 @@
+# Appose Python
+
+***WARNING: Appose is currently in incubation.
+Not all features described below are functional.
+This document has some aspirational aspects!***
+
+## What is Appose?
+
+Appose is a library for interprocess cooperation with shared memory.
+The guiding principles are *simplicity* and *efficiency*.
+
+Appose was written to enable **easy execution of Python-based deep learning
+from Java without copying tensors**, but its utility extends beyond that.
+The steps for using Appose are:
+
+* Build an Environment with the dependencies you need.
+* Create a Service linked to a *worker*, which runs in its own process.
+* Execute scripts on the worker by launching Tasks.
+* Receive status updates from the task asynchronously via callbacks.
+
+For more about Appose as a whole, see https://apposed.org.
+
+## What is this project?
+
+This is the **Python implementation of Appose**.
+
+## How do I use it?
+
+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),
+add `appose` to your project dependencies.
+
+Depending on how your project is set up, this might entail editing
+`requirements.txt`, `setup.py`, `setup.cfg`, and/or `pyproject.toml`.
+
+If you are just starting out, we recommend using `pyproject.toml` (see
+[this guide](https://packaging.python.org/en/latest/tutorials/packaging-projects/#creating-pyproject-toml)):
+
+```toml
+dependencies = [
+  "appose"
+]
+```
+
+## Examples
+
+Here is a minimal example for calling into Java from Python:
+
+```python
+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")
+    assert 11 == result
+```
+
+*Note: The `Appose.java` builder is planned, but not yet implemented.*
+
+Here is an example using a few more of Appose's features:
+
+```python
+import appose
+from time import sleep
+
+golden_ratio_in_groovy = """
+// Approximate the golden ratio using the Fibonacci sequence.
+previous = 0
+current = 1
+for (i=0; i<iterations; i++) {
+    if (task.cancelRequested) {
+        task.cancel()
+        break
+    }
+    task.update(null, i, iterations)
+    v = current
+    current += previous
+    previous = v
+}
+task.outputs["numer"] = current
+task.outputs["denom"] = previous
+"""
+
+env = appose.java(vendor="zulu", version="17").build()
+with env.groovy() as groovy:
+    task = groovy.task(golden_ratio_in_groovy)
+
+    def task_listener(event):
+        match event.responseType:
+            case ResponseType.UPDATE:
+                print(f"Progress {task.current}/{task.maximum}")
+            case ResponseType.COMPLETION:
+                numer = task.outputs["numer"]
+                denom = task.outputs["denom"]
+                ratio = numer / denom
+                print(f"Task complete. Result: {numer}/{denom} =~ {ratio}");
+            case ResponseType.CANCELATION:
+                print("Task canceled")
+            case ResponseType.FAILURE:
+                print(f"Task failed: {task.error}")
+
+    task.listen(task_listener)
+
+    task.start()
+    sleep(1)
+    if not task.status.is_finished():
+        # Task is taking too long; request a cancelation.
+        task.cancel()
+
+    task.wait_for()
+```
+
+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.

appose-0.1.0/pyproject.toml

@@ -0,0 +1,78 @@
+[build-system]
+requires = ["setuptools>=61.2"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "appose"
+version = "0.1.0"
+description = "Appose: multi-language interprocess cooperation with shared memory."
+license = {text = "Simplified BSD License"}
+authors = [{name = "Appose developers"}]
+readme = "README.md"
+keywords = ["java", "javascript", "python", "cross-language", "interprocess"]
+classifiers = [
+    "Development Status :: 2 - Pre-Alpha",
+    "Intended Audience :: Developers",
+    "Intended Audience :: Education",
+    "Intended Audience :: Science/Research",
+    "Programming Language :: Python :: 3 :: Only",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "License :: OSI Approved :: BSD License",
+    "Operating System :: Microsoft :: Windows",
+    "Operating System :: Unix",
+    "Operating System :: MacOS",
+    "Topic :: Scientific/Engineering",
+    "Topic :: Software Development :: Libraries :: Java Libraries",
+    "Topic :: Software Development :: Libraries :: Python Modules",
+    "Topic :: Utilities",
+]
+
+# NB: Keep this in sync with environment.yml AND dev-environment.yml!
+requires-python = ">=3.10"
+dependencies = [
+]
+
+[project.optional-dependencies]
+# NB: Keep this in sync with dev-environment.yml!
+dev = [
+    "autopep8",
+    "black",
+    "build",
+    "flake8",
+    "flake8-pyproject",
+    "flake8-typing-imports",
+    "isort",
+    "pytest",
+    "numpy",
+    "toml",
+    "validate-pyproject[all]",
+]
+
+[project.urls]
+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"
+
+[tool.setuptools]
+package-dir = {"" = "src"}
+include-package-data = true
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+# Thanks to Flake8-pyproject, we can configure flake8 here!
+[tool.flake8]
+exclude = ["bin", "build", "dist"]
+extend-ignore = ["E203"]
+# See https://black.readthedocs.io/en/stable/guides/using_black_with_other_tools.html#flake8
+max-line-length = 88
+min_python_version = "3.10"
+ 
+[tool.isort]
+profile = "black"
+
+[tool.pytest.ini_options]
+addopts = "-s -p no:faulthandler"

appose-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

appose-0.1.0/src/appose/__init__.py

@@ -0,0 +1,152 @@
+###
+# #%L
+# Appose: multi-language interprocess cooperation with shared memory.
+# %%
+# Copyright (C) 2023 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%
+###
+
+'''
+Appose is a library for interprocess cooperation with shared memory.
+The guiding principles are *simplicity* and *efficiency*.
+
+Appose was written to enable **easy execution of Python-based deep learning
+from Java without copying tensors**, but its utility extends beyond that.
+The steps for using Appose are:
+
+* Build an *environment* with the dependencies you need.
+* Create a *service* linked to a *worker*, which runs in its own process.
+* Execute scripts on the worker by launching *tasks*.
+* Receive status updates from the task asynchronously via callbacks.
+
+## Examples
+
+* TODO - move the below code somewhere linkable, for succinctness here.
+
+Here is a very simple example written in Python:
+
+    import appose
+    env = appose.java(vendor="zulu", version="17").build()
+    groovy = env.groovy()
+    Task task = groovy.task("""
+        5 + 6
+    """)
+    task.waitFor()
+    result = task.outputs.get("result")
+    assert 11 == result
+
+And here is an example using a few more of Appose's features:
+
+    import appose
+    from time import sleep
+
+    env = appose.java(vendor="zulu", version="17").build()
+    groovy = env.groovy()
+    task = groovy.task("""
+        // Approximate the golden ratio using the Fibonacci sequence.
+        previous = 0
+        current = 1
+        for (i = 0; i < iterations; i++) {
+            if (task.cancelRequested) {
+                task.cancel()
+                break
+            }
+            task.status(null, i, iterations)
+            v = current
+            current += previous
+            previous = v
+        }
+        task.outputs["numer"] = current
+        task.outputs["denom"] = previous
+    """)
+
+    def task_listener(event):
+        match event.responseType:
+            case UPDATE:
+                print(f"Progress {task.current}/{task.maximum}")
+            case COMPLETION:
+                numer = task.outputs["numer"]
+                denom = task.outputs["denom"]
+                ratio = numer / denom
+                print(f"Task complete. Result: {numer}/{denom} =~ {ratio}");
+            case CANCELATION:
+                print("Task canceled")
+            case FAILURE:
+                print(f"Task failed: {task.error}")
+
+    task.listen(task_listener)
+
+    task.start()
+    sleep(1)
+    if not task.status.isFinished():
+        # Task is taking too long; request a cancelation.
+        task.cancel()
+
+    task.waitFor()
+
+Of course, the above examples could have been done all in Python. But
+hopefully they hint at the possibilities of easy cross-language integration.
+
+## Workers
+
+A *worker* is a separate process created by Appose to do asynchronous
+computation on behalf of the calling process. The calling process interacts
+with a worker via its associated *service*.
+
+Appose comes with built-in support for two worker implementations:
+`python_worker` to run Python scripts, and `GroovyWorker` to run Groovy
+scripts. These workers can be created easily by invoking the environment
+object's `python()` and `groovy()` methods respectively.
+
+But Appose is compatible with any program that abides by the
+*Appose worker process contract*:
+
+1. The worker must accept requests in Appose's request format on its
+   standard input (stdin) stream.
+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.
+'''
+
+from pathlib import Path
+
+from .environment import Builder, Environment
+
+
+def base(directory: Path) -> Builder:
+    return Builder().base(directory)
+
+
+def java(vendor: str, version: str) -> Builder:
+    return Builder().java(vendor=vendor, version=version)
+
+
+def conda(environment_yaml: Path) -> Builder:
+    return Builder().conda(environment_yaml=environment_yaml)
+
+
+def system(directory: Path = Path(".")) -> Environment:
+    return Builder().base(directory).use_system_path().build()