feat!: Make Python bindings public

Cargo.toml

@@ -4,9 +4,9 @@ resolver = "2"
 
 [workspace.dependencies]
 qcs-api = "0.2.1"
-qcs-api-client-common = "0.8.4"
-qcs-api-client-grpc = "0.8.4"
-qcs-api-client-openapi = "0.9.4"
+qcs-api-client-common = "0.8.14"
+qcs-api-client-grpc = "0.8.7"
+qcs-api-client-openapi = "0.9.7"
 serde_json = "1.0.86"
 thiserror = "1.0.57"
 tokio = "1.36.0"
@@ -32,7 +32,7 @@ pyo3-opentelemetry = { version = "=0.3.2-dev.1" }
 pyo3-tracing-subscriber = { version = "=0.1.2-dev.1", default-features = true }
 
 pyo3-build-config = "0.20.0"
-rigetti-pyo3 = { version = "0.3.1", default-features = false, features = ["time", "complex"] }
+rigetti-pyo3 = { version = "0.4.1", default-features = false, features = ["complex", "time"] }
 
 # The primary intent of these options is to reduce the binary size for Python wheels
 # since PyPi has limits on how much storage a project can use.

crates/lib/src/qpu/api.rs

@@ -3,6 +3,7 @@
 
 use std::{convert::TryFrom, fmt, time::Duration};
 
+use async_trait::async_trait;
 use cached::proc_macro::cached;
 use derive_builder::Builder;
 use qcs_api_client_common::configuration::TokenError;
@@ -39,7 +40,8 @@ use crate::executable::Parameters;
 
 use crate::client::{GrpcClientError, GrpcConnection, Qcs};
 
