🎨🐍 Streamline Python bindings

[denialhaag]

Description

This PR aligns the implementation of Python bindings with the implementation introduced in qmap#624. To this end, a helper function add_mqt_core_binding is introduced.

Checklist:

• The pull request only contains commits that are focused and relevant to this change.
• I have added appropriate tests that cover the new/changed functionality.
• I have updated the documentation to reflect these changes.
• I have added entries to the changelog for any noteworthy additions, changes, fixes or removals.
• I have added migration instructions to the upgrade guide (if needed).
• The changes follow the project's style guidelines and introduce no new warnings.
• The changes are fully tested and pass the CI checks.
• I have reviewed my own code changes.

[ystade]

@denialhaag I assume that is all still a work in progress. When you have a state where it makes sense to have a look, feel free to request a review from me before you request it from @burgholzer as the restructuring in QMAP was initiated by me in #624. Also, feel free to reach out if you have any questions.

[denialhaag]

@ystade, yes, this is very much still work in progress. I'll let you know if I have any questions. Thanks! :)

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.

📢 Thoughts on this report? Let us know!

[ystade]

@denialhaag I just pushed a commit that may solve the linter issue, let's see what the CI says.

[ystade]

Besides the comments that will be included in the review, I have one comment that I could not put in the review.

@burgholzer added the following file

core/include/mqt-core/python/pybind11.hpp

Lines 1 to 22 in 643a18f

	/*
	* Copyright (c) 2023 - 2025 Chair for Design Automation, TUM
	* Copyright (c) 2025 Munich Quantum Software Company GmbH
	* All rights reserved.
	*
	* SPDX-License-Identifier: MIT
	*
	* Licensed under the MIT License
	*/
	// This file must be the first include for any bindings code.
	#pragma once
	#include <pybind11/pybind11.h> // IWYU pragma: export
	#include <pybind11/stl.h> // IWYU pragma: export
	namespace mqt {
	namespace py = pybind11;
	using namespace py::literals;
	} // namespace mqt

This did not exist in MQT QMAP when I restructured the bindings. The state right now feels not quite satisfactory as the source files are now clearly separated into src/ and bindings/ but the header files are still mixed in the include/ directory. I would argue that the only Python header is superfluous and the few lines can be added to every C++ source file defining a Python module. However, @burgholzer had surely some good motivation to create this header, so maybe he can give his thoughts on that issue.

[burgholzer]

Besides the comments that will be included in the review, I have one comment that I could not put in the review.

@burgholzer added the following file

core/include/mqt-core/python/pybind11.hpp

Lines 1 to 22 in 643a18f

	/*
	* Copyright (c) 2023 - 2025 Chair for Design Automation, TUM
	* Copyright (c) 2025 Munich Quantum Software Company GmbH
	* All rights reserved.
	*
	* SPDX-License-Identifier: MIT
	*
	* Licensed under the MIT License
	*/
	// This file must be the first include for any bindings code.
	#pragma once
	#include <pybind11/pybind11.h> // IWYU pragma: export
	#include <pybind11/stl.h> // IWYU pragma: export
	namespace mqt {
	namespace py = pybind11;
	using namespace py::literals;
	} // namespace mqt

This did not exist in MQT QMAP when I restructured the bindings. The state right now feels not quite satisfactory as the source files are now clearly separated into src/ and bindings/ but the header files are still mixed in the include/ directory. I would argue that the only Python header is superfluous and the few lines can be added to every C++ source file defining a Python module. However, @burgholzer had surely some good motivation to create this header, so maybe he can give his thoughts on that issue.

The main motivation was that these includes always need to come first in order for the STL bindings to work as expected. The common header makes that fairly easy to enforce.
Given that there is a limited amount of bindings files in this project, I would be fine with eliminating the header and adding the appropriate includes (including a comment stating that these need to come first) to every file that needs them.

[ystade]

Thanks @denialhaag for your work on this. This looks already very good and clean. I added very few comments and one reminder within the code. After those comments are resolved, I think this PR is ready to be reviewed again by @burgholzer .

[ystade]

@denialhaag One more thing, I am quite certain that the last commits did not trigger the full CI, esp. the C++ Linting since only config files were changed. Can you either introduce some dummy change to some C++ file to trigger the entire CI again (the change can be reverted after the CI has finished) or you manually run the CI workflow under Actions/CI/run workflow on this branch? However, this must be done in your forked repository.

In general, since you have the permissions now, I think for the future it is more convenient if you just work directly in this repo without forking it but this is really no big issue.

[denialhaag]

Besides the comments that will be included in the review, I have one comment that I could not put in the review.
@burgholzer added the following file

core/include/mqt-core/python/pybind11.hpp

Lines 1 to 22 in 643a18f

	/*
	* Copyright (c) 2023 - 2025 Chair for Design Automation, TUM
	* Copyright (c) 2025 Munich Quantum Software Company GmbH
	* All rights reserved.
	*
	* SPDX-License-Identifier: MIT
	*
	* Licensed under the MIT License
	*/
	// This file must be the first include for any bindings code.
	#pragma once
	#include <pybind11/pybind11.h> // IWYU pragma: export
	#include <pybind11/stl.h> // IWYU pragma: export
	namespace mqt {
	namespace py = pybind11;
	using namespace py::literals;
	} // namespace mqt

This did not exist in MQT QMAP when I restructured the bindings. The state right now feels not quite satisfactory as the source files are now clearly separated into src/ and bindings/ but the header files are still mixed in the include/ directory. I would argue that the only Python header is superfluous and the few lines can be added to every C++ source file defining a Python module. However, @burgholzer had surely some good motivation to create this header, so maybe he can give his thoughts on that issue.

The main motivation was that these includes always need to come first in order for the STL bindings to work as expected. The common header makes that fairly easy to enforce. Given that there is a limited amount of bindings files in this project, I would be fine with eliminating the header and adding the appropriate includes (including a comment stating that these need to come first) to every file that needs them.

I removed pybind11.hpp. Let me know if this is what you had in mind.

[denialhaag]

Undo these changes before merging.

[burgholzer]

Hey @denialhaag 👋🏼
Many thanks for your work on this! I just did a fairly quick review of the whole PR to keep moving this forward. Nothing really critical, so this should hopefully be easy to address. Otherwise, this is looking really good already and should be done "soon".

[burgholzer]

LGTM 👍🏼 Let's get this in now, to not create too many conflicts with other ongoing PRs.
Thanks for your work on this!