[python] adds download/upload and clean disconnection

Author: lesquoyb

python/README.md

@@ -1,5 +1,5 @@
 # Gama client
- Gama-client is a python wrapper for interacting with the headless mode (called gama-server) of the modeling and simulation platform [gama](https://gama-platform.org/). The latest release is compatible with gama 1.9.1.
+ Gama-client is a python wrapper for interacting with the headless mode (called gama-server) of the modeling and simulation platform [gama](https://gama-platform.org/). The latest release is compatible with gama 1.9.2.
 This wrapper will take care of the connection with gama-server and of sending properly formatted requests to gama-server. It is made to fit the asynchronous nature of gama-server and thus makes it possible to handle multiple simulations at the same time, but the counterpart is that the users will still have to manage what to do with the received messages (command confirmation, simulation output, errors etc.) by themselves. We provide a working example that shows the architecture you can deploy if you still want to have a sequential execution.
 
 # Installation
@@ -70,6 +70,12 @@ await client.connect()
 ```
 And the client will take care of handling this first message and setting the `socket_id` by itself.
 
+To explicitly disconnect from gama-server, simply use the `close_connection` function:
+```python
+await client.close_connection()
+```
+you can later reconnect with the same `client` object the same way you did the first time, with the `connect` function.
+
 ### Running commands
 Once connected you will want to run commands, the principle is pretty simple: all commands can be run your `client` variable through functions. For example if you want to run the [load command](https://gama-platform.org/wiki/next/HeadlessServer#the-load-command) you just have to call the `load` function with the proper parameters.
 ```python

python/examples/bug tests/file_to_download.txt

@@ -0,0 +1,7 @@
+some random text
+multi-line of course
+
+look at me I'm coding:
+print("hello world")
+
+TADA !

python/examples/bug tests/test_gaml_file.gaml

@@ -0,0 +1,27 @@
+
+model snap
+
+global {
+
+    init{
+        create dummy number:10;
+    }
+	reflex f {
+		save snapshot("d") to:"test.png";
+	}
+}
+
+species dummy {
+
+}
+
+
+experiment name type: gui {
+
+	output {
+	 display "d" type:3d{
+	 	species dummy;
+	 }
+
+	}
+}

python/examples/bug tests/upload_download_and_closing.py

@@ -0,0 +1,73 @@
+# tests the new functionalities of uploading/downloading and closing the connection
+
+import asyncio
+from asyncio import Future
+from pathlib import Path
+from typing import Dict
+
+from gama_client.base_client import GamaBaseClient
+from gama_client.command_types import CommandTypes
+from gama_client.message_types import MessageTypes
+
+download_future: Future
+upload_future: Future
+load_future: Future
+
+
+async def message_handler(message: Dict):
+    print("received", message)
+    if "command" in message:
+        if message["command"]["type"] == CommandTypes.Download.value:
+            download_future.set_result(message)
+        elif message["command"]["type"] == CommandTypes.Upload.value:
+            upload_future.set_result(message)
+        elif message["command"]["type"] == CommandTypes.Load.value:
+            load_future.set_result(message)
+
+
+async def main():
+    global download_future, upload_future, load_future
+
+    client = GamaBaseClient("localhost", 6868, message_handler)
+    await client.connect()
+
+    file_to_download = str(Path(__file__).parents[0] / "file_to_download.txt")
+    file_to_upload = str(Path(__file__).parents[0] / "uploaded.txt")
+    gaml_model = str(Path(__file__).parents[0] / "test_gaml_file.gaml")
+
+    download_future = asyncio.get_running_loop().create_future()
+    upload_future = asyncio.get_running_loop().create_future()
+    load_future = asyncio.get_running_loop().create_future()
+
+    await client.download(file_to_download)
+    ftd_content = await download_future
+    if ftd_content["type"] != MessageTypes.CommandExecutedSuccessfully.value:
+        print("error while trying to download a file", ftd_content)
+        return
+    print("file downloaded successfully from gama-server, here is its content:", ftd_content["content"])
+
+    await client.upload(file_to_upload, "here is my secret:\n\n\n\n\n\n\n\n\n\nGOTCHA")
+    up_result = await upload_future
+    if up_result["type"] != MessageTypes.CommandExecutedSuccessfully.value:
+        print("error while trying to upload a file", up_result)
+        return
+    # after that, a new file should have appeared next to this code file, containing our text
+    print("upload successful, about to close connection and do other stuff now")
+
+    await client.close_connection()
+
+    # leave some time to check on gs if correctly disconnected
+    await asyncio.sleep(15)
+
+    # reconnect and execute a random command to check that everything is fine
+    await client.connect()
+    await client.load(gaml_model, "name")
+    load_result = await upload_future
+    if load_result["type"] != MessageTypes.CommandExecutedSuccessfully.value:
+        print("error while trying to load the gaml model", load_result)
+        return
+
+    print("everything worked as expected, exiting the program")
+
+if __name__ == "__main__":
+    asyncio.run(main())

python/gama_client/base_client.py

@@ -64,7 +64,7 @@ async def start_listening_loop(self, handle_connection_message: bool, timeout: f
         :param timeout: timeout for reading the next message
         :return: Never returns
         """
-        while True:
+        while self.socket.open:
             try:
                 mess = await asyncio.wait_for(self.socket.recv(), timeout=timeout)
                 try:
@@ -80,8 +80,9 @@ async def start_listening_loop(self, handle_connection_message: bool, timeout: f
                 except Exception as js_ex:
                     print("Unable to unpack gama-server messages as a json. Error:", js_ex, "Message received:", mess)
             except Exception as sock_ex:
-                print("Error while waiting for a message from gama-server. Exiting", sock_ex)
-                sys.exit(-1)
+                if self.socket.open:
+                    print("Error while waiting for a message from gama-server. Exiting", sock_ex)
+                    sys.exit(-1)
 
     async def load(self, file_path: str, experiment_name: str, console: bool = None, status: bool = None,
                    dialog: bool = None, runtime: bool = None, parameters: List[Dict] = None, until: str = "", socket_id: str = "",
@@ -152,6 +153,41 @@ async def exit(self):
         }
         await self.socket.send(json.dumps(cmd))
 
+    async def download(self, file_path: str):
+        """
+        Downloads a file from gama server file system
+        :type file_path: the path of the file to download on gama-server's file system
+        :return: if everything goes well, gama-server will send back an object containing the entirety
+        of the file as a string
+        """
+        cmd = {
+            "type": CommandTypes.Download.value,
+            "file": file_path,
+        }
+        await self.socket.send(json.dumps(cmd))
+
+    async def upload(self, file_path: str, content: str):
+        """
+        Uploads a file to gama-server's file-system
+        :param file_path: the path on gama-server file-system where the content is going to be saved
+        :param content: the content of the file to be uploaded
+        """
+        cmd = {
+            "type": CommandTypes.Upload.value,
+            "file": file_path,
+            "content": content
+        }
+        await self.socket.send(json.dumps(cmd))
+
+    async def close_connection(self, close_code=1000, reason=""):
+        """
+        Closes the connection
+        :param close_code: the close code, 1000 by default
+        :param reason: a human-readable reason for closing.
+        :return:
+        """
+        await self.socket.close(close_code, reason)
+
     async def play(self, exp_id: str, sync: bool = None, socket_id: str = "", additional_data: Dict = None):
         """
         Sends a command to run the experiment **exp_id**

python/gama_client/command_types.py

@@ -11,4 +11,6 @@ class CommandTypes(Enum):
     StepBack    = "stepBack"
     Reload      = "reload"
     Stop        = "stop"
-    Expression  = "expression"
+    Expression  = "expression"
+    Download    = "download"
+    Upload      = "upload"

python/pyproject.toml

@@ -3,7 +3,7 @@ requires = ["hatchling"]
 build-backend = "hatchling.build"
 [project]
 name = "gama_client"
-version = "1.1.3"
+version = "1.1.4"
 authors = [
   { name="Baptiste Lesquoy", email="[email protected]" },
 ]