-const MAX_DECODING_MESSAGE_SIZE_BYTES: usize = 250 * 1024 * 1024;
+/// The maximum size of a gRPC response, in bytes.
+pub const MAX_DECODING_MESSAGE_SIZE_BYTES: usize = 250 * 1024 * 1024;
 
 pub(crate) fn params_into_job_execution_configuration(
     params: &Parameters,
@@ -435,11 +437,21 @@ pub enum ConnectionStrategy {
     EndpointId(String),
 }
 
-/// Methods that help select and configure a controller service client given a set of
-/// [`ExecutionOptions`] and QPU ID.
-impl ExecutionOptions {
+/// An ExecutionTarget provides methods for provided the appropriate connection to the execution
+/// service.
+///
+/// Implementors provide a [`ConnectionStrategy`] and timeout, the trait provides default
+/// implementation for getting connections and execution targets.
+#[async_trait]
+pub trait ExecutionTarget<'a> {
+    /// The [`ConnectionStrategy`] to use to determine the connection target.
+    fn connection_strategy(&'a self) -> &'a ConnectionStrategy;
+    /// The timeout to use for requests to the target.
+    fn timeout(&self) -> Option<Duration>;
+
+    /// Get the [`execute_controller_job_request::Target`] for the given quantum processor ID.
     fn get_job_target(
-        &self,
+        &'a self,
         quantum_processor_id: Option<&str>,
     ) -> Option<execute_controller_job_request::Target> {
         match self.connection_strategy() {
@@ -452,8 +464,9 @@ impl ExecutionOptions {
         }
     }
 
+    /// Get the [`get_controller_job_results_request::Target`] for the given quantum processor ID.
     fn get_results_target(
-        &self,
+        &'a self,
         quantum_processor_id: Option<&str>,
     ) -> Option<get_controller_job_results_request::Target> {
         match self.connection_strategy() {
@@ -466,8 +479,9 @@ impl ExecutionOptions {
         }
     }
 
+    /// Get the [`cancel_controller_jobs_request::Target`] for the given quantum processor ID.
     fn get_cancel_target(
-        &self,
+        &'a self,
         quantum_processor_id: Option<&str>,
     ) -> Option<cancel_controller_jobs_request::Target> {
         match self.connection_strategy() {
@@ -480,9 +494,9 @@ impl ExecutionOptions {
         }
     }
 
-    /// Get a controller client for the given QPU ID.
-    pub async fn get_controller_client(
-        &self,
+    /// Get a controller client for the given quantum processor ID.
+    async fn get_controller_client(
+        &'a self,
         client: &Qcs,
         quantum_processor_id: Option<&str>,
     ) -> Result<ControllerClient<GrpcConnection>, QpuApiError> {
@@ -494,8 +508,8 @@ impl ExecutionOptions {
     }
 
     /// Get a GRPC connection to a QPU, without specifying the API to use.
-    pub async fn get_qpu_grpc_connection(
-        &self,
+    async fn get_qpu_grpc_connection(
+        &'a self,
         client: &Qcs,
         quantum_processor_id: Option<&str>,
     ) -> Result<GrpcConnection, QpuApiError> {
@@ -525,6 +539,7 @@ impl ExecutionOptions {
         self.grpc_address_to_channel(&address, client)
     }
 
+    /// Get a channel from the given gRPC address.
     fn grpc_address_to_channel(
         &self,
         address: &str,
@@ -540,6 +555,7 @@ impl ExecutionOptions {
         Ok(channel)
     }
 
+    /// Get the gateway address for the given quantum processor ID.
     async fn get_gateway_address(
         &self,
         quantum_processor_id: &str,
@@ -548,6 +564,7 @@ impl ExecutionOptions {
         get_accessor_with_cache(quantum_processor_id, client).await
     }
 
+    /// Get the default endpoint address for the given quantum processor ID.
     async fn get_default_endpoint_address(
         &self,
         quantum_processor_id: &str,
@@ -557,6 +574,19 @@ impl ExecutionOptions {
     }
 }
 
+/// Methods that help select and configure a controller service client given a set of
+/// [`ExecutionOptions`] and QPU ID.
+#[async_trait]
+impl<'a> ExecutionTarget<'a> for ExecutionOptions {
+    fn connection_strategy(&'a self) -> &'a ConnectionStrategy {
+        self.connection_strategy()
+    }
+
+    fn timeout(&self) -> Option<Duration> {
+        self.timeout()
+    }
+}
+
 #[cached(
     result = true,
     time = 60,
@@ -690,7 +720,10 @@ pub enum QpuApiError {
         /// The message associated with the failed job.
         message: String,
     },
-
+    /// Error that can occur when the gRPC status code could not be decoded.
+    #[error("The status code could not be decoded: {0}")]
+    StatusCodeDecode(String), // TODO: This error is in prost. Should we really use that as a dep
+    // just for the error type?
     /// Error that can occur if a numeric status identifier cannot be converted
     /// into a known status type.
     #[error("The request returned an invalid status: {status}. {message}")]

crates/python/Cargo.toml

@@ -21,7 +21,7 @@ crate-type = ["cdylib", "rlib"]
 async-trait = "0.1.73"
 qcs = { path = "../lib", features = ["tracing-opentelemetry"] }
 qcs-api.workspace = true
-qcs-api-client-common.workspace = true
+qcs-api-client-common = { workspace = true, features = ["python"] }
 qcs-api-client-grpc.workspace = true
 qcs-api-client-openapi.workspace = true
 pyo3.workspace = true
@@ -40,6 +40,7 @@ once_cell = "1.18.0"
 opentelemetry = { version = "0.23.0" }
 opentelemetry_sdk = { version = "0.23.0" }
 tracing = { version = "0.1.37" }
+prost = "0.12.6"
 
 [build-dependencies]
 pyo3-build-config.workspace = true

crates/python/qcs_sdk/qpu/api.pyi

@@ -434,10 +434,21 @@ class ConnectionStrategy:
     @staticmethod
     def gateway() -> ConnectionStrategy:
         """Connect through the publicly accessbile gateway."""
+    def is_gateway(self) -> bool:
+        """True if the ConnectionStrategy is to connect to the QCS gateway."""
     @staticmethod
     def direct_access() -> ConnectionStrategy:
         """Connect directly to the default endpoint, bypassing the gateway. Should only be used when you have
         direct network access and an active reservation."""
+    def is_direct_access(self) -> bool:
+        """True if the ConnectionStrategy is to use direct access."""
     @staticmethod
     def endpoint_id(endpoint_id: str) -> ConnectionStrategy:
         """Connect directly to a specific endpoint using its ID."""
+    def is_endpoint_id(self) -> bool:
+        """True if the ConnectionStrategy is to connect to a particular endpoint ID."""
+    def get_endpoint_id(self) -> str:
+        """Get the endpoint ID used by the ConnectionStrategy.
+
+        Raises an error if this ConnectionStrategy doesn't use a specific endpoint ID.
+        """

crates/python/qcs_sdk/qpu/translation.pyi

@@ -155,3 +155,7 @@ class TranslationOptions:
         :param: allow_frame_redefinition: If True, allow defined frames to differ from Rigetti defaults. Only available to certain users.
         Otherwise, only ``INITIAL-FREQUENCY`` and ``CHANNEL-DELAY`` may be modified.
         """
+    def encode_as_protobuf(self) -> bytes:
+        """
+        Serialize these translation options into the Protocol Buffer format.
+        """

crates/python/src/client.rs

@@ -107,7 +107,7 @@ py_wrap_type! {
 }
 
 impl PyQcsClient {
-    pub(crate) fn get_or_create_client(client: Option<Self>) -> Qcs {
+    pub fn get_or_create_client(client: Option<Self>) -> Qcs {
         match client {
             Some(client) => client.into(),
             None => Qcs::load(),
@@ -201,6 +201,16 @@ impl PyQcsClient {
         self.as_ref().get_config().qvm_url().to_string()
     }
 
+    #[getter]
+    pub fn auth_server(&self) -> AuthServer {
+        self.as_ref().get_config().auth_server().clone()
+    }
+
+    #[getter]
+    pub fn tokens(&self, py: Python<'_>) -> PyResult<Tokens> {
+        self.as_ref().get_config().get_tokens(py)
+    }
+
     fn __richcmp__(&self, other: &Self, op: CompareOp, py: Python<'_>) -> PyObject {
         match op {
             CompareOp::Eq => (self == other).into_py(py),

crates/python/src/qpu/api.rs

@@ -544,7 +544,7 @@ impl PyApiExecutionOptionsBuilder {
 }
 
 py_wrap_type! {
-    #[derive(Default)]
+    #[derive(Debug, Default)]
     PyConnectionStrategy(ConnectionStrategy) as "ConnectionStrategy"
 }
 impl_repr!(PyConnectionStrategy);
@@ -562,16 +562,37 @@ impl PyConnectionStrategy {
         Self(ConnectionStrategy::Gateway)
     }
 
+    fn is_gateway(&self) -> bool {
+        matches!(self.as_inner(), ConnectionStrategy::Gateway)
+    }
+
     #[staticmethod]
     fn direct_access() -> Self {
         Self(ConnectionStrategy::DirectAccess)
     }
 
+    fn is_direct_access(&self) -> bool {
+        matches!(self.as_inner(), ConnectionStrategy::DirectAccess)
+    }
+
     #[staticmethod]
     fn endpoint_id(endpoint_id: String) -> PyResult<Self> {
         Ok(Self(ConnectionStrategy::EndpointId(endpoint_id)))
     }
 
+    fn is_endpoint_id(&self) -> bool {
+        matches!(self.as_inner(), ConnectionStrategy::EndpointId(_))
+    }
+
+    fn get_endpoint_id(&self) -> PyResult<String> {
+        match self.as_inner() {
+            ConnectionStrategy::EndpointId(id) => Ok(id.clone()),
+            _ => Err(PyValueError::new_err(
+                "ConnectionStrategy is not an EndpointId",
+            )),
+        }
+    }
+
     fn __richcmp__(&self, py: Python<'_>, other: &Self, op: CompareOp) -> PyObject {
         match op {
             CompareOp::Eq => (self.as_inner() == other.as_inner()).into_py(py),