qcs_api_client_common/
lib.rs

1// Copyright 2022 Rigetti Computing
2//
3// Licensed under the Apache License, Version 2.0 (the "License");
4// you may not use this file except in compliance with the License.
5// You may obtain a copy of the License at
6//
7// http://www.apache.org/licenses/LICENSE-2.0
8//
9// Unless required by applicable law or agreed to in writing, software
10// distributed under the License is distributed on an "AS IS" BASIS,
11// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
12// See the License for the specific language governing permissions and
13// limitations under the License.
14
15//! Implementation code common to the QCS OpenAPI and gRPC clients.
16//!
17//! You probably don't need to use this directly, as the clients should expose anything you might
18//! need.
19//!
20//! # Features
21//!
22//! - `tracing`: enables `tracing` support in [`ClientConfiguration`].
23//! - `tracing-config`: enables [`TracingConfiguration`] support for enabling/disabling traces per-URL.
24//!   Requires the `tracing` feature.
25//! - `python`: enables Python bindings for the client.
26pub mod backoff;
27pub mod configuration;
28pub use configuration::ClientConfiguration;
29
30#[cfg(feature = "clap")]
31pub mod clap_utils;
32
33#[cfg(feature = "tracing-config")]
34pub mod tracing_configuration;
35
36#[cfg(feature = "python")]
37pub mod errors;
38
39#[cfg(feature = "python")]
40use pyo3::prelude::*;
41
42#[cfg(feature = "python")]
43rigetti_pyo3::create_init_submodule! {
44    errors: [ errors::QcsApiClientError ],
45    submodules: ["configuration": configuration::py::init_submodule],
46}
47
48/// The docstring for the `qcs_api_client_common` Python package.
49///
50/// Both `__init__.py` files in the package are generated by `pyo3_stub_gen`, which does not
51/// write docstrings into them, so this is the only definition of the package docstring:
52/// [`init_module`] assigns it to the package at import time, and `module_doc!` copies it into
53/// the generated type stubs.
54#[cfg(feature = "python")]
55const PACKAGE_DOC: &str = "A suite of common functionalities for QCS client applications.
56
57This package offers reusable middleware implementations
58that can be integrated into various client libraries.
59This allows for consistent behavior across different projects
60and facilitates easier maintenance and scalability of client-side logic.
61
62⚠️ This package is still in early development
63and breaking changes should be expected between minor versions.
64";
65
66#[cfg(feature = "python")]
67#[pymodule]
68#[pyo3(name = "_qcs_api_client_common")]
69fn init_module(m: &Bound<'_, PyModule>) -> PyResult<()> {
70    let py = m.py();
71    init_submodule("qcs_api_client_common._qcs_api_client_common", py, m)?;
72
73    m.setattr("__doc__", PACKAGE_DOC)?;
74
75    Ok(())
76}
77
78#[cfg(feature = "stubs")]
79mod stubs {
80    use pyo3_stub_gen::{module_doc, reexport_module_members};
81
82    // During stub generation, these `qcs_api_client_common._qcs_api_client_common` modules and
83    // their contents will be re-exported into the `qcs_api_client_common` namespace, and the
84    // corresponding `__init__.py` files will be generated.
85    reexport_module_members!("qcs_api_client_common" from "qcs_api_client_common._qcs_api_client_common"; *, "__doc__");
86    reexport_module_members!(
87        "qcs_api_client_common.configuration" from "qcs_api_client_common._qcs_api_client_common.configuration"
88    );
89
90    // The pure-Python modules are unknown to `pyo3_stub_gen`, so re-export them into the
91    // top-level namespace explicitly. Naming the package as its own source module is
92    // deliberate: it generates `from qcs_api_client_common import grpc, httpx`, which resolves
93    // the submodules through the partially-initialized package in `sys.modules`.
94    reexport_module_members!("qcs_api_client_common" from "qcs_api_client_common"; "grpc", "httpx");
95
96    module_doc!(
97        "qcs_api_client_common._qcs_api_client_common",
98        "{}",
99        crate::PACKAGE_DOC
100    );
101}
102
103#[cfg(feature = "stubs")]
104pyo3_stub_gen::define_stub_info_gatherer!(stub_info);
qcs_api_client_common/lib.rs

qcs_api_client_common/
lib.rs
