23304525254

Committed 19 Mar 2026 04:09PM UTC coverage: 87.346% (+0.04%) from 87.309%

Build # 23304525254

Build Type

Pull #15361

github

Committed by

web-flow

Commit Message

Merge 52d8c7053 into 13b23a355

Pull Request Pull Request #15361: Add `qk_circuit_draw` function to the C API

Coverage Stats

15 of 17 new or added lines in 2 files covered. (88.24%)

102 existing lines in 7 files now uncovered.

103313 of 118280 relevant lines covered (87.35%)

1137052.73 hits per line

Source File
Press 'n' to go to next uncovered line, 'b' for previous

76.15

/crates/qpy/src/annotations.rs

// This code is part of Qiskit.
//
// (C) Copyright IBM 2025
//
// This code is licensed under the Apache License, Version 2.0. You may
// obtain a copy of this license in the LICENSE.txt file in the root directory
// of this source tree or at https://www.apache.org/licenses/LICENSE-2.0.
//
// Any modifications or derivative works of this code must retain this
// copyright notice, and modified files need to carry a notice indicating
// that they have been altered from the originals.
use crate::bytes::Bytes;
use crate::error::QpyError;
use hashbrown::HashMap;
use pyo3::prelude::*;
use pyo3::types::{PyDict, PyIterator, PyNotImplemented};
/// The purpose of AnnotationHandler is to keep track of all the annotation serializers/deserializers at once.
/// Each namespace has one potential serializer/deserializer corresponding to it, given in the factories list.
/// When serializing the first time a namespace is encountered, the serializer is generated from the factory,
/// but it remains inside `potential_serializers` as long as it did not manage to serialize any annotation.
/// The way to determine whether a serialization attempt succeeded is to check whether the result of `dump_annotation`
/// was `NotImplemented`.

#[derive(Debug)]
pub struct AnnotationHandler<'a> {
    pub annotation_factories: &'a Bound<'a, PyDict>,
    factories: HashMap<String, Py<PyAny>>,
    pub serializers: HashMap<String, (usize, Py<PyAny>)>,
    potential_serializers: HashMap<String, Py<PyAny>>,
    pub deserializers: Vec<Py<PyAny>>,
}

impl<'a> AnnotationHandler<'a> {
    pub fn new(annotation_factories: &'a Bound<'a, PyDict>) -> Self {
        let mut factories = HashMap::with_capacity(annotation_factories.len());
        for (key, value) in annotation_factories.iter() {
            if let Ok(key_string) = key.extract() {
                // we ignore non-string keys since they will not be invoked during serialization
                // where we choose serializer according to the namespace string
                factories.insert(key_string, value.clone().unbind());
            }
        }

        let serializers = HashMap::new();
        let potential_serializers = HashMap::new();
        // deserializers are created on demand based on the QPY annotation headers
        let deserializers = Vec::new();
        AnnotationHandler {
            annotation_factories,
            factories,
            serializers,
            potential_serializers,
            deserializers,
        }
    }
    pub fn serialize(&mut self, annotation: &Py<PyAny>) -> Result<(u32, Bytes), QpyError> {
        Python::attach(|py| {
            let annotation_namespace: String = annotation.getattr(py, "namespace")?.extract(py)?;
            let annotation_module = py.import("qiskit.circuit.annotation")?;
            let namespace_iter_func = annotation_module.getattr("iter_namespaces")?;
            let namespace_iter =
                PyIterator::from_object(&namespace_iter_func.call1((&annotation_namespace,))?)?;
            for namespace_res in namespace_iter {
                let namespace = namespace_res?;
                let namespace_string: String = namespace.clone().extract()?;
                // first check for an active serializer
                if let Some((index, serializer)) = self.serializers.get(&namespace_string) {
                    let result = serializer.call_method1(
                        py,
                        "dump_annotation",
                        (namespace.clone(), annotation),
                    )?;
                    if !result.is(PyNotImplemented::get(py)) {
                        let result_bytes: Bytes = result.extract(py)?;
                        return Ok((*index as u32, result_bytes));
                    }
                } else if let Some(serializer) = self.potential_serializers.get(&namespace_string) {
                    let result = serializer.call_method1(
                        py,
                        "dump_annotation",
                        (namespace.clone(), annotation),
                    )?;
                    if !result.is(PyNotImplemented::get(py)) {
                        let index = self.serializers.len();
                        let result_bytes: Bytes = result.extract(py)?;
                        self.serializers
                            .insert(namespace_string.clone(), (index, serializer.clone()));
                        return Ok((index as u32, result_bytes));
                    }
                }
                // no serializer, let's try to create one from the corresponding factory
                else if let Some(factory) = self.factories.get(&namespace_string) {
                    let serializer = factory.call0(py)?;
                    let result = serializer.call_method1(
                        py,
                        "dump_annotation",
                        (namespace.clone(), annotation),
                    )?;
                    if !result.is(PyNotImplemented::get(py)) {
                        let index = self.serializers.len();
                        let result_bytes: Bytes = result.extract(py)?;
                        self.serializers
                            .insert(namespace_string.clone(), (index, serializer));
                        return Ok((index as u32, result_bytes));
                    } else {
                        // This time the serializer failed, but we might want to try it again without
                        // having to reconstruct it from the factory
                        self.potential_serializers
                            .insert(namespace_string.clone(), serializer);
                    }
                }
            }
            Err(QpyError::AnnotationError(format!(
                "No configured annotation serializer could handle {}",
                annotation.bind(py).repr()?,
            )))
        })
    }

