wmill 1.583.0__tar.gz → 1.609.0__tar.gz

{wmill-1.583.0 → wmill-1.609.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: wmill
-Version: 1.583.0
+Version: 1.609.0
 Summary: A client library for accessing Windmill server wrapping the Windmill client API
 Home-page: https://windmill.dev
 License: Apache-2.0

{wmill-1.583.0 → wmill-1.609.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [tool.poetry]
 name = "wmill"
-version = "1.583.0"
+version = "1.609.0"
 description = "A client library for accessing Windmill server wrapping the Windmill client API"
 license = "Apache-2.0"
 homepage = "https://windmill.dev"

{wmill-1.583.0 → wmill-1.609.0}/wmill/client.py

@@ -32,7 +32,17 @@ JobStatus = Literal["RUNNING", "WAITING", "COMPLETED"]
 
 
 class Windmill:
+    """Windmill client for interacting with the Windmill API."""
+
     def __init__(self, base_url=None, token=None, workspace=None, verify=True):
+        """Initialize the Windmill client.
+
+        Args:
+            base_url: API base URL (defaults to BASE_INTERNAL_URL or WM_BASE_URL env)
+            token: Authentication token (defaults to WM_TOKEN env)
+            workspace: Workspace ID (defaults to WM_WORKSPACE env)
+            verify: Whether to verify SSL certificates
+        """
         base = (
             base_url
             or os.environ.get("BASE_INTERNAL_URL")
@@ -75,6 +85,11 @@ class Windmill:
         return mocked_api
 
     def get_client(self) -> httpx.Client:
+        """Get the HTTP client instance.
+
+        Returns:
+            Configured httpx.Client for API requests
+        """
         return httpx.Client(
             base_url=self.base_url,
             headers=self.headers,
@@ -82,6 +97,16 @@ class Windmill:
         )
 
     def get(self, endpoint, raise_for_status=True, **kwargs) -> httpx.Response:
+        """Make an HTTP GET request to the Windmill API.
+
+        Args:
+            endpoint: API endpoint path
+            raise_for_status: Whether to raise an exception on HTTP errors
+            **kwargs: Additional arguments passed to httpx.get
+
+        Returns:
+            HTTP response object
+        """
         endpoint = endpoint.lstrip("/")
         resp = self.client.get(f"/{endpoint}", **kwargs)
         if raise_for_status:
@@ -94,6 +119,16 @@ class Windmill:
         return resp
 
     def post(self, endpoint, raise_for_status=True, **kwargs) -> httpx.Response:
+        """Make an HTTP POST request to the Windmill API.
+
+        Args:
+            endpoint: API endpoint path
+            raise_for_status: Whether to raise an exception on HTTP errors
+            **kwargs: Additional arguments passed to httpx.post
+
+        Returns:
+            HTTP response object
+        """
         endpoint = endpoint.lstrip("/")
         resp = self.client.post(f"/{endpoint}", **kwargs)
         if raise_for_status:
@@ -106,6 +141,14 @@ class Windmill:
         return resp
 
     def create_token(self, duration=dt.timedelta(days=1)) -> str:
+        """Create a new authentication token.
+
+        Args:
+            duration: Token validity duration (default: 1 day)
+
+        Returns:
+            New authentication token string
+        """
         endpoint = "/users/tokens/create"
         payload = {
             "label": f"refresh {time.time()}",
@@ -276,6 +319,21 @@ class Windmill:
             cleanup=cleanup, assert_result_is_not_none=assert_result_is_not_none
         )
 
+    def run_inline_script_preview(
+        self,
+        content: str,
+        language: str,
+        args: dict = None,
+    ) -> Any:
+        """Run a script on the current worker without creating a job"""
+        endpoint = f"/w/{self.workspace}/jobs/run_inline/preview"
+        body = {
+            "content": content,
+            "language": language,
+            "args": args or {},
+        }
+        return self.post(endpoint, json=body).json()
+
     def wait_job(
         self,
         job_id,
@@ -284,6 +342,22 @@ class Windmill:
         cleanup: bool = True,
         assert_result_is_not_none: bool = False,
     ):
+        """Wait for a job to complete and return its result.
+
+        Args:
+            job_id: ID of the job to wait for
+            timeout: Maximum time to wait (seconds or timedelta)
+            verbose: Enable verbose logging
+            cleanup: Register cleanup handler to cancel job on exit
+            assert_result_is_not_none: Raise exception if result is None
+
+        Returns:
+            Job result when completed
+
+        Raises:
+            TimeoutError: If timeout is reached
+            Exception: If job fails
+        """
         def cancel_job():
             logger.warning(f"cancelling job: {job_id}")
             self.post(
@@ -392,16 +466,52 @@ class Windmill:
         return result
 
     def get_job(self, job_id: str) -> dict:
+        """Get job details by ID.
+
+        Args:
+            job_id: UUID of the job
+
+        Returns:
+            Job details dictionary
+        """
         return self.get(f"/w/{self.workspace}/jobs_u/get/{job_id}").json()
 
     def get_root_job_id(self, job_id: str | None = None) -> dict:
+        """Get the root job ID for a flow hierarchy.
+
+        Args:
+            job_id: Job ID (defaults to current WM_JOB_ID)
+
+        Returns:
+            Root job ID
+        """
         job_id = job_id or os.environ.get("WM_JOB_ID")
         return self.get(f"/w/{self.workspace}/jobs_u/get_root_job_id/{job_id}").json()
 
-    def get_id_token(self, audience: str) -> str:
-        return self.post(f"/w/{self.workspace}/oidc/token/{audience}").text
+    def get_id_token(self, audience: str, expires_in: int | None = None) -> str:
+        """Get an OIDC JWT token for authentication to external services.
+
+        Args:
+            audience: Token audience (e.g., "vault", "aws")
+            expires_in: Optional expiration time in seconds
+
+        Returns:
+            JWT token string
+        """
+        params = {}
+        if expires_in is not None:
+            params["expires_in"] = expires_in
+        return self.post(f"/w/{self.workspace}/oidc/token/{audience}", params=params).text
 
     def get_job_status(self, job_id: str) -> JobStatus:
+        """Get the status of a job.
+
+        Args:
+            job_id: UUID of the job
+
+        Returns:
+            Job status: "RUNNING", "WAITING", or "COMPLETED"
+        """
         job = self.get_job(job_id)
         job_type = job.get("type", "")
         assert job_type, f"{job} is not a valid job"
@@ -416,6 +526,15 @@ class Windmill:
         job_id: str,
         assert_result_is_not_none: bool = True,
     ) -> Any:
+        """Get the result of a completed job.
+
+        Args:
+            job_id: UUID of the completed job
+            assert_result_is_not_none: Raise exception if result is None
+
+        Returns:
+            Job result
+        """
         result = self.get(f"/w/{self.workspace}/jobs_u/completed/get_result/{job_id}")
         result_text = result.text
         if assert_result_is_not_none and result_text is None:
@@ -426,6 +545,14 @@ class Windmill:
             return result_text
 
     def get_variable(self, path: str) -> str:
+        """Get a variable value by path.
+
+        Args:
+            path: Variable path in Windmill
+
+        Returns:
+            Variable value as string
+        """
         path = parse_variable_syntax(path) or path
         if self.mocked_api is not None:
             variables = self.mocked_api["variables"]
@@ -436,17 +563,20 @@ class Windmill:
                 logger.info(
                     f"MockedAPI present, but variable not found at {path}, falling back to real API"
                 )
-
-        """Get variable from Windmill"""
         return self.get(f"/w/{self.workspace}/variables/get_value/{path}").json()
 
     def set_variable(self, path: str, value: str, is_secret: bool = False) -> None:
+        """Set a variable value by path, creating it if it doesn't exist.
+
+        Args:
+            path: Variable path in Windmill
+            value: Variable value to set
+            is_secret: Whether the variable should be secret (default: False)
+        """
         path = parse_variable_syntax(path) or path
         if self.mocked_api is not None:
             self.mocked_api["variables"][path] = value
             return
-
-        """Set variable from Windmill"""
         # check if variable exists
         r = self.get(
             f"/w/{self.workspace}/variables/get/{path}", raise_for_status=False
@@ -474,6 +604,15 @@ class Windmill:
         path: str,
         none_if_undefined: bool = False,
     ) -> dict | None:
+        """Get a resource value by path.
+
+        Args:
+            path: Resource path in Windmill
+            none_if_undefined: Return None instead of raising if not found
+
+        Returns:
+            Resource value dictionary or None
+        """
         path = parse_resource_syntax(path) or path
         if self.mocked_api is not None:
             resources = self.mocked_api["resources"]
@@ -490,8 +629,6 @@ class Windmill:
                 logger.info(
                     f"MockedAPI present, but resource not found at ${path}, falling back to real API"
                 )
-
-        """Get resource from Windmill"""
         try:
             return self.get(
                 f"/w/{self.workspace}/resources/get_value_interpolated/{path}"
@@ -508,6 +645,13 @@ class Windmill:
         path: str,
         resource_type: str,
     ):
+        """Set a resource value by path, creating it if it doesn't exist.
+
+        Args:
+            value: Resource value to set
+            path: Resource path in Windmill
+            resource_type: Resource type for creation
+        """
         path = parse_resource_syntax(path) or path
         if self.mocked_api is not None:
             self.mocked_api["resources"][path] = value
@@ -563,10 +707,33 @@ class Windmill:
             params=params if params else None,
         ).json()
     
-    def set_state(self, value: Any):
-        self.set_resource(value, path=self.state_path, resource_type="state")
+    def set_state(self, value: Any, path: str | None = None) -> None:
+        """Set the workflow state.
+
+        Args:
+            value: State value to set
+            path: Optional state resource path override.
+        """
+        self.set_resource(value, path=path or self.state_path, resource_type="state")
+
+    def get_state(self, path: str | None = None) -> Any:
+        """Get the workflow state.
+
+        Args:
+            path: Optional state resource path override.
+
+        Returns:
+            State value or None if not set
+        """
+        return self.get_resource(path=path or self.state_path, none_if_undefined=True)
 
     def set_progress(self, value: int, job_id: Optional[str] = None):
+        """Set job progress percentage (0-99).
+
+        Args:
+            value: Progress percentage
+            job_id: Job ID (defaults to current WM_JOB_ID)
+        """
         workspace = get_workspace()
         flow_id = os.environ.get("WM_FLOW_JOB_ID")
         job_id = job_id or os.environ.get("WM_JOB_ID")
@@ -584,6 +751,14 @@ class Windmill:
         )
 
     def get_progress(self, job_id: Optional[str] = None) -> Any:
+        """Get job progress percentage.
+
+        Args:
+            job_id: Job ID (defaults to current WM_JOB_ID)
+
+        Returns:
+            Progress value (0-100) or None if not set
+        """
         workspace = get_workspace()
         job_id = job_id or os.environ.get("WM_JOB_ID")
 
@@ -622,6 +797,11 @@ class Windmill:
 
     @property
     def version(self):
+        """Get the Windmill server version.
+
+        Returns:
+            Version string
+        """
         return self.get("version").text
 
     def get_duckdb_connection_settings(
@@ -795,19 +975,110 @@ class Windmill:
             ).json()
         except Exception as e:
             raise Exception("Could not write file to S3") from e
-        return S3Object(s3=response["file_key"])
+        return S3Object(s3=response["file_key"], storage=s3object["storage"])
 
     def sign_s3_objects(self, s3_objects: list[S3Object | str]) -> list[S3Object]:
+        """Sign S3 objects for use by anonymous users in public apps.
+
+        Args:
+            s3_objects: List of S3 objects to sign
+
+        Returns:
+            List of signed S3 objects
+        """
         return self.post(
             f"/w/{self.workspace}/apps/sign_s3_objects", json={"s3_objects": list(map(parse_s3_object, s3_objects))}
         ).json()
 
     def sign_s3_object(self, s3_object: S3Object | str) -> S3Object:
+        """Sign a single S3 object for use by anonymous users in public apps.
+
+        Args:
+            s3_object: S3 object to sign
+
+        Returns:
+            Signed S3 object
+        """
         return self.post(
             f"/w/{self.workspace}/apps/sign_s3_objects",
             json={"s3_objects": [s3_object]},
         ).json()[0]
 
+    def get_presigned_s3_public_urls(
+        self,
+        s3_objects: list[S3Object | str],
+        base_url: str | None = None,
+    ) -> list[str]:
+        """
+        Generate presigned public URLs for an array of S3 objects.
+        If an S3 object is not signed yet, it will be signed first.
+
+        Args:
+            s3_objects: List of S3 objects to sign
+            base_url: Optional base URL for the presigned URLs (defaults to WM_BASE_URL)
+
+        Returns:
+            List of signed public URLs
+
+        Example:
+            >>> s3_objs = [S3Object(s3="/path/to/file1.txt"), S3Object(s3="/path/to/file2.txt")]
+            >>> urls = client.get_presigned_s3_public_urls(s3_objs)
+        """
+        base_url = base_url or self._get_public_base_url()
+
+        s3_objs = [parse_s3_object(s3_obj) for s3_obj in s3_objects]
+
+        # Sign all S3 objects that need to be signed in one go
+        s3_objs_to_sign: list[tuple[S3Object, int]] = [
+            (s3_obj, index)
+            for index, s3_obj in enumerate(s3_objs)
+            if s3_obj.get("presigned") is None
+        ]
+
+        if s3_objs_to_sign:
+            signed_s3_objs = self.sign_s3_objects(
+                [s3_obj for s3_obj, _ in s3_objs_to_sign]
+            )
+            for i, (_, original_index) in enumerate(s3_objs_to_sign):
+                s3_objs[original_index] = parse_s3_object(signed_s3_objs[i])
+
+        signed_urls: list[str] = []
+        for s3_obj in s3_objs:
+            s3 = s3_obj.get("s3", "")
+            presigned = s3_obj.get("presigned", "")
+            storage = s3_obj.get("storage", "_default_")
+            signed_url = f"{base_url}/api/w/{self.workspace}/s3_proxy/{storage}/{s3}?{presigned}"
+            signed_urls.append(signed_url)
+
+        return signed_urls
+
+    def get_presigned_s3_public_url(
+        self,
+        s3_object: S3Object | str,
+        base_url: str | None = None,
+    ) -> str:
+        """
+        Generate a presigned public URL for an S3 object.
+        If the S3 object is not signed yet, it will be signed first.
+
+        Args:
+            s3_object: S3 object to sign
+            base_url: Optional base URL for the presigned URL (defaults to WM_BASE_URL)
+
+        Returns:
+            Signed public URL
+
+        Example:
+            >>> s3_obj = S3Object(s3="/path/to/file.txt")
+            >>> url = client.get_presigned_s3_public_url(s3_obj)
+        """
+        urls = self.get_presigned_s3_public_urls([s3_object], base_url)
+        return urls[0]
+
+    def _get_public_base_url(self) -> str:
+        """Get the public base URL from environment or default to localhost"""
+        return os.environ.get("WM_BASE_URL", "http://localhost:3000")
+
     def __boto3_connection_settings(self, s3_resource) -> Boto3ConnectionSettings:
         endpoint_url_prefix = "https://" if s3_resource["useSSL"] else "http://"
         return Boto3ConnectionSettings(
@@ -824,14 +1095,29 @@ class Windmill:
         )
 
     def whoami(self) -> dict:
+        """Get the current user information.
+
+        Returns:
+            User details dictionary
+        """
         return self.get("/users/whoami").json()
 
     @property
     def user(self) -> dict:
+        """Get the current user information (alias for whoami).
+
+        Returns:
+            User details dictionary
+        """
         return self.whoami()
 
     @property
     def state_path(self) -> str:
+        """Get the state resource path from environment.
+
+        Returns:
+            State path string
+        """
         state_path = os.environ.get(
             "WM_STATE_PATH_NEW", os.environ.get("WM_STATE_PATH")
         )
@@ -841,10 +1127,16 @@ class Windmill:
 
     @property
     def state(self) -> Any:
+        """Get the workflow state.
+
+        Returns:
+            State value or None if not set
+        """
         return self.get_resource(path=self.state_path, none_if_undefined=True)
 
     @state.setter
     def state(self, value: Any) -> None:
+        """Set the workflow state."""
         self.set_state(value)
 
     @staticmethod
@@ -887,12 +1179,26 @@ class Windmill:
         with open(f"/shared/{path}", "r", encoding="utf-8") as f:
             return json.load(f)
 
-    def get_resume_urls(self, approver: str = None) -> dict:
+    def get_resume_urls(self, approver: str = None, flow_level: bool = None) -> dict:
+        """Get URLs needed for resuming a flow after suspension.
+
+        Args:
+            approver: Optional approver name
+            flow_level: If True, generate resume URLs for the parent flow instead of the
+                specific step. This allows pre-approvals that can be consumed by any later
+                suspend step in the same flow.
+
+        Returns:
+            Dictionary with approvalPage, resume, and cancel URLs
+        """
         nonce = random.randint(0, 1000000000)
         job_id = os.environ.get("WM_JOB_ID") or "NO_ID"
+        params = {"approver": approver}
+        if flow_level is not None:
+            params["flow_level"] = flow_level
         return self.get(
             f"/w/{self.workspace}/jobs/resume_urls/{job_id}/{nonce}",
-            params={"approver": approver},
+            params=params,
         ).json()
 
     def request_interactive_slack_approval(
@@ -1000,6 +1306,29 @@ class Windmill:
             },
         )
 
