client.workflow_run
===================

.. py:module:: client.workflow_run

.. autoapi-nested-parse::

   The workflow run is an instance of a workflow.



Attributes
----------

.. autoapisummary::

   client.workflow_run.logger


Classes
-------

.. autoapisummary::

   client.workflow_run.WorkflowRunFactory
   client.workflow_run.WorkflowRun


Module Contents
---------------

.. py:data:: logger

.. py:class:: WorkflowRunFactory(workflow_id: int, requester: Optional[jobmon.core.requester.Requester] = None)

   A utility class responsible for instantiating workflow run objects.

   This class sends the appropriate resume signals so that the parent workflow
   object is in a state where the newly created workflowrun is ready to run, either on
   resume or not.

   Initialization of client WorkflowRun.


   .. py:attribute:: workflow_id


   .. py:attribute:: requester
      :value: None



   .. py:attribute:: workflow_is_resumable
      :value: False



   .. py:method:: set_workflow_resume(reset_running_jobs: bool = True, resume_timeout: int = 300, force_cleanup: bool = False) -> None

      Set statuses of the given workflow ID's workflow to a resumable state.

      Move active workflow runs to hot/cold resume states, depending on reset_running_jobs.

      :param reset_running_jobs: If True (cold resume), also terminate running tasks.
                                 If False (hot resume), let running tasks finish.
      :param resume_timeout: Maximum time to wait for workflow to become resumable.
      :param force_cleanup: If True and timeout is reached with pending KILL_SELF
                            task instances, force cleanup and proceed. Use this when
                            jobs have been externally terminated (scancel, node failure).



   .. py:method:: wait_for_workflow_resume(resume_timeout: int = 300, force_cleanup: bool = False) -> None

      Wait for workflow to become resumable.

      :param resume_timeout: Maximum time to wait in seconds
      :param force_cleanup: If True and KILL_SELF task instances are detected,
                            clean them up immediately instead of waiting for workers



   .. py:method:: force_cleanup_kill_self() -> int

      Force cleanup of stuck KILL_SELF task instances.

      Use this when jobs have been externally terminated (e.g., scancel, node failure)
      and the workflow is stuck waiting for cleanup that will never happen.

      :returns: Number of task instances cleaned up



   .. py:method:: reset_task_statuses(reset_if_running: bool = True, force_cleanup: bool = False) -> None

      Sets the tasks associated with a workflow to the appropriate states.

      :param reset_if_running: If True, also reset running tasks.
      :param force_cleanup: If True and workflow not resumable due to stuck KILL_SELF
                            task instances, force cleanup and proceed.



   .. py:method:: create_workflow_run(workflow_run_heartbeat_interval: Optional[int] = None, heartbeat_report_by_buffer: Optional[float] = None) -> WorkflowRun

      Workflow should at least have signalled for a resume at this point.



.. py:class:: WorkflowRun(workflow_id: int, requester: Optional[jobmon.core.requester.Requester] = None, workflow_run_heartbeat_interval: Optional[int] = None, heartbeat_report_by_buffer: Optional[float] = None)

   Bases: :py:obj:`object`


   WorkflowRun enables tracking for multiple runs of a single Workflow.

   A Workflow may be started/paused/ and resumed multiple times. Each start or
   resume represents a new WorkflowRun.

   In order for a Workflow can be deemed to be DONE (successfully), it
   must have 1 or more WorkflowRuns. In the current implementation, a Workflow
   Job may belong to one or more WorkflowRuns, but once the Job reaches a DONE
   state, it will no longer be added to a subsequent WorkflowRun. However,
   this is not enforced via any database constraints.

   Initialize client WorkflowRun.


   .. py:attribute:: workflow_id


   .. py:attribute:: user


   .. py:attribute:: requester
      :value: None



   .. py:attribute:: heartbeat_interval


   .. py:attribute:: heartbeat_report_by_buffer


   .. py:property:: workflow_run_id
      :type: int



   .. py:property:: status
      :type: Optional[str]



   .. py:method:: bind() -> None

      Link this workflow run with the workflow and add all tasks.