Update API to match TypeScript/JavaScript API

Refactor Topic iterator to yield values directly instead of futures, fixing the unbound queue variable bug. Add cancelPayload support to startTopic and simplify subscribeToProperty, subscribeToEvent, and subscribeToLogMessages to use it. Add __aiter__/__anext__/next() to Topic for cleaner `async for` and `await topic.next()` usage. Add type annotations and improve docstrings throughout api.py, topic.py, and socketwrapper.py.

Author: engbergandreas

README.md

@@ -1,13 +1,58 @@
 # openspace-api-python
-Python library to interface with [OpenSpace](https://github.com/OpenSpace/OpenSpace) using sockets.
+Python library to interface with [OpenSpace](https://github.com/OpenSpace/OpenSpace) using TCP sockets.
 
-## Work in progress
-Both the API and library are still very much a work in progress and are subject to change.
+**Work in progress** - Both the API and library are still under active development and are subject to change.
 
 ## Install
-Stable release of the OpenSpace API Python package are registered at [PyPi](https://pypi.org/project/openspace-api/). The latest version can be installed using `pip`:
+Stable releases are published on [PyPI](https://pypi.org/project/openspace-api/). Install the latest version with:
 
-`pip install openspace-api` 
+```sh
+pip install openspace-api
+```
 
-## Python in the terminal
-https://github.com/OpenSpace/openspace-api-python/blob/master/example/example.py provides an example of how to connect from a Python script using sockets. To run it, run `python example.py` from the working directory in the terminal. 
+## Quick start
+
+```python
+import asyncio
+import openspace as OpenSpace
+
+api = OpenSpace.Api('localhost', 4681)
+disconnect = asyncio.Event()
+
+async def onConnect():
+  openspace = await api.library()
+  time = await openspace.time.UTC()
+  print(f"Current simulation time: {time}")
+  disconnect.set()
+
+def onDisconnect():
+  disconnect.set()
+
+api.onConnect(onConnect)
+api.onDisconnect(onDisconnect)
+
+async def main():
+  await api.connect()
+  await disconnect.wait()
+
+asyncio.run(main())
+```
+
+## Examples
+
+Install the example dependencies first:
+
+```sh
+pip install -r example/requirements.txt
+```
+
+  - [example.py](https://github.com/OpenSpace/openspace-api-python/blob/master/example/example.py) - Async script demonstrating get/set property, property subscriptions, event subscriptions, calling Lua library functions, and adding scene graph nodes. Run with:
+  ```sh
+  python example/example.py
+  ```
+  - [example/sync-example.py](https://github.com/OpenSpace/openspace-api-python/blob/master/example/sync-example.py) - Shows how to wrap async API calls to make them synchronous, useful in interactive shells (Python REPL, IPython).
+  - [example/notebook-examples.py](https://github.com/OpenSpace/openspace-api-python/blob/master/example/notebook-examples.py) - Self-contained async functions designed for Jupyter notebooks (`await functionName()`) or scripts (`asyncio.run(functionName())`). Covers pausing simulation, navigating to geo coordinates, setting time, and adding globe layers.
+
+## Requirements
+  - Python 3.10+
+  - A running instance of [OpenSpace](https://github.com/OpenSpace/OpenSpace)

example/example.py

@@ -1,169 +1,150 @@
 import asyncio
 import openspace
+from openspace import toNamedTuple
 
 ADDRESS = 'localhost'
 PORT = 4681
+
 # Create an OpenSpaceApi instance with the OpenSpace address and port
-os = openspace.Api(ADDRESS, PORT)
+api = openspace.Api(ADDRESS, PORT)
 
 # This event is used to cleanly exit the event loop.
 disconnect = asyncio.Event()
 
 #--------------------------------TEST FUNCTIONS--------------------------------
 # Define a callback function to handle the received payload
 def event_callback(result):
-    print("event_callback:", result)
-
-async def scaleEarth(value):
-    print("Scaling Earth")
+  print("event_callback result:", result)
 
-    property = "Scene.Earth.Scale.Scale"
-    data = await os.getProperty(property)
-    data = os.toNamedTuple(data)
+async def scaleEarth(value: float):
+  print("Scaling Earth")
 
-    print(f"Current scale value: {data.Value}")
-    os.setProperty(property, value)
+  property = "Scene.Earth.Scale.Scale"
+  data = await api.getProperty(property)
+  data = toNamedTuple(data)
+  print(f"Current scale value: {data.value.value}")
+  api.setProperty(property, value)
 
 async def subscribeToEarthScaleUpdates():
-    print("Subscribing to Earth scale updates")
-
-    subscription = os.subscribeToProperty("Scene.Earth.Scale.Scale")
-    # We can iterate the subscription using by looping nextValue()
-    i = 0
-    while i < 3:
-        print("Waiting for Earth scale update...")
-        result = await os.nextValue(subscription)
-        dic = os.toNamedTuple(result)
-        print(f"{dic.Description.Identifier} changed to {dic.Value}")
-        i += 1
-    subscription.cancel()
-
-    ## Or using async for loop
-    # async for future in subscription.iterator():
-    #     result = await future
-    #     dic = api.toNamedTuple(result)
-    #     print(f"{dic.Description.Identifier} changed to {dic.Value}")
-    #     if i > 3:
-    #         subscription.cancel()
-    #     i += 1
+  print("Subscribing to Earth scale updates")
+
+  topic = api.subscribeToProperty("Scene.Earth.Scale.Scale")
+  i = 0
+  async for data in topic:
+    print(f"Waiting for Earth scale update {i}/3")
+    print(f"Earth scale update data: {data}")
+    if i >= 3:
+      topic.cancel()
+    i += 1
 
 async def subscribeToEventOnce(events):
-    topic = os.subscribeToEvent(events)
+  topic = api.subscribeToEvent(events)
 
-    async for future in topic.iterator():
-        print(f"SubscribeToEventOnce: Waiting for {events} to fire...")
-        result = await future
-        print("Event fired: ", result)
-        topic.cancel()
+  print(f"SubscribeToEventOnce: Waiting for {events} to fire...")
+  async for result in topic:
+    print("SubscribeToEventOnce: Event fired: ", result)
+    topic.cancel()
 
 async def subscribeToEventWithCallback(events, callback):
-    topic = os.subscribeToEvent(events)
-    j = 0
-    async for future in topic.iterator():
-        print(f"SubscribeToEventWithCallback: Subscription callback waiting for {events} to fire...")
-        data = await future
-        callback(data)
-        if j >= 1:
-            topic.cancel()
-            print("Cancelled SubscribeToEventWithCallback")
-        j += 1
+  topic = api.subscribeToEvent(events)
+  i = 0
+  print(f"SubscribeToEventWithCallback: Subscription callback waiting for {events} to fire...")
+  async for result in topic:
+    print(f"SubscibeToEventWithCallback: Event fired: {result}")
+    callback(result)
+    i+=1
+    if i >= 2:
+      topic.cancel()
+      print("Cancelled SubscribeToEventWithCallback")
 
 async def getTime(openspace):
-    time = await openspace.time.UTC()
-    # equivalent to:
-    # time = await openspace['time']['UTC']()
-    print(f"Current simulation time: {time}")
+  time = await openspace.time.UTC()
+  print(f"Current simulation time: {time}")
 
-async def getGeoPosition(openspace):
-    pos = await openspace.globebrowsing.localPositionFromGeo("Earth", 10, 10, 10)
-    print(f"Earth geo position: {pos}")
 
 async def getGeoPositionForCamera(openspace):
-    pos = await openspace.globebrowsing.geoPositionForCamera()
-    print(f"Geo position from camera: {pos}")
+  pos = await openspace.globebrowsing.geoPositionForCamera()
+  print(f"Geo position from camera: {pos}")
 
 async def addSceneGraphNode(openspace):
-    IDENTIFIER = "TestNode"
-    NAME = "Test Node"
-
-    node = {
-        "Identifier": IDENTIFIER,
-        "Name": NAME,
-        "Parent": "Earth",
-        "Transform": {
-            "Type": "GlobeTranslation",
-            "Globe": "Earth",
-            "Latitude": 0,
-            "Longitude": 0,
-            "FixedAltitude": 10
-        },
-        "GUI": {
-            "Path": "/MyTest/Test",
-            "Name": "TestNode"
-        }
+  identifier = "TestNode"
+  name = "Test Node"
+
+  node = {
+    "Identifier": identifier,
+    "Name": name,
+    "Parent": "Earth",
+    "Transform": {
+      "Type": "GlobeTranslation",
+      "Globe": "Earth",
+      "Latitude": 0,
+      "Longitude": 0,
+      "FixedAltitude": 10
+    },
+    "GUI": {
+      "Path": "/MyTest/Test",
+      "Name": "TestNode"
     }
+  }
 
-    await openspace.addSceneGraphNode(node)
-    print("Added scene graph node")
+  await openspace.addSceneGraphNode(node)
+  print("Added scene graph node")
 
-    await openspace.setPropertyValue("NavigationHandler.OrbitalNavigator.Anchor", IDENTIFIER)
-    await openspace.setPropertyValue("NavigationHandler.OrbitalNavigator.RetargetAnchor", None)
+  await openspace.setPropertyValue("NavigationHandler.OrbitalNavigator.Anchor", identifier)
+  await openspace.setPropertyValue("NavigationHandler.OrbitalNavigator.RetargetAnchor", None)
 
 #--------------------------------MAIN FUNCTION--------------------------------
 async def main(openspace):
+  await scaleEarth(0.9)
+  await getTime(openspace)
+  await getGeoPositionForCamera(openspace)
+  await addSceneGraphNode(openspace)
 
-    await scaleEarth(0.9)
-    await getTime(openspace)
-    await getGeoPosition(openspace)
-    await getGeoPositionForCamera(openspace)
-    await addSceneGraphNode(openspace)
+  # Create a task to not block event loop
+  earthScaleTask = asyncio.create_task(subscribeToEarthScaleUpdates())
+  asyncio.create_task(subscribeToEventOnce(["RenderableEnabled"]))
 
-    # Create a task to not block event loop
-    earthScale_Task = asyncio.create_task(subscribeToEarthScaleUpdates())
+  await earthScaleTask
 
-    asyncio.create_task(subscribeToEventOnce(["RenderableEnabled"]))
+  event_Task = asyncio.create_task(
+    subscribeToEventWithCallback(
+      ["RenderableEnabled", "RenderableDisabled"],
+      event_callback
+    )
+  )
 
-    await earthScale_Task
+  await event_Task
 
-    event_Task = asyncio.create_task(subscribeToEventWithCallback(
-        ["RenderableEnabled", "RenderableDisabled"], event_callback))
-
-    await event_Task
-
-    disconnect.set()
+  disconnect.set()
 
 async def onConnect():
-    PASSWORD = ''
-    res = await os.authenticate(PASSWORD)
-    if not res[1] == 'authorized':
-        disconnect.set()
-        return
+  PASSWORD = ''
+  result = await api.authenticate(PASSWORD)
+  if not result["status"] == 'authorized':
+    disconnect.set()
+    return
 
-    print("Connected to OpenSpace")
-    openspace = await os.singleReturnLibrary()
+  print("Connected to OpenSpace")
+  openspace = await api.library()
 
-    # Create a main task to run all function logic
-    asyncio.create_task(main(openspace), name="Main")
+  # Create a main task to run all function logic
+  asyncio.create_task(main(openspace), name="Main")
 
 def onDisconnect():
-    if asyncio.get_event_loop().is_running():
-        asyncio.get_event_loop().stop()
-    print("Disconnected from OpenSpace")
-    # If connection failed this helps the program exit gracefully
-    disconnect.set()
+  print("Disconnected from OpenSpace")
+  # If connection failed this helps the program exit gracefully
+  disconnect.set()
 
-os.onConnect(onConnect)
-os.onDisconnect(onDisconnect)
+api.onConnect(onConnect)
+api.onDisconnect(onDisconnect)
 
 # Main loop serves as an entry point to allow for authentication before running any other
 # logic. This part can be skipped if no authentication is needed, reducing the overhead of
 # creating multiple tasks before main() is run.
 async def mainLoop():
-    os.connect()
-    # Wait for the disconnect event to be set
-    await disconnect.wait()
-    os.disconnect()
-
-loop = asyncio.new_event_loop()
-loop.run_until_complete(mainLoop())
-loop.run_forever()
+  await api.connect()
+  # Wait for the disconnect event to be set
+  await disconnect.wait()
+  api.disconnect()
+
+asyncio.run(mainLoop())