Fix issues with Workspace documentation, add more documentation, and …

…fix linting errors (#583)

* Move workspace class/constructor documentation up

* Additional documentation and linting

* Fix rtype cross-references for typing types

azure-quantum/azure/quantum/job/__init__.py

@@ -8,7 +8,7 @@
 from azure.quantum._client.models import JobDetails
 from .base_job import BaseJob
 from .filtered_job import FilteredJob
-from .job import Job
+from .job import Job, ContentType
 from .job_failed_with_results_error import JobFailedWithResultsError
 from .workspace_item import WorkspaceItem
 from .workspace_item_factory import WorkspaceItemFactory
@@ -17,6 +17,7 @@
 __all__ = [
     "Job",
     "JobDetails",
+    "ContentType",
     "BaseJob",
     "FilteredJob",
     "WorkspaceItem",

azure-quantum/azure/quantum/job/job.py

@@ -114,7 +114,7 @@ def get_results(self, timeout_secs: float = DEFAULT_TIMEOUT):
         :param timeout_secs: Timeout in seconds, defaults to 300
         :type timeout_secs: float
         :return: Results dictionary with histogram shots, or raw results if not a json object.
-        :rtype: Any
+        :rtype: typing.Any
         """
         if self.results is not None:
             return self.results

azure-quantum/azure/quantum/qiskit/__init__.py

@@ -5,10 +5,11 @@
 
 """Azure Quantum Qiskit Provider"""
 
-from .provider import AzureQuantumProvider
+from .provider import AzureQuantumProvider, AzureQuantumJob
 from azure.quantum import __version__
 
 __all__ = [
     "AzureQuantumProvider",
+    "AzureQuantumJob",
     "__version__"
 ]

azure-quantum/azure/quantum/qiskit/backends/__init__.py

@@ -43,3 +43,9 @@
     MicrosoftBackend,
     MicrosoftResourceEstimationBackend,
 )
+
+from .backend import AzureBackendBase
+
+__all__ = [
+    "AzureBackendBase"
+]

azure-quantum/azure/quantum/qiskit/provider.py

@@ -6,7 +6,7 @@
 import warnings
 import inspect
 from itertools import groupby
-from typing import Dict, List, Tuple, Type
+from typing import Dict, List, Optional, Tuple, Type
 from azure.quantum import Workspace
 
 try:
@@ -24,17 +24,13 @@
 from azure.quantum.qiskit.job import AzureQuantumJob
 from azure.quantum.qiskit.backends import *
 
-
 QISKIT_USER_AGENT = "azure-quantum-qiskit"
 
-
 class AzureQuantumProvider(Provider):
-    """
-    Class for interfacing with the Azure Quantum service
-    using Qiskit quantum circuits
-    """
-    def __init__(self, workspace: Workspace=None, **kwargs):
-        """AzureQuantumService class
+
+    def __init__(self, workspace: Optional[Workspace]=None, **kwargs):
+        """Class for interfacing with the Azure Quantum service
+        using Qiskit quantum circuits.
 
         :param workspace: Azure Quantum workspace. If missing it will create a new Workspace passing `kwargs` to the constructor. Defaults to None. 
         :type workspace: Workspace
@@ -66,7 +62,7 @@ def get_backend(self, name=None, **kwargs) -> AzureBackendBase:
             name (str): name of the backend.
             **kwargs: dict used for filtering.
         Returns:
-            Backend: a backend matching the filtering.
+            azure.quantum.qiskit.backends.AzureBackendBase: a backend matching the filtering.
         Raises:
             QiskitBackendNotFoundError: if no backend could be found or
                 more than one backend matches the filtering criteria.
@@ -110,7 +106,7 @@ def backends(self, name=None, **kwargs):
             name (str): name of the backend.
             **kwargs: dict used for filtering.
         Returns:
-            typing.List[qiskit.providers.BackendV1]: a list of Backends that match the filtering
+            typing.List[azure.quantum.qiskit.backends.AzureBackendBase]: a list of Backends that match the filtering
                 criteria.
         """
 
@@ -143,7 +139,13 @@ def backends(self, name=None, **kwargs):
         return backends
 
     def get_job(self, job_id) -> AzureQuantumJob:
-        """Returns the Job instance associated with the given id."""
+        """Returns the Job instance associated with the given id.
+        
+        Args:
+            job_id (str): Id of the Job to return.
+        Returns:
+            AzureQuantumJob: Job instance.
+        """
         azure_job = self._workspace.get_job(job_id)
         backend = self.get_backend(azure_job.details.target)
         return AzureQuantumJob(backend, azure_job)

azure-quantum/azure/quantum/target/microsoft/elements/dft/job.py

@@ -30,7 +30,7 @@ def get_results(self, timeout_secs: float = DEFAULT_TIMEOUT) -> Dict[str, Any]:
         :raises: :class:`RuntimeError` if job execution failed.
         :raises: :class:`azure.quantum.job.JobFailedWithResultsError` if job execution failed,
                 but failure results could still be retrieved.
-        :return: Results dictionary with histogram shots, or raw results if not a json object.
+        :return: Results dictionary.
         """
 
         try:

azure-quantum/azure/quantum/target/pasqal/result.py

@@ -26,16 +26,16 @@ class Result:
        job = Job(...)  # This job should come from a Pasqal target
        job.wait_until_completed()
        result = Result(job)
-
     """
 
     def __init__(self, job: Job) -> None:
         """
         Decode the results of a Job with output type of "pasqal.pulser-results.v1"
 
-        :param job: Azure Quantum job
-        :type job: Job
-        :raises: RuntimeError if the job has not completed successfully
+        Args:
+            job (Job): Azure Quantum job
+        Raises:
+            RuntimeError: if the job has not completed successfully
         """
 
         if job.details.status != "Succeeded":

azure-quantum/azure/quantum/target/pasqal/target.py

@@ -25,6 +25,8 @@ class PasqalTarget(str, Enum):
     """
 
     SIM_EMU_TN = "pasqal.sim.emu-tn"
+    """pasqal.sim.emu-tn target"""
+
     QPU_FRESNEL = "pasqal.qpu.fresnel"
     """A simulator target for Quil. See https://github.com/quil-lang/qvm for more info."""
 
@@ -52,7 +54,11 @@ def num_qubits(target_name) -> int:
 
 @dataclass
 class InputParams:
-    """Input parameters"""
+    """Input parameters
+
+    Args:
+        runs (int): The number of times to run the experiment.
+    """
 
     runs: int = 1
     """The number of times to run the experiment."""
@@ -79,6 +85,25 @@ def __init__(
         encoding: str = "",
         **kwargs,
     ):
+        """
+        Initializes a new target.
+
+        :param workspace: Associated workspace
+        :type workspace: Workspace
+        :param name: Target name
+        :type name: str
+        :param input_data_format: Format of input data (ex. "pasqal.pulser.v1")
+        :type input_data_format: str
+        :param output_data_format: Format of output data (ex. "pasqal.pulser-results.v1")
+        :type output_data_format: str
+        :param capability: QIR capability
+        :type capability: str
+        :param provider_id: Id of provider (ex. "pasqal")
+        :type provider_id: str
+        :param encoding: "Content-Encoding" attribute value to set on input blob (ex. "gzip")
+        :type encoding: str
+        """
+
         super().__init__(
             workspace=workspace,
             name=name,

azure-quantum/azure/quantum/target/rigetti/result.py

@@ -21,22 +21,26 @@
 class Result:
     """Downloads the data of a completed Job and extracts the ``Readout`` for each register.
 
-    >>> from azure.quantum.job import Job
-    >>> from azure.quantum.target.rigetti import Result
-    >>> job = Job(...)  # This job should come from a Rigetti target
-    >>> job.wait_until_completed()
-    >>> result = Result(job)
-    >>> ro_data = result["ro"]
-    >>> first_shot_data = ro_data[0]
+    .. highlight:: python
+    .. code-block::
+    
+       from azure.quantum.job import Job
+       from azure.quantum.target.rigetti import Result
+       job = Job(...)  # This job should come from a Rigetti target
+       job.wait_until_completed()
+       result = Result(job)
+       ro_data = result["ro"]
+       first_shot_data = ro_data[0]
     """
 
     def __init__(self, job: Job) -> None:
         """
         Decode the results of a Job with output type of "rigetti.quil-results.v1"
 
-        :param job: Azure Quantum Job
-        :type job: Job
-        :raises: RuntimeError if the job has not completed successfully
+        Args:
+            job (Job): Azure Quantum job
+        Raises:
+            RuntimeError: if the job has not completed successfully
         """
 
         if job.details.status != "Succeeded":
@@ -53,6 +57,7 @@ def __getitem__(self, register_name: str) -> "Readout":
 
 
 T = TypeVar("T", bound=Union[int, float, complex])
+
 Readout = List[List[T]]
 """Contains the data of a declared "readout" memory region, usually the ``ro`` register.
 

azure-quantum/azure/quantum/target/rigetti/target.py

@@ -146,6 +146,25 @@ def __init__(
         encoding: str = "",
         **kwargs,
     ):
+        """
+        Initializes a new target.
+
+        :param workspace: Associated workspace
+        :type workspace: Workspace
+        :param name: Target name
+        :type name: str
+        :param input_data_format: Format of input data (ex. "rigetti.quil.v1")
+        :type input_data_format: str
+        :param output_data_format: Format of output data (ex. "rigetti.quil-results.v1")
+        :type output_data_format: str
+        :param capability: QIR capability
+        :type capability: str
+        :param provider_id: Id of provider (ex. "rigetti")
+        :type provider_id: str
+        :param encoding: "Content-Encoding" attribute value to set on input blob (ex. "gzip")
+        :type encoding: str
+        """
+
         super().__init__(
             workspace=workspace,
             name=name,

azure-quantum/azure/quantum/target/target.py

@@ -77,7 +77,7 @@ def __init__(
         :param provider_id: Id of provider (ex. "microsoft-qc")
         :type provider_id: str
         :param content_type: "Content-Type" attribute value to set on input blob (ex. "application/json")
-        :type content_type: ContentType
+        :type content_type: azure.quantum.job.ContentType
         :param encoding: "Content-Encoding" attribute value to set on input blob (ex. "gzip")
         :type encoding: str
         :param average_queue_time: Set average queue time (for internal use)