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)