Windmill Python Client

Warnings

• gotcha The `wmill` client is not inherently thread-safe or multi-processing safe. When developing multi-threaded or multi-process applications, you must create a separate `wmill.Windmill()` client instance for each thread or process to avoid unexpected behavior.
  Fix: Instantiate `wmill.Windmill()` client separately for each thread or process.
• breaking The `wmill.write_s3_file()` function's signature changed in version `1.421.0`. It now requires `content_type` and `content_disposition` as positional arguments, leading to `TypeError` if not provided.
  Fix: Update calls to `wmill.write_s3_file()` to include `content_type` and `content_disposition` arguments (e.g., `wmill.write_s3_file(s3_obj, content, content_type='application/octet-stream', content_disposition='attachment')`).
• gotcha For local development outside the Windmill Web IDE, you must explicitly set environment variables (`WM_TOKEN`, `BASE_URL`, `WORKSPACE`) for the `wmill` client to authenticate and connect to your Windmill instance. Without these, client methods may fail or connect to incorrect endpoints.
  Fix: Ensure `WM_TOKEN`, `BASE_URL` (e.g., `http://localhost:8000` or your instance URL), and `WORKSPACE` are set in your environment variables before running local scripts that use `wmill`.
• gotcha Windmill automatically resolves Python script dependencies by analyzing top-level `import` statements. It uses a heuristic assuming the import root name matches the PyPI package name. If your package structure deviates (e.g., `import my_lib.sub_module` where the package is `my-library`), automatic resolution might fail.
  Fix: For non-standard package name to import root mappings, consider using PEP-723 inline script metadata for explicit dependency specification or contributing to Windmill's exception list. Otherwise, ensure top-level imports directly reflect PyPI package names.

Install

• pip install wmill Install latest version

Imports

• wmill

  import wmill

• Windmill

  from wmill import Windmill

  For advanced usage and explicit client instantiation.
• S3Object

  from wmill import S3Object

  For S3 integration helpers.

Quickstart

This quickstart demonstrates how to use the `wmill` client to interact with the Windmill platform. It covers retrieving resources and variables, running other scripts, and direct client instantiation for advanced operations. Authentication is handled automatically within the Windmill environment or via `WM_TOKEN`, `BASE_URL`, and `WORKSPACE` environment variables for local development.

import os
import wmill

def main():
    # When running inside Windmill, WM_TOKEN, BASE_URL, and WORKSPACE
    # are automatically available via environment variables.
    # For local development, ensure these are set.
    # Example: WM_TOKEN=your_token BASE_URL=http://localhost:8000 WORKSPACE=your_workspace python your_script.py
    try:
        # Get a resource (e.g., database configuration)
        db_config = wmill.get_resource('u/user/db_config')
        print(f"Retrieved DB config: {db_config}")

        # Get a variable (e.g., an API key)
        api_key = wmill.get_variable('u/user/api_key')
        print(f"Retrieved API key (first 5 chars): {api_key[:5]}...")

        # Run another script synchronously and get its result
        result = wmill.run_script_by_path(
            'f/scripts/my_helper_script',
            args={'input_data': 'hello'}
        )
        print(f"Script 'my_helper_script' result: {result}")

        # Advanced usage: instantiate the client directly
        client = wmill.Windmill(
            base_url=os.environ.get('BASE_URL', 'http://localhost:8000'),
            token=os.environ.get('WM_TOKEN', ''),
            workspace=os.environ.get('WORKSPACE', 'your_workspace')
        )
        user_info = client.user
        print(f"Current Windmill user: {user_info.email}")

    except Exception as e:
        print(f"An error occurred: {e}")

if __name__ == '__main__':
    main()