From aeb8ee4d7bc9b0fa2a44d294412f151ca5088eb9 Mon Sep 17 00:00:00 2001
From: Stephan Fitzpatrick <knowsuchagency@gmail.com>
Date: Fri, 24 Nov 2023 11:17:30 -0800
Subject: [PATCH] feat(python): Update return type for 'get_resource' function
 (#2695)

* Update return type for 'get_resource' function

Modified the 'get_resource' function in 'wmill/client.py' to additionally return a 'dict', providing support for dictionaries in addition to strings and None. This change caters towards use-cases where getting a dictionary resource is needed, enhancing flexibility of resource handling in Windmill client operations. Code updated in two locations for consistency.

* Update README.md for python-client

Expanded and updated the 'README.md' to include detailed explanations about the basic and advanced usage of the 'wmill' package. The previous version wasn't as comprehensive and lacked examples. Now it includes thorough usage guidance, additional explanations, and code examples. Change improves usability for new developers approaching the project.
---
 python-client/README.md             | 91 +++++++++++++++++++++++------
 python-client/wmill/wmill/client.py |  4 +-
 2 files changed, 75 insertions(+), 20 deletions(-)

diff --git a/python-client/README.md b/python-client/README.md
index ffb4ca11b8..75bac013d0 100644
--- a/python-client/README.md
+++ b/python-client/README.md
@@ -1,28 +1,83 @@
 # wmill
 
-The client for the [Windmill](https://windmill.dev) platform
+The core client for the [Windmill](https://windmill.dev) platform.
 
-## Quickstart
+
+## Usage
+
+### Basic Usage
+
+The `wmill` package has several methods at the top-level for the most frequent operations you will need.
+
+The following are some common examples:
 
 ```python
+import time
+
 import wmill
 
-# with a WM_TOKEN env variable
-client = wmill.Client()
-
-# without a WM_TOKEN env variable
-client = wmill.Client(token="<mytoken>")
 
 def main():
-
-    version = client.get_version()
-    resource = client.get_resource("u/user/resource_path")
-
-    # run synchronously, will return the result
-    res = client.run_script_sync(hash="000000000000002a", args={})
-    print(res)
-
-    for _ in range(3):
-        # run asynchrnously, will return immediately. Can be scheduled
-        client.run_script_async(hash="000000000000002a", args={}, scheduled_in_secs=10)
+    # Get the value of a variable
+    wmill.get_variable("u/user/variable_path")
+    
+    # Run a script synchronously and get the result
+    wmill.run_script("f/pathto/script", args={"arg1": "value1"})
+    
+    # Get the value of a resource
+    wmill.get_resource("u/user/resource_path")
+    
+    # Set the script's state
+    wmill.set_state({"ts": time.time()})
+    
+    # Get the script's state
+    wmill.get_state()
+```
+
+### Advanced Usage
+
+The `wmill` package also exposes the `Windmill` class, which is the core client for the Windmill platform.
+
+```python
+import time
+
+from wmill import Windmill
+
+def main():
+    client = Windmill(
+        # token=...  <- this is optional. otherwise the client will look for the WM_TOKEN env var
+    )
+
+    # Get the current version of the client
+    client.version
+
+    # Get the current user
+    client.user
+    
+    # Convenience get and post methods exist for https://app.windmill.dev/openapi.html#/
+    # these are thin wrappers around the httpx library's get and post methods
+    # list worker groups
+    client.get("/configs/list_worker_groups")
+    # create a group
+    client.post(
+        f"/w/{client.workspace}/groups/create",
+        json={
+            "name": "my-group",
+            "summary": "my group summary",
+        }
+    )
+    
+    # Get and set the state of the script
+    now = time.time()
+    client.state = {"ts": now}
+    assert client.state == {"ts": now}
+    
+    # Run a job asynchronously
+    job_id = client.run_script_async(path="path/to/script")
+    # Get its status
+    client.get_job_status(job_id)
+    # Get its result
+    client.get_result(job_id)
+
+
 ```
diff --git a/python-client/wmill/wmill/client.py b/python-client/wmill/wmill/client.py
index fea2a7fa7a..bdbeb902cf 100644
--- a/python-client/wmill/wmill/client.py
+++ b/python-client/wmill/wmill/client.py
@@ -253,7 +253,7 @@ class Windmill:
         self,
         path: str,
         none_if_undefined: bool = False,
-    ) -> str | None:
+    ) -> str | dict | None:
         """Get resource from Windmill"""
         try:
             return self.get(
@@ -567,7 +567,7 @@ def get_state() -> Any:
 def get_resource(
     path: str,
     none_if_undefined: bool = False,
-) -> str | None:
+) -> str | dict | None:
     """Get resource from Windmill"""
     return _client.get_resource(path, none_if_undefined)