general_superstaq.job
=====================

.. py:module:: general_superstaq.job

.. autoapi-nested-parse::

   Represents a job created via the Superstaq API.



Classes
-------

.. autoapisummary::

   general_superstaq.job.Job


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

.. py:class:: Job(client: general_superstaq.superstaq_client._SuperstaqClientV3, job_id: uuid.UUID | str)

   A job created on the Superstaq API.

   Note that this is mutable, when calls to get status or results are made the job updates itself
   If a job is canceled or deleted, only the job id and the status remain valid.


   .. py:method:: cancel(**kwargs: object) -> None

      Cancel the current job if it is not in a terminal state.

      :param index: An optional index of the specific sub-job to cancel.
      :param kwargs: Extra options needed to fetch jobs.

      :raises ~general_superstaq.SuperstaqServerException: If unable to get the status of the job from the API or
      :raises cancellations were unsuccessful.:



   .. py:method:: job_id() -> uuid.UUID

      Gets the job id of this job.

      This is the unique identifier used for identifying the job by the API.

      :returns: This job's id (a string).



   .. py:method:: target() -> str

      Gets the Superstaq target associated with this job.

      :returns: The target to which this job was submitted.

      :raises ~general_superstaq.SuperstaqServerException: If unable to get the job from the API.



   .. py:method:: to_dict() -> dict[str, general_superstaq.typing.Job]

      Refreshes and returns job information.

      .. note::

         The contents of this dictionary are not guaranteed to be consistent over time. Whenever
         possible, users should use the specific `Job` methods to retrieve the desired job
         information instead of relying on particular entries in the output of this method.

      :returns: A dictionary containing updated job information.



   .. py:method:: wait_until_complete(index: int | None = None, timeout_seconds: float | None = None, polling_seconds: float = 5) -> None

      Waits until either the job is done or some error in the job occurs.

      :param index: An optional index of the specific circuit to wait for (otherwise waits for all
                    circuits to complete).
      :param timeout_seconds: The total number of seconds to poll for.
      :param polling_seconds: The interval with which to poll.



   .. py:attribute:: STATUS_PRIORITY_ORDER


   .. py:property:: job_data
      :type: general_superstaq.models.JobData



   .. py:property:: metadata
      :type: dict[str, object]


      Any metadata passed when creating this job.


   .. py:property:: tags
      :type: list[str]


      All tags associated with this job.