qcs-api-client-common 0.19.0

// Copyright 2022 Rigetti Computing
//
// Licensed under the Apache License, Version 2.0 (the "License");
// you may not use this file except in compliance with the License.
// You may obtain a copy of the License at
//
// http://www.apache.org/licenses/LICENSE-2.0
//
// Unless required by applicable law or agreed to in writing, software
// distributed under the License is distributed on an "AS IS" BASIS,
// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
// See the License for the specific language governing permissions and
// limitations under the License.

//! Implementation code common to the QCS OpenAPI and gRPC clients.
//!
//! You probably don't need to use this directly, as the clients should expose anything you might
//! need.
//!
//! # Features
//!
//! - `tracing`: enables `tracing` support in [`ClientConfiguration`].
//! - `tracing-config`: enables [`TracingConfiguration`] support for enabling/disabling traces per-URL.
//!   Requires the `tracing` feature.
//! - `python`: enables Python bindings for the client.
pub mod backoff;
pub mod configuration;
pub use configuration::ClientConfiguration;

#[cfg(feature = "clap")]
pub mod clap_utils;

#[cfg(feature = "tracing-config")]
pub mod tracing_configuration;

#[cfg(feature = "python")]
pub mod errors;

#[cfg(feature = "python")]
use pyo3::prelude::*;

#[cfg(feature = "python")]
rigetti_pyo3::create_init_submodule! {
    errors: [ errors::QcsApiClientError ],
    submodules: ["configuration": configuration::py::init_submodule],
}

/// The docstring for the `qcs_api_client_common` Python package.
///
/// Both `__init__.py` files in the package are generated by `pyo3_stub_gen`, which does not
/// write docstrings into them, so this is the only definition of the package docstring:
/// [`init_module`] assigns it to the package at import time, and `module_doc!` copies it into
/// the generated type stubs.
#[cfg(feature = "python")]
const PACKAGE_DOC: &str = "A suite of common functionalities for QCS client applications.

This package offers reusable middleware implementations
that can be integrated into various client libraries.
This allows for consistent behavior across different projects
and facilitates easier maintenance and scalability of client-side logic.

⚠️ This package is still in early development
and breaking changes should be expected between minor versions.
";

#[cfg(feature = "python")]
#[pymodule]
#[pyo3(name = "_qcs_api_client_common")]
fn init_module(m: &Bound<'_, PyModule>) -> PyResult<()> {
    let py = m.py();
    init_submodule("qcs_api_client_common._qcs_api_client_common", py, m)?;

    m.setattr("__doc__", PACKAGE_DOC)?;

    Ok(())
}

#[cfg(feature = "stubs")]
mod stubs {
    use pyo3_stub_gen::{module_doc, reexport_module_members};

    // During stub generation, these `qcs_api_client_common._qcs_api_client_common` modules and
    // their contents will be re-exported into the `qcs_api_client_common` namespace, and the
    // corresponding `__init__.py` files will be generated.
    reexport_module_members!("qcs_api_client_common" from "qcs_api_client_common._qcs_api_client_common"; *, "__doc__");
    reexport_module_members!(
        "qcs_api_client_common.configuration" from "qcs_api_client_common._qcs_api_client_common.configuration"
    );

    // The pure-Python modules are unknown to `pyo3_stub_gen`, so re-export them into the
    // top-level namespace explicitly. Naming the package as its own source module is
    // deliberate: it generates `from qcs_api_client_common import grpc, httpx`, which resolves
    // the submodules through the partially-initialized package in `sys.modules`.
    reexport_module_members!("qcs_api_client_common" from "qcs_api_client_common"; "grpc", "httpx");

    module_doc!(
        "qcs_api_client_common._qcs_api_client_common",
        "{}",
        crate::PACKAGE_DOC
    );
}

#[cfg(feature = "stubs")]
pyo3_stub_gen::define_stub_info_gatherer!(stub_info);