hatchet-sdk 1.6.2__py3-none-any.whl → 1.6.3__py3-none-any.whl

hatchet_sdk/features/runs.py

@@ -89,6 +89,10 @@ class BulkCancelReplayOpts(BaseModel):
 
 
 class RunsClient(BaseRestClient):
+    """
+    The runs client is a client for interacting with task and workflow runs within Hatchet.
+    """
+
     def __init__(
         self,
         config: ClientConfig,
@@ -107,10 +111,22 @@ class RunsClient(BaseRestClient):
         return TaskApi(client)
 
     def get(self, workflow_run_id: str) -> V1WorkflowRunDetails:
+        """
+        Get workflow run details for a given workflow run ID.
+
+        :param workflow_run_id: The ID of the workflow run to retrieve details for.
+        :return: Workflow run details for the specified workflow run ID.
+        """
         with self.client() as client:
             return self._wra(client).v1_workflow_run_get(str(workflow_run_id))
 
     async def aio_get(self, workflow_run_id: str) -> V1WorkflowRunDetails:
+        """
+        Get workflow run details for a given workflow run ID.
+
+        :param workflow_run_id: The ID of the workflow run to retrieve details for.
+        :return: Workflow run details for the specified workflow run ID.
+        """
         return await asyncio.to_thread(self.get, workflow_run_id)
 
     async def aio_list(
@@ -126,6 +142,22 @@ class RunsClient(BaseRestClient):
         worker_id: str | None = None,
         parent_task_external_id: str | None = None,
     ) -> V1TaskSummaryList:
+        """
+        List task runs according to a set of filters.
+
+        :param since: The start time for filtering task runs.
+        :param only_tasks: Whether to only list task runs.
+        :param offset: The offset for pagination.
+        :param limit: The maximum number of task runs to return.
+        :param statuses: The statuses to filter task runs by.
+        :param until: The end time for filtering task runs.
+        :param additional_metadata: Additional metadata to filter task runs by.
+        :param workflow_ids: The workflow IDs to filter task runs by.
+        :param worker_id: The worker ID to filter task runs by.
+        :param parent_task_external_id: The parent task external ID to filter task runs by.
+
+        :return: A list of task runs matching the specified filters.
+        """
         return await asyncio.to_thread(
             self.list,
             since=since,
@@ -153,6 +185,22 @@ class RunsClient(BaseRestClient):
         worker_id: str | None = None,
         parent_task_external_id: str | None = None,
     ) -> V1TaskSummaryList:
+        """
+        List task runs according to a set of filters.
+
+        :param since: The start time for filtering task runs.
+        :param only_tasks: Whether to only list task runs.
+        :param offset: The offset for pagination.
+        :param limit: The maximum number of task runs to return.
+        :param statuses: The statuses to filter task runs by.
+        :param until: The end time for filtering task runs.
+        :param additional_metadata: Additional metadata to filter task runs by.
+        :param workflow_ids: The workflow IDs to filter task runs by.
+        :param worker_id: The worker ID to filter task runs by.
+        :param parent_task_external_id: The parent task external ID to filter task runs by.
+
+        :return: A list of task runs matching the specified filters.
+        """
         with self.client() as client:
             return self._wra(client).v1_workflow_run_list(
                 tenant=self.client_config.tenant_id,
@@ -177,6 +225,18 @@ class RunsClient(BaseRestClient):
         additional_metadata: JSONSerializableMapping = {},
         priority: int | None = None,
     ) -> V1WorkflowRunDetails:
+        """
+        Trigger a new workflow run.
+
+        IMPORTANT: It's preferable to use `Workflow.run` (and similar) to trigger workflows if possible. This method is intended to be an escape hatch. For more details, see [the documentation](https://docs.hatchet.run/sdks/python/runnables#workflow).
+
+        :param workflow_name: The name of the workflow to trigger.
+        :param input: The input data for the workflow run.
+        :param additional_metadata: Additional metadata associated with the workflow run.
+        :param priority: The priority of the workflow run.
+
+        :return: The details of the triggered workflow run.
+        """
         with self.client() as client:
             return self._wra(client).v1_workflow_run_create(
                 tenant=self.client_config.tenant_id,
@@ -195,17 +255,47 @@ class RunsClient(BaseRestClient):
         additional_metadata: JSONSerializableMapping = {},
         priority: int | None = None,
     ) -> V1WorkflowRunDetails:
+        """
+        Trigger a new workflow run.
+
+        IMPORTANT: It's preferable to use `Workflow.run` (and similar) to trigger workflows if possible. This method is intended to be an escape hatch. For more details, see [the documentation](https://docs.hatchet.run/sdks/python/runnables#workflow).
+
+        :param workflow_name: The name of the workflow to trigger.
+        :param input: The input data for the workflow run.
+        :param additional_metadata: Additional metadata associated with the workflow run.
+        :param priority: The priority of the workflow run.
+
+        :return: The details of the triggered workflow run.
+        """
         return await asyncio.to_thread(
             self.create, workflow_name, input, additional_metadata, priority
         )
 
     def replay(self, run_id: str) -> None:
+        """
+        Replay a task or workflow run.
+
+        :param run_id: The external ID of the task or workflow run to replay.
+        :return: None
+        """
         self.bulk_replay(opts=BulkCancelReplayOpts(ids=[run_id]))
 
     async def aio_replay(self, run_id: str) -> None:
+        """
+        Replay a task or workflow run.
+
+        :param run_id: The external ID of the task or workflow run to replay.
+        :return: None
+        """
         return await asyncio.to_thread(self.replay, run_id)
 
     def bulk_replay(self, opts: BulkCancelReplayOpts) -> None:
+        """
+        Replay task or workflow runs in bulk, according to a set of filters.
+
+        :param opts: Options for bulk replay, including filters and IDs.
+        :return: None
+        """
         with self.client() as client:
             self._ta(client).v1_task_replay(
                 tenant=self.client_config.tenant_id,
@@ -213,15 +303,39 @@ class RunsClient(BaseRestClient):
             )
 
     async def aio_bulk_replay(self, opts: BulkCancelReplayOpts) -> None:
+        """
+        Replay task or workflow runs in bulk, according to a set of filters.
+
+        :param opts: Options for bulk replay, including filters and IDs.
+        :return: None
+        """
         return await asyncio.to_thread(self.bulk_replay, opts)
 
     def cancel(self, run_id: str) -> None:
+        """
+        Cancel a task or workflow run.
+
+        :param run_id: The external ID of the task or workflow run to cancel.
+        :return: None
+        """
         self.bulk_cancel(opts=BulkCancelReplayOpts(ids=[run_id]))
 
     async def aio_cancel(self, run_id: str) -> None:
+        """
+        Cancel a task or workflow run.
+
+        :param run_id: The external ID of the task or workflow run to cancel.
+        :return: None
+        """
         return await asyncio.to_thread(self.cancel, run_id)
 
     def bulk_cancel(self, opts: BulkCancelReplayOpts) -> None:
+        """
+        Cancel task or workflow runs in bulk, according to a set of filters.
+
+        :param opts: Options for bulk cancel, including filters and IDs.
+        :return: None
+        """
         with self.client() as client:
             self._ta(client).v1_task_cancel(
                 tenant=self.client_config.tenant_id,
@@ -229,14 +343,43 @@ class RunsClient(BaseRestClient):
             )
 
     async def aio_bulk_cancel(self, opts: BulkCancelReplayOpts) -> None:
+        """
+        Cancel task or workflow runs in bulk, according to a set of filters.
+
+        :param opts: Options for bulk cancel, including filters and IDs.
+        :return: None
+        """
         return await asyncio.to_thread(self.bulk_cancel, opts)
 
     def get_result(self, run_id: str) -> JSONSerializableMapping:
+        """
+        Get the result of a workflow run by its external ID.
+
+        :param run_id: The external ID of the workflow run to retrieve the result for.
+        :return: The result of the workflow run.
+        """
         details = self.get(run_id)
 
         return details.run.output
 
+    async def aio_get_result(self, run_id: str) -> JSONSerializableMapping:
+        """
+        Get the result of a workflow run by its external ID.
+
+        :param run_id: The external ID of the workflow run to retrieve the result for.
+        :return: The result of the workflow run.
+        """
+        details = await asyncio.to_thread(self.get, run_id)
+
+        return details.run.output
+
     def get_run_ref(self, workflow_run_id: str) -> "WorkflowRunRef":
+        """
+        Get a reference to a workflow run.
+
+        :param workflow_run_id: The ID of the workflow run to get a reference to.
+        :return: A reference to the specified workflow run.
+        """
         from hatchet_sdk.workflow_run import WorkflowRunRef
 
         return WorkflowRunRef(
@@ -245,8 +388,3 @@ class RunsClient(BaseRestClient):
             workflow_run_listener=self.workflow_run_listener,
             runs_client=self,
         )
-
-    async def aio_get_result(self, run_id: str) -> JSONSerializableMapping:
-        details = await asyncio.to_thread(self.get, run_id)
-
-        return details.run.output

hatchet_sdk/features/scheduled.py

@@ -27,6 +27,10 @@ from hatchet_sdk.utils.typing import JSONSerializableMapping
 
 
 class ScheduledClient(BaseRestClient):
+    """
+    The scheduled client is a client for managing scheduled workflows within Hatchet.
+    """
+
     def _wra(self, client: ApiClient) -> WorkflowRunApi:
         return WorkflowRunApi(client)
 
@@ -41,16 +45,16 @@ class ScheduledClient(BaseRestClient):
         additional_metadata: JSONSerializableMapping,
     ) -> ScheduledWorkflows:
         """
-        Creates a new scheduled workflow run asynchronously.
+        Creates a new scheduled workflow run.
+
+        IMPORTANT: It's preferable to use `Workflow.run` (and similar) to trigger workflows if possible. This method is intended to be an escape hatch. For more details, see [the documentation](https://docs.hatchet.run/sdks/python/runnables#workflow).
 
-        Args:
-            workflow_name (str): The name of the scheduled workflow.
-            trigger_at (datetime.datetime): The datetime when the run should be triggered.
-            input (JSONSerializableMapping): The input data for the scheduled workflow.
-            additional_metadata (JSONSerializableMapping): Additional metadata associated with the future run.
+        :param workflow_name: The name of the workflow to schedule.
+        :param trigger_at: The datetime when the run should be triggered.
+        :param input: The input data for the scheduled workflow.
+        :param additional_metadata: Additional metadata associated with the future run as a key-value pair.
 
-        Returns:
-            ScheduledWorkflows: The created scheduled workflow instance.
+        :return: The created scheduled workflow instance.
         """
         with self.client() as client:
             return self._wra(client).scheduled_workflow_run_create(
@@ -71,16 +75,16 @@ class ScheduledClient(BaseRestClient):
         additional_metadata: JSONSerializableMapping,
     ) -> ScheduledWorkflows:
         """
-        Creates a new scheduled workflow run asynchronously.
+        Creates a new scheduled workflow run.
 
-        Args:
-            workflow_name (str): The name of the scheduled workflow.
-            trigger_at (datetime.datetime): The datetime when the run should be triggered.
-            input (JSONSerializableMapping): The input data for the scheduled workflow.
-            additional_metadata (JSONSerializableMapping): Additional metadata associated with the future run as a key-value pair (e.g. {"key1": "value1", "key2": "value2"}).
+        IMPORTANT: It's preferable to use `Workflow.run` (and similar) to trigger workflows if possible. This method is intended to be an escape hatch. For more details, see [the documentation](https://docs.hatchet.run/sdks/python/runnables#workflow).
 
-        Returns:
-            ScheduledWorkflows: The created scheduled workflow instance.
+        :param workflow_name: The name of the workflow to schedule.
+        :param trigger_at: The datetime when the run should be triggered.
+        :param input: The input data for the scheduled workflow.
+        :param additional_metadata: Additional metadata associated with the future run as a key-value pair.
+
+        :return: The created scheduled workflow instance.
         """
 
         return await asyncio.to_thread(
@@ -93,10 +97,10 @@ class ScheduledClient(BaseRestClient):
 
     def delete(self, scheduled_id: str) -> None:
         """
-        Deletes a scheduled workflow run.
+        Deletes a scheduled workflow run by its ID.
 
-        Args:
-            scheduled_id (str): The scheduled workflow trigger ID to delete.
+        :param scheduled_id: The ID of the scheduled workflow run to delete.
+        :return: None
         """
         with self.client() as client:
             self._wa(client).workflow_scheduled_delete(
@@ -105,6 +109,12 @@ class ScheduledClient(BaseRestClient):
             )
 
     async def aio_delete(self, scheduled_id: str) -> None:
+        """
+        Deletes a scheduled workflow run by its ID.
+
+        :param scheduled_id: The ID of the scheduled workflow run to delete.
+        :return: None
+        """
         await asyncio.to_thread(self.delete, scheduled_id)
 
     async def aio_list(
@@ -121,18 +131,16 @@ class ScheduledClient(BaseRestClient):
         """
         Retrieves a list of scheduled workflows based on provided filters.
 
-        Args:
-            offset (int | None): The starting point for the list.
-            limit (int | None): The maximum number of items to return.
-            workflow_id (str | None): Filter by specific workflow ID.
-            parent_workflow_run_id (str | None): Filter by parent workflow run ID.
-            statuses (list[ScheduledRunStatus] | None): Filter by status.
-            additional_metadata (Optional[List[dict[str, str]]]): Filter by additional metadata.
-            order_by_field (Optional[ScheduledWorkflowsOrderByField]): Field to order the results by.
-            order_by_direction (Optional[WorkflowRunOrderByDirection]): Direction to order the results.
+        :param offset: The offset to use in pagination.
+        :param limit: The maximum number of scheduled workflows to return.
+        :param workflow_id: The ID of the workflow to filter by.
+        :param parent_workflow_run_id: The ID of the parent workflow run to filter by.
+        :param statuses: A list of statuses to filter by.
+        :param additional_metadata: Additional metadata to filter by.
+        :param order_by_field: The field to order the results by.
+        :param order_by_direction: The direction to order the results by.
 
-        Returns:
-            List[ScheduledWorkflows]: A list of scheduled workflows matching the criteria.
+        :return: A list of scheduled workflows matching the provided filters.
         """
         return await asyncio.to_thread(
             self.list,
@@ -160,18 +168,16 @@ class ScheduledClient(BaseRestClient):
         """
         Retrieves a list of scheduled workflows based on provided filters.
 
-        Args:
-            offset (int | None): The starting point for the list.
-            limit (int | None): The maximum number of items to return.
-            workflow_id (str | None): Filter by specific workflow ID.
-            parent_workflow_run_id (str | None): Filter by parent workflow run ID.
-            statuses (list[ScheduledRunStatus] | None): Filter by status.
-            additional_metadata (Optional[List[dict[str, str]]]): Filter by additional metadata.
-            order_by_field (Optional[ScheduledWorkflowsOrderByField]): Field to order the results by.
-            order_by_direction (Optional[WorkflowRunOrderByDirection]): Direction to order the results.
+        :param offset: The offset to use in pagination.
+        :param limit: The maximum number of scheduled workflows to return.
+        :param workflow_id: The ID of the workflow to filter by.
+        :param parent_workflow_run_id: The ID of the parent workflow run to filter by.
+        :param statuses: A list of statuses to filter by.
+        :param additional_metadata: Additional metadata to filter by.
+        :param order_by_field: The field to order the results by.
+        :param order_by_direction: The direction to order the results by.
 
-        Returns:
-            List[ScheduledWorkflows]: A list of scheduled workflows matching the criteria.
+        :return: A list of scheduled workflows matching the provided filters.
         """
         with self.client() as client:
             return self._wa(client).workflow_scheduled_list(
@@ -192,11 +198,8 @@ class ScheduledClient(BaseRestClient):
         """
         Retrieves a specific scheduled workflow by scheduled run trigger ID.
 
-        Args:
-            scheduled (str): The scheduled workflow trigger ID to retrieve.
-
-        Returns:
-            ScheduledWorkflows: The requested scheduled workflow instance.
+        :param scheduled_id: The scheduled workflow trigger ID to retrieve.
+        :return: The requested scheduled workflow instance.
         """
 
         with self.client() as client:
@@ -209,10 +212,7 @@ class ScheduledClient(BaseRestClient):
         """
         Retrieves a specific scheduled workflow by scheduled run trigger ID.
 
-        Args:
-            scheduled (str): The scheduled workflow trigger ID to retrieve.
-
-        Returns:
-            ScheduledWorkflows: The requested scheduled workflow instance.
+        :param scheduled_id: The scheduled workflow trigger ID to retrieve.
+        :return: The requested scheduled workflow instance.
         """
         return await asyncio.to_thread(self.get, scheduled_id)

hatchet_sdk/features/workers.py

@@ -9,19 +9,40 @@ from hatchet_sdk.clients.v1.api_client import BaseRestClient
 
 
 class WorkersClient(BaseRestClient):
+    """
+    The workers client is a client for managing workers programmatically within Hatchet.
+    """
+
     def _wa(self, client: ApiClient) -> WorkerApi:
         return WorkerApi(client)
 
     def get(self, worker_id: str) -> Worker:
+        """
+        Get a worker by its ID.
+
+        :param worker_id: The ID of the worker to retrieve.
+        :return: The worker.
+        """
         with self.client() as client:
             return self._wa(client).worker_get(worker_id)
 
     async def aio_get(self, worker_id: str) -> Worker:
+        """
+        Get a worker by its ID.
+
+        :param worker_id: The ID of the worker to retrieve.
+        :return: The worker.
+        """
         return await asyncio.to_thread(self.get, worker_id)
 
     def list(
         self,
     ) -> WorkerList:
+        """
+        List all workers in the tenant determined by the client config.
+
+        :return: A list of workers.
+        """
         with self.client() as client:
             return self._wa(client).worker_list(
                 tenant=self.client_config.tenant_id,
@@ -30,9 +51,21 @@ class WorkersClient(BaseRestClient):
     async def aio_list(
         self,
     ) -> WorkerList:
+        """
+        List all workers in the tenant determined by the client config.
+
+        :return: A list of workers.
+        """
         return await asyncio.to_thread(self.list)
 
     def update(self, worker_id: str, opts: UpdateWorkerRequest) -> Worker:
+        """
+        Update a worker by its ID.
+
+        :param worker_id: The ID of the worker to update.
+        :param opts: The update options.
+        :return: The updated worker.
+        """
         with self.client() as client:
             return self._wa(client).worker_update(
                 worker=worker_id,
@@ -40,4 +73,11 @@ class WorkersClient(BaseRestClient):
             )
 
     async def aio_update(self, worker_id: str, opts: UpdateWorkerRequest) -> Worker:
+        """
+        Update a worker by its ID.
+
+        :param worker_id: The ID of the worker to update.
+        :param opts: The update options.
+        :return: The updated worker.
+        """
         return await asyncio.to_thread(self.update, worker_id, opts)

hatchet_sdk/features/workflows.py

@@ -10,6 +10,12 @@ from hatchet_sdk.clients.v1.api_client import BaseRestClient
 
 
 class WorkflowsClient(BaseRestClient):
+    """
+    The workflows client is a client for managing workflows programmatically within Hatchet.
+
+    Note that workflows are the declaration, _not_ the individual runs. If you're looking for runs, use the `RunsClient` instead.
+    """
+
     def _wra(self, client: ApiClient) -> WorkflowRunApi:
         return WorkflowRunApi(client)
 
@@ -17,9 +23,21 @@ class WorkflowsClient(BaseRestClient):
         return WorkflowApi(client)
 
     async def aio_get(self, workflow_id: str) -> Workflow:
+        """
+        Get a workflow by its ID.
+
+        :param workflow_id: The ID of the workflow to retrieve.
+        :return: The workflow.
+        """
         return await asyncio.to_thread(self.get, workflow_id)
 
     def get(self, workflow_id: str) -> Workflow:
+        """
+        Get a workflow by its ID.
+
+        :param workflow_id: The ID of the workflow to retrieve.
+        :return: The workflow.
+        """
         with self.client() as client:
             return self._wa(client).workflow_get(workflow_id)
 
@@ -29,6 +47,15 @@ class WorkflowsClient(BaseRestClient):
         limit: int | None = None,
         offset: int | None = None,
     ) -> WorkflowList:
+        """
+        List all workflows in the tenant determined by the client config that match optional filters.
+
+        :param workflow_name: The name of the workflow to filter by.
+        :param limit: The maximum number of items to return.
+        :param offset: The offset to start the list from.
+
+        :return: A list of workflows.
+        """
         with self.client() as client:
             return self._wa(client).workflow_list(
                 tenant=self.client_config.tenant_id,
@@ -43,15 +70,38 @@ class WorkflowsClient(BaseRestClient):
         limit: int | None = None,
         offset: int | None = None,
     ) -> WorkflowList:
+        """
+        List all workflows in the tenant determined by the client config that match optional filters.
+
+        :param workflow_name: The name of the workflow to filter by.
+        :param limit: The maximum number of items to return.
+        :param offset: The offset to start the list from.
+
+        :return: A list of workflows.
+        """
         return await asyncio.to_thread(self.list, workflow_name, limit, offset)
 
     def get_version(
         self, workflow_id: str, version: str | None = None
     ) -> WorkflowVersion:
+        """
+        Get a workflow version by the workflow ID and an optional version.
+
+        :param workflow_id: The ID of the workflow to retrieve the version for.
+        :param version: The version of the workflow to retrieve. If None, the latest version is returned.
+        :return: The workflow version.
+        """
         with self.client() as client:
             return self._wa(client).workflow_version_get(workflow_id, version)
 
     async def aio_get_version(
         self, workflow_id: str, version: str | None = None
     ) -> WorkflowVersion:
+        """
+        Get a workflow version by the workflow ID and an optional version.
+
+        :param workflow_id: The ID of the workflow to retrieve the version for.
+        :param version: The version of the workflow to retrieve. If None, the latest version is returned.
+        :return: The workflow version.
+        """
         return await asyncio.to_thread(self.get_version, workflow_id, version)