pythonista-jscore-runtime 0.0.1__tar.gz → 0.0.2__tar.gz

{pythonista_jscore_runtime-0.0.1 → pythonista_jscore_runtime-0.0.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: pythonista-jscore-runtime
-Version: 0.0.1
+Version: 0.0.2
 Summary: Pythonista JSCore Runtime Framework - Execute JavaScript and WebAssembly with seamless interop support natively in Pythonista 3.
 Author-email: M4nw3l <63550247+M4nw3l@users.noreply.github.com>
 Requires-Python: >= 3.10
@@ -43,20 +43,18 @@ with (jscore.runtime() as runtime, runtime.context() as context):
 
 ## Installation
 
-Download [jscore_runtime.py](jscore_runtime.py) from the repository and copy to your site-packages folder.
-
-<!--
-Install with pip via StaSh 
+Install with pip using [StaSh](https://github.com/ywangd/stash).
 
 ```bash
 pip install pythonista-jscore-runtime 
 ```
--->
+
+Or download [jscore_runtime.py](jscore_runtime.py) from the repository and copy to your site-packages folder.
 
 ## Usage
 ### Javascript Runtime
 JSCore Runtime supports both the context management and explicit create/destroy usage paradigms. 
-Alongside also automatically managed (singleton) quick/convenience evaluation and more explicit/multiple virtual machine and contexts instancing for advanced control. 
+It provides singletons for convenience evaluation and while also allows more explicit management of multiple virtual machines and contexts with its class model.
 
 A runtime singleton can be obtained from the `jscore` static class.
 ```python
@@ -142,7 +140,7 @@ context.js.my_function() # returns 1234
 The `wasm_runtime` class, and its associated `wasm_context` and `wasm_module` classes allow WebAssembly modules to be loaded 
 with files and byte arrays from Python. They efficiently load WebAssembly modules via a direct buffer copy of an NSData objects bytes into a Uint8Arrays backing store in JavaScriptCore. Allowing a module and its instance to then instantiated, and its exports are bridged directly to Python. Interop with JavaScriptCore allows WebAssembly functions to be mapped and called as any other normal Python callable function. WebAssembly methods are exposed from JavaScriptCore as `function() { [Native Code] }` bodied functions. The performance should be close to excuting code natively but is still being interpreted by JavaScriptCore. It is also likely that JavaScriptCore's WebAssembly runtime may be subject to some restrictions imposed by Apple's general security policies. 
 
-To create a `wasm_context` to instantiate `wasm_module` instances from a `wasm_runtime` instance needs to be created first. This currently works the same way as the `javascript_runtime`. 
+To create a `wasm_context` a `wasm_runtime` instance needs to be created first. This currently works the same way as the `javascript_runtime`. 
 
 A singleton runtime instance, with a lifetime of the program, may be obtained from the `jscore.runtime` accessor.
 ```python
@@ -161,7 +159,7 @@ A `wasm_context` may be obtained from runtime instance:
 context = runtime.context()
 ```
 
-Although a `wasm_context` may execute JavaScript and vice versa, `wasm_runtime` and `wasm_context` are designed to integrate Python with WebAssembly as a first class runtime, without need for any JavaScript by default, to load and call WebAssembly modules from Python.
+Although a `wasm_context` may execute JavaScript and vice versa, `wasm_runtime` and `wasm_context` are designed to integrate Python with WebAssembly as a first class runtime, without need for any JavaScript by default, to load and call WebAssembly modules from Python. A `wasm_context` therefore focuses on loading `wasm_module` instances.
 
 WebAssembly modules can be loaded from files or as raw bytes with the `wasm_module` class and `wasm_context.load_module` function.
 
@@ -232,7 +230,7 @@ function _jscore_wasm_load(name, wasm_bin, namespace){
 Calling `wasm_context.load_module` will call this function to create `WebAssembly.Module` and `WebAssebly.Instance` instances in JavaScript with a WebAssembly binary passed as an `Uint8Array` typed array instance and an imports namespace. 
 
 #### Example: Loading and calling Mozilla's simple.wasm
-An end to end example of loading and using a WebAssembly from Pythonista can be demonstrated by replicating [Mozilla's Loading Wasm Modules in Javascript](https://developer.mozilla.org/en-US/docs/WebAssembly/Guides/Using_the_JavaScript_API#loading_wasm_modules_in_javascript) example.
+An end to end example of loading and using a WebAssembly module from Pythonista can be demonstrated by replicating [Mozilla's Loading Wasm Modules in Javascript](https://developer.mozilla.org/en-US/docs/WebAssembly/Guides/Using_the_JavaScript_API#loading_wasm_modules_in_javascript) example.
 
 - Firstly, download the [simple.wasm](https://raw.githubusercontent.com/mdn/webassembly-examples/master/js-api-examples/simple.wasm) module from the page. 
 - After downloading simple.wasm, the next step is to copy this into Pythonista. To do this, navigate to the simple.wasm file in your Files app, then select the file and open the sharing sheet, then tap "Run Pythonista Script" and then choose the "Import File" option. 

{pythonista_jscore_runtime-0.0.1 → pythonista_jscore_runtime-0.0.2}/README.md

@@ -26,20 +26,18 @@ with (jscore.runtime() as runtime, runtime.context() as context):
 
 ## Installation
 
-Download [jscore_runtime.py](jscore_runtime.py) from the repository and copy to your site-packages folder.
-
-<!--
-Install with pip via StaSh 
+Install with pip using [StaSh](https://github.com/ywangd/stash).
 
 ```bash
 pip install pythonista-jscore-runtime 
 ```
--->
+
+Or download [jscore_runtime.py](jscore_runtime.py) from the repository and copy to your site-packages folder.
 
 ## Usage
 ### Javascript Runtime
 JSCore Runtime supports both the context management and explicit create/destroy usage paradigms. 
-Alongside also automatically managed (singleton) quick/convenience evaluation and more explicit/multiple virtual machine and contexts instancing for advanced control. 
+It provides singletons for convenience evaluation and while also allows more explicit management of multiple virtual machines and contexts with its class model.
 
 A runtime singleton can be obtained from the `jscore` static class.
 ```python
@@ -125,7 +123,7 @@ context.js.my_function() # returns 1234
 The `wasm_runtime` class, and its associated `wasm_context` and `wasm_module` classes allow WebAssembly modules to be loaded 
 with files and byte arrays from Python. They efficiently load WebAssembly modules via a direct buffer copy of an NSData objects bytes into a Uint8Arrays backing store in JavaScriptCore. Allowing a module and its instance to then instantiated, and its exports are bridged directly to Python. Interop with JavaScriptCore allows WebAssembly functions to be mapped and called as any other normal Python callable function. WebAssembly methods are exposed from JavaScriptCore as `function() { [Native Code] }` bodied functions. The performance should be close to excuting code natively but is still being interpreted by JavaScriptCore. It is also likely that JavaScriptCore's WebAssembly runtime may be subject to some restrictions imposed by Apple's general security policies. 
 
-To create a `wasm_context` to instantiate `wasm_module` instances from a `wasm_runtime` instance needs to be created first. This currently works the same way as the `javascript_runtime`. 
+To create a `wasm_context` a `wasm_runtime` instance needs to be created first. This currently works the same way as the `javascript_runtime`. 
 
 A singleton runtime instance, with a lifetime of the program, may be obtained from the `jscore.runtime` accessor.
 ```python
@@ -144,7 +142,7 @@ A `wasm_context` may be obtained from runtime instance:
 context = runtime.context()
 ```
 
-Although a `wasm_context` may execute JavaScript and vice versa, `wasm_runtime` and `wasm_context` are designed to integrate Python with WebAssembly as a first class runtime, without need for any JavaScript by default, to load and call WebAssembly modules from Python.
+Although a `wasm_context` may execute JavaScript and vice versa, `wasm_runtime` and `wasm_context` are designed to integrate Python with WebAssembly as a first class runtime, without need for any JavaScript by default, to load and call WebAssembly modules from Python. A `wasm_context` therefore focuses on loading `wasm_module` instances.
 
 WebAssembly modules can be loaded from files or as raw bytes with the `wasm_module` class and `wasm_context.load_module` function.
 
@@ -215,7 +213,7 @@ function _jscore_wasm_load(name, wasm_bin, namespace){
 Calling `wasm_context.load_module` will call this function to create `WebAssembly.Module` and `WebAssebly.Instance` instances in JavaScript with a WebAssembly binary passed as an `Uint8Array` typed array instance and an imports namespace. 
 
 #### Example: Loading and calling Mozilla's simple.wasm
-An end to end example of loading and using a WebAssembly from Pythonista can be demonstrated by replicating [Mozilla's Loading Wasm Modules in Javascript](https://developer.mozilla.org/en-US/docs/WebAssembly/Guides/Using_the_JavaScript_API#loading_wasm_modules_in_javascript) example.
+An end to end example of loading and using a WebAssembly module from Pythonista can be demonstrated by replicating [Mozilla's Loading Wasm Modules in Javascript](https://developer.mozilla.org/en-US/docs/WebAssembly/Guides/Using_the_JavaScript_API#loading_wasm_modules_in_javascript) example.
 
 - Firstly, download the [simple.wasm](https://raw.githubusercontent.com/mdn/webassembly-examples/master/js-api-examples/simple.wasm) module from the page. 
 - After downloading simple.wasm, the next step is to copy this into Pythonista. To do this, navigate to the simple.wasm file in your Files app, then select the file and open the sharing sheet, then tap "Run Pythonista Script" and then choose the "Import File" option. 

{pythonista_jscore_runtime-0.0.1 → pythonista_jscore_runtime-0.0.2}/jscore_runtime.py

@@ -5,7 +5,7 @@ Develop apps with Python, JavaScript and WebAssembly libraries, components and c
 https://github.com/M4nw3l/pythonista-jscore-runtime
 """
 
-__version__ = '0.0.1'
+__version__ = '0.0.2'
 
 from ctypes import *
 from ctypes.util import find_library
@@ -549,7 +549,9 @@ class jscore:
 	])
 	
 	_runtime_vm = None
+	_runtime_context = None
 	_runtimes = {}
+	_runtimes_contexts = {}
 	_runtime_cleanups = []
 	@classmethod
 	def new_runtime(cls, runtime_class, *args, **kwargs):
@@ -562,14 +564,58 @@ class jscore:
 	def runtime(cls, runtime_class = None):
 		if runtime_class is None:
 			runtime_class = javascript_runtime
-		runtime = jscore._runtimes.get(runtime_class)
+		runtime = cls._runtimes.get(runtime_class)
 		if runtime is None:
 			if cls._runtime_vm is None:
 				cls._runtime_vm = cls.vm_allocate()
-			runtime = cls.new_runtime(runtime_class, cls._runtime_vm)
-			jscore._runtimes[runtime_class] = runtime
+				cls._runtime_context = cls.context_allocate(cls._runtime_vm)
+			runtime = cls.new_runtime(runtime_class, cls._runtime_vm, cls._runtime_context)
+			cls._runtimes[runtime_class] = runtime
 		return runtime
-		
+
+	@classmethod
+	def _runtimes_cleanup(cls):
+		cls.context_deallocate(cls._runtime_context)
+		cls.vm_deallocate(cls._runtime_vm) # if we destroyed the last singleton runtime reference cleanup shared context and vm  
+		for cleanup in cls._runtime_cleanups:
+			cleanup()
+		# reset everything
+		cls._runtimes = {}
+		cls._runtime_cleanups = []
+		cls._runtimes_contexts = {}
+		cls._runtime_vm = None
+		cls._runtime_context = None
+
+	@classmethod
+	def context(cls, runtime_class = None):
+		if runtime_class is None:
+			runtime_class = javascript_runtime
+		context = cls._runtimes_contexts.get(runtime_class)
+		if context is None:
+			runtime = cls.runtime(runtime_class)
+			context = runtime.context()
+			cls._runtimes_contexts[runtime_class] = context
+		return context
+
+	@classmethod
+	def javascript(cls):
+		return cls.context(javascript_runtime)
+	#aliases
+	js = javascript
+
+	@classmethod
+	def webassembly(cls):
+		return cls.context(wasm_runtime)
+	#aliases
+	wasm = webassembly
+
+	@classmethod
+	def destroy(cls):
+		for typ,context in dict(cls._runtimes_contexts).items():
+			context.destroy()
+		for typ,runtime in dict(cls._runtimes).items():
+			runtime.destroy()
+
 	@classmethod
 	def vm_allocate(cls):
 		vm = jscore.JSVirtualMachine.alloc().init()
@@ -605,11 +651,7 @@ class jscore:
 		if runtime is rt: # remove destroyed runtime if its a tracked singleton instance
 			del cls._runtimes[key]
 			if len(cls._runtimes) == 0:
-				cls.vm_deallocate(cls._runtime_vm) # if we destroyed the last singleton runtime reference cleanup vm
-				cls._runtime_vm = None
-				for cleanup in cls._runtime_cleanups:
-					cleanup()
-				cls._runtime_cleanups = []
+				cls._runtimes_cleanup()
 	
 	_context_ref_context_lookup = {}
 	@classmethod
@@ -1402,35 +1444,44 @@ class jscore_module_loader:
 
 # base runtime framework
 class jscore_context:
-	def __init__(self, runtime):
+	def __init__(self, runtime, context = None):
 		self.runtime = runtime
-		self.context = None
+		self.context = context
+		self.context_owner = self.context is None
+		self.allocated = False
 		self.depth = 0
+		self.accessor = None
 		self.callbacks = None
 
 	def allocate(self):
-		if self.context is not None:
-			raise Exception("Context already allocated. Do not call allocate/deallocate manually.")
-		self.context = jscore.context_allocate(self.runtime.vm)
+		if self.context_owner:
+			if self.context is not None:
+				raise Exception("Context already allocated. Do not call allocate/deallocate manually.")
+			self.context = jscore.context_allocate(self.runtime.vm)
 		self.loader = jscore_module_loader(self)
+		self.accessor = javascript_context_accessor(self)
 		self.callbacks = {}
+		self.allocated = True
 		
 	def deallocate(self):
 		if self.context is None:
 			raise Exception("Context already deallocated. Do not call allocate/deallocate manually.")
 		self.loader.release()
 		self.loader = None
-		jscore.context_deallocate(self.context)
-		self.context = None
+		self.accessor = None
+		if self.context_owner:
+			jscore.context_deallocate(self.context)
+			self.context = None
 		self.callbacks = None
+		self.allocated = False
 
 	def alloc(self):
-		if self.context is not None:
+		if self.allocated:
 			return
 		self.allocate()
 
 	def destroy(self):
-		if self.context is None:
+		if not self.allocated:
 			return
 		self.deallocate()
 
@@ -1512,12 +1563,20 @@ class jscore_context:
 			callback = javascript_callback(func, name)
 			self.callbacks[key] = callback
 		return callback
+		
+	@property
+	def js(self):
+		self.alloc()
+		return self.accessor
 	
 
 class jscore_runtime:
-	def __init__(self, vm = None):
+	def __init__(self, vm = None, shared_context = None):
 		self.vm = vm
 		self.vm_owner = self.vm is None
+		if self.vm_owner and shared_context is not None:
+			raise Exception("A matching vm must be specified with a shared context. Contexts must not be shared from another virtual machine.")
+		self.shared_context = shared_context # never owner when shared_context is not None
 		self.depth = 0
 		self.module_paths = {}
 		self.scripts = []
@@ -1627,12 +1686,14 @@ class jscore_runtime:
 			self.destroy()
 		return self
 
-	def new_context(self):
+	def new_context(self, context):
 		raise NotImplementedError() 
 
-	def context(self):
+	def context(self, context = None):
 		self.alloc()
-		return self.new_context()
+		if context is None:
+			context = self.shared_context
+		return self.new_context(context)
 
 # helper class to determine the minimum set of changes to build a jsvalue in terms of javascript statements
 class jsvalue_evaluator:
@@ -1884,27 +1945,19 @@ class javascript_context_accessor:
 
 # javascript
 class javascript_context(jscore_context):
-	def __init__(self, runtime):
-		super().__init__(runtime)
-		self.accessor = None
+	def __init__(self, runtime, context = None):
+		super().__init__(runtime, context)
 
 	def allocate(self):
 		super().allocate()
-		self.accessor = javascript_context_accessor(self)
 
 	def deallocate(self):
-		self.accessor = None
 		super().deallocate()
-	
-	@property
-	def js(self):
-		self.alloc()
-		return self.accessor
 
 
 class javascript_runtime(jscore_runtime):
-	def new_context(self):
-		return javascript_context(self)
+	def new_context(self, context):
+		return javascript_context(self, context)
 
 # wasm (WebAssembly)
 class wasm_namespace:
@@ -2092,8 +2145,8 @@ class wasm_module:
 
 
 class wasm_context(jscore_context):
-	def __init__(self, runtime):
-		super().__init__(runtime)
+	def __init__(self, runtime, context = None):
+		super().__init__(runtime, context)
 		self._modules = {}
 		self._imports = {}
 		self._namespace = wasm_namespace(self._imports)
@@ -2176,8 +2229,8 @@ class wasm_context(jscore_context):
 
 
 class wasm_runtime(jscore_runtime):
-	def new_context(self):
-		return wasm_context(self)
+	def new_context(self, context):
+		return wasm_context(self, context)
 
 
 if __name__ == '__main__':
@@ -2444,5 +2497,14 @@ if __name__ == '__main__':
 
 	context.destroy()
 	runtime.destroy()
-	print(jscore._runtimes)
-	print(jscore._runtime_vm)
+
+	js_context = jscore.js()
+	js_context.js.hello = "javascript"
+	
+	wasm_context = jscore.wasm()
+	print(wasm_context.js.hello)
+	wasm_context.js.hello = "wasm"
+	
+	print(js_context.js.hello)
+	
+	jscore.destroy()