Add auto-generated ctypes bindings to C API (#16067)

* Add auto-generated `ctypes` bindings to C API

This is similar to how Python exposes its own C API through `ctypes` as
`ctypes.pythonapi`.  It's unlikely to be immediately useful as a feature
for downstream users, but it simplifies the process of us testing our
own code from Python space.

I had originally hoped / thought that `numba` would support calling
these `ctypes` functions, but while `numba` (as of current version 0.65)
does have support for calling `ctypes` functions defined purely in terms
of primitive non-pointer integral types, it doesn't yet support
`ctypes.py_object` or arbitrary pointers.

* Remove unnecessary fast path

Author: jakelishman

.gitignore

@@ -20,6 +20,7 @@ __pycache__/
 *.so
 # Generated C header files included in package.
 /qiskit/capi/include
+/qiskit/capi/_ctypes.py
 
 # Distribution / packaging
 .Python

Cargo.lock

@@ -16,3 +16,4 @@ name = "qiskit_bindgen"
 anyhow.workspace = true
 cbindgen  = { workspace = true, features = ["unstable_ir"] }
 hashbrown.workspace = true
+regex.version = "1.12"

crates/bindgen/Cargo.toml

@@ -48,18 +48,31 @@ pub static PYTHON_BINDING_FEATURE: &str = "python_binding";
 pub static PYTHON_BINDING_DEFINE: &str = "QISKIT_C_PYTHON_INTERFACE";
 
 pub static COPYRIGHT: &str = "\
-// This code is part of Qiskit.
-//
-// (C) Copyright IBM 2026
-//
-// 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.
+This code is part of Qiskit.
+
+(C) Copyright IBM 2026
+
+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.
 ";
+pub fn copyright_with_line_comments(comment: &str) -> String {
+    use std::fmt::Write;
+
+    let mut out = String::new();
+    for line in COPYRIGHT.lines() {
+        if line.is_empty() {
+            _ = writeln!(out, "{comment}");
+        } else {
+            _ = writeln!(out, "{comment} {line}");
+        }
+    }
+    out
+}
 
 /// Crates that contain definitions of objects that are exposed through the C API.
 pub static QISKIT_PUBLIC_API_CRATES: &[&str] =
@@ -182,7 +195,7 @@ fn get_config() -> anyhow::Result<cbindgen::Config> {
         .map(|&(cfg, def)| (format!("feature = {cfg}"), String::from(def)))
         .collect();
     Ok(cbindgen::Config {
-        header: Some(COPYRIGHT.to_owned()),
+        header: Some(copyright_with_line_comments("//")),
         language: cbindgen::Language::C,
         includes,
         include_version: true,

crates/bindgen/src/lib.rs

@@ -11,3 +11,4 @@
 // that they have been altered from the originals.
 
 pub mod c;
+pub mod py_ctypes;