+    def datatable(self, name: str = "main"):
+        """Get a DataTable client for SQL queries.
+
+        Args:
+            name: Database name (default: "main")
+
+        Returns:
+            DataTableClient instance
+        """
+        return DataTableClient(self, name)
+
+    def ducklake(self, name: str = "main"):
+        """Get a DuckLake client for DuckDB queries.
+
+        Args:
+            name: Database name (default: "main")
+
+        Returns:
+            DucklakeClient instance
+        """
+        return DucklakeClient(self, name)
+
+
 
 def init_global_client(f):
     @functools.wraps(f)
@@ -1032,11 +1361,24 @@ def deprecate(in_favor_of: str):
 
 @init_global_client
 def get_workspace() -> str:
+    """Get the current workspace ID.
+
+    Returns:
+        Workspace ID string
+    """
     return _client.workspace
 
 
 @init_global_client
 def get_root_job_id(job_id: str | None = None) -> str:
+    """Get the root job ID for a flow hierarchy.
+
+    Args:
+        job_id: Job ID (defaults to current WM_JOB_ID)
+
+    Returns:
+        Root job ID
+    """
     return _client.get_root_job_id(job_id)
 
 
@@ -1052,6 +1394,16 @@ def run_script_async(
     args: Dict[str, Any] = None,
     scheduled_in_secs: int = None,
 ) -> str:
