Qiskit / qiskit / 23197589083

87%

main: 87%

Build Type

push

github

Committed by web-flow

Commit Message

Add `QkCircuit` C/Python interoperation via `QuantumCircuit._data` (#15767)

We previously had a `qk_circuit_to_python` method that returned a
complete `QuantumCircuit`, though without the stable C extension module
mode, this was only practically useful for testing via `ctypes` in our
unit tests.

This is a breaking change that explicitly makes the C/Python conversion
type the direct Python-space `CircuitData` handle, and documents a path
to retrieving this from `QuantumCircuit`, replacing the old method with
`qk_circuit_to_python_full` (which in practice is likely to be the only
useful call in the near future).

This is necessary because the `qk_circuit_borrow_from_python` method
cannot safely take a `QuantumCircuit` in a `PyObject *`, because we
would need to extract a _new_ Python reference to `QuantumCircuit._data`
internally, and then either _leak_ the refcount of that or risk Python
garbage-collecting it out from underneath us if another thread/worker
were to reassign the outer `QuantumCircuit._data`.

The documentation of `QuantumCircuit._data` deliberately and explicitly
makes _all_ features of the attribute private except for the ability to
pass it to C-API functions expecting "Python handle to `QkCircuit`".
This specifically does not preclude a hypothetical unification of
`PyCircuitData` and `QuantumCircuit` in the future; we will be able to
maintain backwards compatibility if that comes to pass by simply having
`QuantumCircuit._data` return itself.

Run Details

8 of 70 new or added lines in 2 files covered. (11.43%)

19 existing lines in 6 files now uncovered.

101154 of 115626 relevant lines covered (87.48%)

1168545.39 hits per line