Make it possible to wrap API calls

And show how it can be used to make them synchronous, for use in
interactive shells.

Closes #5.

Author: dawagner

example/sync-example.py

@@ -0,0 +1,29 @@
+import asyncio
+import openspace
+
+# This is an example of how to make synchronous calls to the API
+# This is not so useful in scripts but has its use in interactive shells, instead of prepending
+# every call with `await`.
+
+ADDRESS = 'localhost'
+PORT = 4681
+# Create an OpenSpaceApi instance with the OpenSpace address and port
+api = openspace.Api(ADDRESS, PORT)
+
+# You might want to handle this differently according to your environment or use-case.
+# For instance, this works in a regular python shell or in IPython but `python3 -m asyncio` is
+# different.
+loop = asyncio.new_event_loop()
+def sync_wrapper(f, *args, **kwargs):
+    return loop.run_until_complete(f(*args, **kwargs))
+
+# warning: all async calls must be performed on the same loop
+
+loop.run_until_complete(api.connect())
+sync_os = loop.run_until_complete(api.singleReturnLibrary(sync_wrapper))
+
+# Calls to methods of `sync_os` will block until the call is made and a result is returned:
+sync_os.printInfo("foo")
+print(sync_os.propertyValue("Scene.Earth.Scale.Scale"))
+
+api.disconnect()

src/openspace/src/api.py

@@ -3,6 +3,7 @@
 from traceback import print_exc
 from .topic import Topic
 from .socketwrapper import SocketWrapper
+from functools import partial
 from typing import Callable, NamedTuple
 from collections import namedtuple
 
@@ -337,20 +338,19 @@ async def executeLuaFunction(self, function: str, args, getReturnValue = True):
         else:
             topic.cancel()
 
-    async def library(self) -> dict:
+    async def library(self, wrapper: None|Callable = None) -> dict:
         """ Get an object representing the OpenSpace lua libarary. \n
+        :param wrapper: if set, wraps all API calls (may be used to make them synchronous)
         :return - The lua library, mapped to async python functions. """
 
-        def generateAsyncSingleRetFunction(functionName):
-            async def fun(*args):
-                try:
-                    luaTable = await self.executeLuaFunction(functionName, args)
-                    if luaTable:
-                        return luaTable['1']
-                    return None
-                except Exception as e:
-                    print("Lua exception error: \n", e)
-            return fun
+        async def async_lua_call(functionName, *args):
+            try:
+                luaTable = await self.executeLuaFunction(functionName, args)
+                if luaTable:
+                    return luaTable['1']
+                return None
+            except Exception as e:
+                print("Lua exception error: \n", e)
 
         docs = await self.getDocumentation('lua')
 
@@ -369,13 +369,18 @@ async def fun(*args):
                 _lib = '' if subPyLibrary == pyLibrary else libraryName + '.'
                 fullFunctionName = 'openspace.' + _lib + func['name']
 
-                subPyLibrary[func['name']] = generateAsyncSingleRetFunction(fullFunctionName)
+                lua_call = partial(async_lua_call, fullFunctionName)
+                if wrapper is not None:
+                    lua_call = partial(wrapper, lua_call)
+                subPyLibrary[func['name']] = lua_call
 
         return toNamedTuple(pyLibrary, libraryName)
 
-    async def singleReturnLibrary(self):
+    async def singleReturnLibrary(self, wrapper=None):
         """ Get an object representing the OpenSpace lua library. \n
+        (deprecated. Use library() instead)
+        :param wrapper: if set, wraps all API calls (may be used to make them synchronous)
         :return - The lua library, mapped to async python functions. This method only
         returns the first return value. """
 
-        return await self.library(False)
+        return await self.library(wrapper)