+    """Create a script job and return its job ID.
+
+    Args:
+        hash_or_path: Script hash or path (determined by presence of '/')
+        args: Script arguments
+        scheduled_in_secs: Delay before execution in seconds
+
+    Returns:
+        Job ID string
+    """
     is_path = "/" in hash_or_path
     hash_ = None if is_path else hash_or_path
     path = hash_or_path if is_path else None
@@ -1073,6 +1425,17 @@ def run_flow_async(
     # lead to incorrectness and failures
     do_not_track_in_parent: bool = True,
 ) -> str:
+    """Create a flow job and return its job ID.
+
+    Args:
+        path: Flow path
+        args: Flow arguments
+        scheduled_in_secs: Delay before execution in seconds
+        do_not_track_in_parent: Whether to track in parent job (default: True)
+
+    Returns:
+        Job ID string
+    """
     return _client.run_flow_async(
         path=path,
         args=args,
@@ -1090,6 +1453,19 @@ def run_script_sync(
     cleanup: bool = True,
     timeout: dt.timedelta = None,
 ) -> Any:
+    """Run a script synchronously by hash and return its result.
+
+    Args:
+        hash: Script hash
+        args: Script arguments
+        verbose: Enable verbose logging
+        assert_result_is_not_none: Raise exception if result is None
+        cleanup: Register cleanup handler to cancel job on exit
+        timeout: Maximum time to wait
+
+    Returns:
+        Script result
+    """
     return _client.run_script(
         hash_=hash,
         args=args,
@@ -1106,6 +1482,16 @@ def run_script_by_path_async(
     args: Dict[str, Any] = None,
     scheduled_in_secs: Union[None, int] = None,
 ) -> str:
+    """Create a script job by path and return its job ID.
+
+    Args:
+        path: Script path
+        args: Script arguments
+        scheduled_in_secs: Delay before execution in seconds
+
+    Returns:
+        Job ID string
+    """
     return _client.run_script_by_path_async(
         path=path,
         args=args,
@@ -1119,6 +1505,16 @@ def run_script_by_hash_async(
     args: Dict[str, Any] = None,
     scheduled_in_secs: Union[None, int] = None,
 ) -> str:
+    """Create a script job by hash and return its job ID.
+
+    Args:
+        hash_: Script hash
+        args: Script arguments
+        scheduled_in_secs: Delay before execution in seconds
+
+    Returns:
+        Job ID string
+    """
     return _client.run_script_by_hash_async(
         hash_=hash_,
         args=args,
@@ -1135,6 +1531,19 @@ def run_script_by_path_sync(
     cleanup: bool = True,
     timeout: dt.timedelta = None,
 ) -> Any:
+    """Run a script synchronously by path and return its result.
+
+    Args:
+        path: Script path
+        args: Script arguments
+        verbose: Enable verbose logging
+        assert_result_is_not_none: Raise exception if result is None
+        cleanup: Register cleanup handler to cancel job on exit
+        timeout: Maximum time to wait
+
+    Returns:
+        Script result
+    """
     return _client.run_script(
         path=path,
         args=args,
@@ -1155,11 +1564,28 @@ def get_id_token(audience: str) -> str:
 
 @init_global_client
 def get_job_status(job_id: str) -> JobStatus:
+    """Get the status of a job.
+
+    Args:
+        job_id: UUID of the job
+
+    Returns:
+        Job status: "RUNNING", "WAITING", or "COMPLETED"
+    """
     return _client.get_job_status(job_id)
 
 
 @init_global_client
 def get_result(job_id: str, assert_result_is_not_none=True) -> Dict[str, Any]:
+    """Get the result of a completed job.
+
+    Args:
+        job_id: UUID of the completed job
+        assert_result_is_not_none: Raise exception if result is None
+
+    Returns:
+        Job result
+    """
     return _client.get_result(
         job_id=job_id, assert_result_is_not_none=assert_result_is_not_none
     )
@@ -1258,6 +1684,56 @@ def sign_s3_object(s3_object: S3Object| str) -> S3Object:
     return _client.sign_s3_object(s3_object)
 
 
+@init_global_client
+def get_presigned_s3_public_urls(
+    s3_objects: list[S3Object | str],
+    base_url: str | None = None,
+) -> list[str]:
+    """
+    Generate presigned public URLs for an array of S3 objects.
+    If an S3 object is not signed yet, it will be signed first.
+
+    Args:
+        s3_objects: List of S3 objects to sign
+        base_url: Optional base URL for the presigned URLs (defaults to WM_BASE_URL)
+
+    Returns:
+        List of signed public URLs
+
+    Example:
+        >>> import wmill
+        >>> from wmill import S3Object
+        >>> s3_objs = [S3Object(s3="/path/to/file1.txt"), S3Object(s3="/path/to/file2.txt")]
+        >>> urls = wmill.get_presigned_s3_public_urls(s3_objs)
+    """
+    return _client.get_presigned_s3_public_urls(s3_objects, base_url)
+
+
+@init_global_client
+def get_presigned_s3_public_url(
+    s3_object: S3Object | str,
+    base_url: str | None = None,
+) -> str:
+    """
+    Generate a presigned public URL for an S3 object.
+    If the S3 object is not signed yet, it will be signed first.
+
+    Args:
+        s3_object: S3 object to sign
+        base_url: Optional base URL for the presigned URL (defaults to WM_BASE_URL)
+
+    Returns:
+        Signed public URL
+
+    Example:
+        >>> import wmill
+        >>> from wmill import S3Object
+        >>> s3_obj = S3Object(s3="/path/to/file.txt")
+        >>> url = wmill.get_presigned_s3_public_url(s3_obj)
+    """
+    return _client.get_presigned_s3_public_url(s3_object, base_url)
+
+
 @init_global_client
 def whoami() -> dict:
     """
@@ -1267,12 +1743,11 @@ def whoami() -> dict:
 
 
 @init_global_client
-@deprecate("Windmill().state")
-def get_state() -> Any:
+def get_state(path: str | None = None) -> Any:
     """
     Get the state
     """
-    return _client.state
+    return _client.get_state(path=path)
 
 
 @init_global_client
@@ -1323,11 +1798,11 @@ def list_resources(
 
 
 @init_global_client
-def set_state(value: Any) -> None:
+def set_state(value: Any, path: str | None = None) -> None:
     """
     Set the state
     """
-    return _client.set_state(value)
+    return _client.set_state(value, path=path)
 
 
 @init_global_client
@@ -1409,12 +1884,28 @@ def set_flow_user_state(key: str, value: Any) -> None:
 
 @init_global_client
 def get_state_path() -> str:
+    """Get the state resource path from environment.
+
+    Returns:
+        State path string
+    """
     return _client.state_path
 
 
 @init_global_client
-def get_resume_urls(approver: str = None) -> dict:
-    return _client.get_resume_urls(approver)
+def get_resume_urls(approver: str = None, flow_level: bool = None) -> dict:
+    """Get URLs needed for resuming a flow after suspension.
+
+    Args:
+        approver: Optional approver name
+        flow_level: If True, generate resume URLs for the parent flow instead of the
+            specific step. This allows pre-approvals that can be consumed by any later
+            suspend step in the same flow.
+
+    Returns:
+        Dictionary with approvalPage, resume, and cancel URLs
+    """
+    return _client.get_resume_urls(approver, flow_level)
 
 
 @init_global_client
@@ -1440,6 +1931,17 @@ def request_interactive_slack_approval(
 def send_teams_message(
     conversation_id: str, text: str, success: bool, card_block: dict = None
 ):
+    """Send a message to a Microsoft Teams conversation.
+
+    Args:
+        conversation_id: Teams conversation ID
+        text: Message text
+        success: Whether to style as success message
+        card_block: Optional adaptive card block
+
+    Returns:
+        HTTP response from Teams
+    """
     return _client.send_teams_message(conversation_id, text, success, card_block)
 
 
@@ -1527,6 +2029,18 @@ def run_script_by_hash(
         timeout=timeout,
     )
 
+@init_global_client
+def run_inline_script_preview(
+    content: str,
+    language: str,
+    args: dict = None,
+) -> Any:
+    """Run a script on the current worker without creating a job"""
+    return _client.run_inline_script_preview(
+        content=content,
+        language=language,
+        args=args,
+    )
 
 @init_global_client
 def username_to_email(username: str) -> str:
@@ -1538,7 +2052,42 @@ def username_to_email(username: str) -> str:
     return _client.username_to_email(username)
 
 
+@init_global_client
+def datatable(name: str = "main") -> DataTableClient:
+    """Get a DataTable client for SQL queries.
+
+    Args:
+        name: Database name (default: "main")
+
+    Returns:
+        DataTableClient instance
+    """
+    return _client.datatable(name)
+
+@init_global_client
+def ducklake(name: str = "main") -> DucklakeClient:
+    """Get a DuckLake client for DuckDB queries.
+
+    Args:
+        name: Database name (default: "main")
+
+    Returns:
+        DucklakeClient instance
+    """
+    return _client.ducklake(name)
+
 def task(*args, **kwargs):
+    """Decorator to mark a function as a workflow task.
+
+    When executed inside a Windmill job, the decorated function runs as a
+    separate workflow step. Outside Windmill, it executes normally.
+
+    Args:
+        tag: Optional worker tag for execution
+
+    Returns:
+        Decorated function
+    """
     from inspect import signature
 
     def f(func, tag: str | None = None):
@@ -1635,3 +2184,161 @@ def stream_result(stream) -> None:
     """
     for text in stream:
         append_to_result_stream(text)
+
+class DataTableClient:
+    """Client for executing SQL queries against Windmill DataTables."""
+
+    def __init__(self, client: Windmill, name: str):
+        """Initialize DataTableClient.
+
+        Args:
+            client: Windmill client instance
+            name: DataTable name
+        """
+        self.client = client
+        self.name, self.schema = parse_sql_client_name(name)
+    def query(self, sql: str, *args) -> SqlQuery:
+        """Execute a SQL query against the DataTable.
+
+        Args:
+            sql: SQL query string with $1, $2, etc. placeholders
+            *args: Positional arguments to bind to query placeholders
+
+        Returns:
+            SqlQuery instance for fetching results
+        """
+        if self.schema is not None:
+            sql = f'SET search_path TO "{self.schema}";\n' + sql
+
+        args_dict = {}
+        args_def = ""
+        for i, arg in enumerate(args):
+            args_dict[f"arg{i+1}"] = arg
+            args_def += f"-- ${i+1} arg{i+1}\n"
+        sql = args_def + sql
+        return SqlQuery(
+            sql,
+            lambda sql: self.client.run_inline_script_preview(
+                content=sql,
+                language="postgresql",
+                args={"database": f"datatable://{self.name}", **args_dict},
+            )
+        )
+
+class DucklakeClient:
+    """Client for executing DuckDB queries against Windmill DuckLake."""
+
+    def __init__(self, client: Windmill, name: str):
+        """Initialize DucklakeClient.
+
+        Args:
+            client: Windmill client instance
+            name: DuckLake database name
+        """
+        self.client = client
+        self.name = name 
+
+    def query(self, sql: str, **kwargs):
+        """Execute a DuckDB query against the DuckLake database.
+
+        Args:
+            sql: SQL query string with $name placeholders
+            **kwargs: Named arguments to bind to query placeholders
+
+        Returns:
+            SqlQuery instance for fetching results
+        """
+        args_dict = {}
+        args_def = ""
+        for key, value in kwargs.items():
+            args_dict[key] = value
+            args_def += f"-- ${key} ({infer_sql_type(value)})\n"
+        attach = f"ATTACH 'ducklake://{self.name}' AS dl;USE dl;\n"
+        sql = args_def + attach + sql
+        return SqlQuery(
+            sql,
+            lambda sql: self.client.run_inline_script_preview(
+                content=sql,
+                language="duckdb",
+                args=args_dict,
+            )
+        )
+
+class SqlQuery:
+    """Query result handler for DataTable and DuckLake queries."""
+
+    def __init__(self, sql: str, fetch_fn):
+        """Initialize SqlQuery.
+
+        Args:
+            sql: SQL query string
+            fetch_fn: Function to execute the query
+        """
+        self.sql = sql
+        self.fetch_fn = fetch_fn
+
+    def fetch(self, result_collection: str | None = None):
+        """Execute query and fetch results.
+
+        Args:
+            result_collection: Optional result collection mode
+
+        Returns:
+            Query results
+        """
+        sql = self.sql
+        if result_collection is not None:
+            sql = f'-- result_collection={result_collection}\n{sql}'
+        return self.fetch_fn(sql)
+
+    def fetch_one(self):
+        """Execute query and fetch first row of results.
+
+        Returns:
+            First row of query results
+        """
+        return self.fetch(result_collection="last_statement_first_row")
+
+    def fetch_one_scalar(self):
+        """Execute query and fetch first row of results. Return result as a scalar value.
+
+        Returns:
+            First row of query result as a scalar value
+        """
+        return self.fetch(result_collection="last_statement_first_row_scalar")
+
+    def execute(self):
+        """Execute query and don't return any results.
+        """
+        self.fetch_one()
+
+def infer_sql_type(value) -> str:
+    """
+    DuckDB executor requires explicit argument types at declaration
+    These types exist in both DuckDB and Postgres
+    Check that the types exist if you plan to extend this function for other SQL engines.
+    """
+    if isinstance(value, bool):
+        # Check bool before int since bool is a subclass of int in Python
+        return "BOOLEAN"
+    elif isinstance(value, int):
+        return "BIGINT"
+    elif isinstance(value, float):
+        return "DOUBLE PRECISION"
+    elif value is None:
+        return "TEXT"
+    elif isinstance(value, str):
+        return "TEXT"
+    elif isinstance(value, dict) or isinstance(value, list):
+        return "JSON"
+    else:
+        return "TEXT"
+
+def parse_sql_client_name(name: str) -> tuple[str, Optional[str]]:
+    name = name
+    schema = None
+    if ":" in name:
+        name, schema = name.split(":", 1) 
+    if not name:
+        name = "main"
+    return name, schema

{wmill-1.583.0 → wmill-1.609.0}/wmill/s3_reader.py

@@ -5,6 +5,15 @@ import httpx
 
 
 class S3BufferedReader(BufferedReader):
+    """Streaming buffered reader for S3 files via Windmill's S3 proxy.
+
+    Args:
+        workspace: Windmill workspace ID
+        windmill_client: HTTP client for Windmill API
+        file_key: S3 file key/path
+        s3_resource_path: Optional path to S3 resource configuration
+        storage: Optional storage backend identifier
+    """
     def __init__(self, workspace: str, windmill_client: httpx.Client, file_key: str, s3_resource_path: Optional[str], storage: Optional[str]):
         params = {
             "file_key": file_key,
@@ -62,6 +71,14 @@ class S3BufferedReader(BufferedReader):
 
 
 def bytes_generator(buffered_reader: Union[BufferedReader, BytesIO]):
+    """Yield 50KB chunks from a buffered reader.
+
+    Args:
+        buffered_reader: File-like object to read from
+
+    Yields:
+        Bytes chunks of up to 50KB
+    """
     while True:
         byte = buffered_reader.read(50 * 1024)
         if not byte:

{wmill-1.583.0 → wmill-1.609.0}/wmill/s3_types.py

@@ -2,6 +2,7 @@ from typing import Optional
 
 
 class S3Object(dict):
+    """S3 file reference with file key, optional storage identifier, and presigned token."""
     s3: str
     storage: Optional[str]
     presigned: Optional[str]
@@ -11,6 +12,7 @@ class S3Object(dict):
 
 
 class S3FsClientKwargs(dict):
+    """S3FS client keyword arguments for region configuration."""
     region_name: str
 
     def __getattr__(self, attr):
@@ -18,6 +20,7 @@ class S3FsClientKwargs(dict):
 
 
 class S3FsArgs(dict):
+    """S3FS connection arguments including endpoint, credentials, and client settings."""
     endpoint_url: str
     key: str
     secret: str
@@ -30,6 +33,7 @@ class S3FsArgs(dict):
 
 
 class StorageOptions(dict):
+    """Storage options for Polars S3 connectivity with AWS credentials and endpoint."""
     aws_endpoint_url: str
     aws_access_key_id: str
     aws_secret_access_key: str
@@ -41,6 +45,7 @@ class StorageOptions(dict):
 
 
 class PolarsConnectionSettings(dict):
+    """Polars S3 connection settings containing S3FS args and storage options."""
     s3fs_args: S3FsArgs
     storage_options: StorageOptions
 
@@ -49,6 +54,7 @@ class PolarsConnectionSettings(dict):
 
 
 class Boto3ConnectionSettings(dict):
+    """Boto3 S3 connection settings with endpoint, region, and AWS credentials."""
     endpoint_url: str
     region_name: str
     use_ssl: bool
@@ -60,6 +66,7 @@ class Boto3ConnectionSettings(dict):
 
 
 class DuckDbConnectionSettings(dict):
+    """DuckDB S3 connection settings as a configuration string."""
     connection_settings_str: str
 
     def __getattr__(self, attr):