python client via pydocs

docs/advanced/2_clients/python_client.md

@@ -1,92 +1,95 @@
 # Python client
 
-The Python client library for Windmill provides a convenient way to interact with the Windmill platform's API from within your script jobs. By authenticating with the `WM_TOKEN` reserved variable, you can utilize the Python client to access various functionalities offered by Windmill.
+The Python client library for Windmill provides a convenient way to interact with the Windmill platform using Python. This client provides a set of functions and utilities to access Windmill resources and perform various operations.
+
+The Python Windmill SDK can be found at https://app.windmill.dev/pydocs/wmill.html
 
 ## Installation
 
-To use the Python client library, you need to install the `wmill` package. You can install it via pip:
+To use the Python client library, you need to install the `wmill` package via pip:
 
-```
+```bash
 pip install wmill
 ```
 
 ## Usage
 
-To use the Python client library in your script, include the following prelude:
+The Python client provides several functions that you can use to interact with the Windmill platform. Here's an example of how to use the client to get a resource from Windmill:
 
 ```python
 import wmill
 
-def main(...):
-    # Your script code
-```
+def main():
+    # Get a resource
+    db_config = wmill.get_resource('u/user/db_config')
 
-## Client class
+    # Get a variable
+    api_key = wmill.get_variable('u/user/api_key')
 
-The `Client` class is the main entry point for interacting with the Windmill API. It provides methods for accessing resources, running scripts, retrieving job statuses and results, and more. Here is the class signature:
+    # Run a script asynchronously
+    job_id = wmill.run_script_by_path_async('f/scripts/process_data', args={'input': 'value'})
 
-```python
-class Client(base_url: str = 'http://localhost:8000/api', token: str = '')
+    # Run a script synchronously and get result
+    result = wmill.run_script_by_path('f/scripts/calculate', args={'x': 10, 'y': 20})
 ```
 
-### Methods
+## API Reference
 
-#### get_resource
+For detailed API documentation including all available methods, parameters, and return types, see the [Python SDK documentation](https://app.windmill.dev/pydocs/wmill.html).
 
-```python
-def get_resource(self, path: str) -> Dict[str, Any]
-```
+### Core Functions
 
-The `get_resource` method retrieves a resource at the specified path from the Windmill platform. It returns the resource as a Python dictionary (`Dict[str, Any]`).
+The client provides both module-level convenience functions and a `Windmill` class for advanced usage:
 
-#### run_script_async
+#### Module-level Functions
 
-```python
-def run_script_async(self, hash: str, args: Dict[str, Any] = {}, scheduled_in_secs: Optional[None] = None) -> str
-```
+- `get_resource(path)` - Get a resource from Windmill
+- `get_variable(path)` - Get a variable value
+- `set_variable(path, value)` - Set a variable value
+- `run_script_by_path(path, args)` - Run a script synchronously by path
+- `run_script_by_hash(hash_, args)` - Run a script synchronously by hash
+- `run_script_by_path_async(path, args)` - Run a script asynchronously by path
+- `run_flow_async(path, args)` - Run a flow asynchronously
+- `get_result(job_id)` - Get the result of a completed job
+- `get_state()` - Get the script's state
+- `set_state(value)` - Set the script's state
 
-The `run_script_async` method launches the execution of a script asynchronously on the Windmill platform. It returns the job ID associated with the script execution.
+#### Windmill Class
 
-#### run_script_sync
+For advanced usage, you can instantiate the `Windmill` class directly:
 
 ```python
-def run_script_sync(self, hash: str, args: Dict[str, Any] = {}, verbose: bool = False) -> Dict[str, Any]
-```
-
-The `run_script_sync` method runs a script synchronously on the Windmill platform. It waits for the script to complete and returns the result as a Python dictionary (`Dict[str, Any]`).
+from wmill import Windmill
 
-#### get_job_status
+client = Windmill(
+    base_url='http://localhost:8000',
+    token='your_token',
+    workspace='your_workspace'
+)
 
-```python
-def get_job_status(self, job_id: str) -> JobStatus
+# Use client methods
+result = client.get_resource('u/user/resource')
 ```
 
-The `get_job_status` method retrieves the status of a queued or completed job identified by its job ID. It returns an instance of the `JobStatus` enumeration.
+## S3 Integration
 
-#### get_result
+The client includes helpers for working with S3-compatible storage:
 
 ```python
-def get_result(self, job_id: str) -> Dict[str, Any]
-```
-
-The `get_result` method retrieves the result of a completed job identified by its job ID. It returns the result as a Python dictionary (`Dict[str, Any]`).
+import wmill
+from wmill import S3Object
 
-#### get_version
+# Load a file from S3
+s3_obj = S3Object(s3='/path/to/file.txt')
+content = wmill.load_s3_file(s3_obj)
 
-```python
-def get_version(self) -> str
+# Write a file to S3
+file_content = b'Hello Windmill!'
+wmill.write_s3_file(s3_obj, file_content)
 ```
 
-The `get_version` method returns the current version of the Windmill backend.
-
-## JobStatus enumeration
-
-The `JobStatus` class is an enumeration that represents the different states of a job in Windmill. It provides the following class variables:
-
-- `COMPLETED`: Represents a completed job.
-- `RUNNING`: Represents a job that is currently running.
-- `WAITING`: Represents a job that is queued and waiting to be executed.
-
-The `JobStatus` enumeration is useful when retrieving the status of a job using the `get_job_status` method.
+## Notes
 
-> **Note**: The Python client is not thread or multi-processing safe. When using multithreading or multiprocessing, create a separate client instance per thread/process using `wmill.Windmill()`.
+- The Python client automatically uses the `WM_TOKEN` environment variable for authentication when running inside Windmill
+- The client is not thread or multi-processing safe. When using multithreading or multiprocessing, create a separate client instance per thread/process using `wmill.Windmill()`
+- For complete API reference with all methods and parameters, see the [Python SDK documentation](https://app.windmill.dev/pydocs/wmill.html)