    pub fn load(&self, index: u32, payload: Bytes) -> Result<Py<PyAny>, QpyError> {
        if let Some(deserializer) = self.deserializers.get(index as usize) {
            Python::attach(|py| -> Result<Py<PyAny>, QpyError> {
                Ok(deserializer.call_method1(py, "load_annotation", (payload,))?)
            })
        } else {
            Err(QpyError::ConversionError(format!(
                "Annotation deserializer index {:?} out of range (0...{:?}), is too large and would overflow",
                index,
                self.deserializers.len()
            )))
        }
    }

    pub fn dump_serializers(&self) -> Result<Vec<(String, Bytes)>, QpyError> {
        // we need to be a little careful to keep the result sorted by index order
        let mut result: Vec<Option<(String, Bytes)>> = vec![None; self.serializers.len()];
        Python::attach(|py| -> Result<(), QpyError> {
            for (namespace, (index, serializer)) in &self.serializers {
                let state: Bytes = serializer.call_method0(py, "dump_state")?.extract(py)?;
                result[*index] = Some((namespace.clone(), state));
            }
            Ok(())
        })?;
        Ok(result.into_iter().flatten().collect())
    }

    pub fn load_deserializers(&mut self, data: Vec<(String, Bytes)>) -> Result<(), QpyError> {
        Python::attach(|py| -> Result<(), QpyError> {
            for (namespace, state) in data {
                if let Some(factory) = self.factories.get(&namespace) {
                    let serializer = factory.call0(py)?;
                    serializer.call_method1(
                        py,
                        "load_state",
                        (namespace.clone(), state.clone()),
                    )?;
                    self.deserializers.push(serializer);
                };
            }
            Ok(())
        })?;
        Ok(())
    }
}

1	// This code is part of Qiskit.
2	//
3	// (C) Copyright IBM 2025
4	//
5	// This code is licensed under the Apache License, Version 2.0. You may
6	// obtain a copy of this license in the LICENSE.txt file in the root directory
7	// of this source tree or at https://www.apache.org/licenses/LICENSE-2.0.
8	//
9	// Any modifications or derivative works of this code must retain this
10	// copyright notice, and modified files need to carry a notice indicating
11	// that they have been altered from the originals.
12	use crate::bytes::Bytes;
13	use crate::error::QpyError;
14	use hashbrown::HashMap;
15	use pyo3::prelude::*;
16	use pyo3::types::{PyDict, PyIterator, PyNotImplemented};
17	/// The purpose of AnnotationHandler is to keep track of all the annotation serializers/deserializers at once.
18	/// Each namespace has one potential serializer/deserializer corresponding to it, given in the factories list.
19	/// When serializing the first time a namespace is encountered, the serializer is generated from the factory,
20	/// but it remains inside `potential_serializers` as long as it did not manage to serialize any annotation.
21	/// The way to determine whether a serialization attempt succeeded is to check whether the result of `dump_annotation`
22	/// was `NotImplemented`.
23
24	#[derive(Debug)]
25	pub struct AnnotationHandler<'a> {
26	pub annotation_factories: &'a Bound<'a, PyDict>,
27	factories: HashMap<String, Py<PyAny>>,
28	pub serializers: HashMap<String, (usize, Py<PyAny>)>,
29	potential_serializers: HashMap<String, Py<PyAny>>,
30	pub deserializers: Vec<Py<PyAny>>,
31	}
32
33	impl<'a> AnnotationHandler<'a> {
34	pub fn new(annotation_factories: &'a Bound<'a, PyDict>) -> Self {	3,968✔
35	let mut factories = HashMap::with_capacity(annotation_factories.len());	3,968✔
36	for (key, value) in annotation_factories.iter() {	3,968✔
37	if let Ok(key_string) = key.extract() {	96✔
38	// we ignore non-string keys since they will not be invoked during serialization	96✔
39	// where we choose serializer according to the namespace string	96✔
40	factories.insert(key_string, value.clone().unbind());	96✔
41	}	96✔
42	}
43
44	let serializers = HashMap::new();	3,968✔
45	let potential_serializers = HashMap::new();	3,968✔
46	// deserializers are created on demand based on the QPY annotation headers
47	let deserializers = Vec::new();	3,968✔
48	AnnotationHandler {	3,968✔
49	annotation_factories,	3,968✔
50	factories,	3,968✔
51	serializers,	3,968✔
52	potential_serializers,	3,968✔
53	deserializers,	3,968✔
54	}	3,968✔
55	}	3,968✔
56	pub fn serialize(&mut self, annotation: &Py<PyAny>) -> Result<(u32, Bytes), QpyError> {	38✔
57	Python::attach(\|py\| {	38✔
58	let annotation_namespace: String = annotation.getattr(py, "namespace")?.extract(py)?;	38✔
59	let annotation_module = py.import("qiskit.circuit.annotation")?;	38✔
60	let namespace_iter_func = annotation_module.getattr("iter_namespaces")?;	38✔
61	let namespace_iter =	38✔
62	PyIterator::from_object(&namespace_iter_func.call1((&annotation_namespace,))?)?;	38✔
63	for namespace_res in namespace_iter {	52✔
64	let namespace = namespace_res?;	52✔
65	let namespace_string: String = namespace.clone().extract()?;	52✔
66	// first check for an active serializer
67	if let Some((index, serializer)) = self.serializers.get(&namespace_string) {	52✔
68	let result = serializer.call_method1(	12✔
69	py,	12✔
70	"dump_annotation",
71	(namespace.clone(), annotation),	12✔
72	)?;	×
73	if !result.is(PyNotImplemented::get(py)) {	12✔
74	let result_bytes: Bytes = result.extract(py)?;	10✔
75	return Ok((*index as u32, result_bytes));	10✔
76	}	2✔
77	} else if let Some(serializer) = self.potential_serializers.get(&namespace_string) {	40✔
78	let result = serializer.call_method1(	×
79	py,	×
80	"dump_annotation",
81	(namespace.clone(), annotation),	×
82	)?;	×
83	if !result.is(PyNotImplemented::get(py)) {	×
84	let index = self.serializers.len();	×
85	let result_bytes: Bytes = result.extract(py)?;	×
86	self.serializers	×
87	.insert(namespace_string.clone(), (index, serializer.clone()));	×
88	return Ok((index as u32, result_bytes));	×
89	}	×
90	}
91	// no serializer, let's try to create one from the corresponding factory
92	else if let Some(factory) = self.factories.get(&namespace_string) {	40✔
93	let serializer = factory.call0(py)?;	26✔
94	let result = serializer.call_method1(	26✔
95	py,	26✔
96	"dump_annotation",
97	(namespace.clone(), annotation),	26✔
98	)?;	×
99	if !result.is(PyNotImplemented::get(py)) {	26✔
100	let index = self.serializers.len();	26✔
101	let result_bytes: Bytes = result.extract(py)?;	26✔
102	self.serializers	26✔
103	.insert(namespace_string.clone(), (index, serializer));	26✔
104	return Ok((index as u32, result_bytes));	26✔
105	} else {	×
106	// This time the serializer failed, but we might want to try it again without	×
107	// having to reconstruct it from the factory	×
108	self.potential_serializers	×
109	.insert(namespace_string.clone(), serializer);	×
110	}	×
111	}	14✔
112	}
113	Err(QpyError::AnnotationError(format!(	2✔
114	"No configured annotation serializer could handle {}",
115	annotation.bind(py).repr()?,	2✔
116	)))
117	})	38✔
118	}	38✔
119
120	pub fn load(&self, index: u32, payload: Bytes) -> Result<Py<PyAny>, QpyError> {	36✔
121	if let Some(deserializer) = self.deserializers.get(index as usize) {	36✔
122	Python::attach(\|py\| -> Result<Py<PyAny>, QpyError> {	36✔
123	Ok(deserializer.call_method1(py, "load_annotation", (payload,))?)	36✔
124	})	36✔
125	} else {
126	Err(QpyError::ConversionError(format!(	×
127	"Annotation deserializer index {:?} out of range (0...{:?}), is too large and would overflow",	×
UNCOV 128	index,	×
129	self.deserializers.len()	×
UNCOV 130	)))	×
131	}
132	}	36✔
133
134	pub fn dump_serializers(&self) -> Result<Vec<(String, Bytes)>, QpyError> {	1,958✔
135	// we need to be a little careful to keep the result sorted by index order
136	let mut result: Vec<Option<(String, Bytes)>> = vec![None; self.serializers.len()];	1,958✔
137	Python::attach(\|py\| -> Result<(), QpyError> {	1,958✔
138	for (namespace, (index, serializer)) in &self.serializers {	1,958✔
139	let state: Bytes = serializer.call_method0(py, "dump_state")?.extract(py)?;	26✔
140	result[*index] = Some((namespace.clone(), state));	26✔
141	}
142	Ok(())	1,958✔
143	})?;	1,958✔
144	Ok(result.into_iter().flatten().collect())	1,958✔
145	}	1,958✔
146
147	pub fn load_deserializers(&mut self, data: Vec<(String, Bytes)>) -> Result<(), QpyError> {	1,532✔
148	Python::attach(\|py\| -> Result<(), QpyError> {	1,532✔
149	for (namespace, state) in data {	1,532✔
150	if let Some(factory) = self.factories.get(&namespace) {	26✔
151	let serializer = factory.call0(py)?;	26✔
152	serializer.call_method1(	26✔
153	py,	26✔
154	"load_state",
155	(namespace.clone(), state.clone()),	26✔
UNCOV 156	)?;	×
157	self.deserializers.push(serializer);	26✔
UNCOV 158	};	×
159	}
160	Ok(())	1,532✔
161	})?;	1,532✔
162	Ok(())	1,532✔
163	}	1,532✔
164	}

Qiskit / qiskit / 23304525254

Source File Press 'n' to go to next uncovered line, 'b' for previous

Source File
Press 'n' to go to next uncovered line, 'b' for previous