.. _embedding: Embedding the interpreter ######################### While pybind11 is mainly focused on extending Python using C++, it's also possible to do the reverse: embed the Python interpreter into a C++ program. All of the other documentation pages still apply here, so refer to them for general pybind11 usage. This section will cover a few extra things required for embedding. Getting started =============== A basic executable with an embedded interpreter can be created with just a few lines of CMake and the ``pybind11::embed`` target, as shown below. For more information, see :doc:`/compiling`. .. code-block:: cmake cmake_minimum_required(VERSION 3.4) project(example) find_package(pybind11 REQUIRED) # or `add_subdirectory(pybind11)` add_executable(example main.cpp) target_link_libraries(example PRIVATE pybind11::embed) The essential structure of the ``main.cpp`` file looks like this: .. code-block:: cpp #include // everything needed for embedding namespace py = pybind11; int main() { py::scoped_interpreter guard{}; // start the interpreter and keep it alive py::print("Hello, World!"); // use the Python API } The interpreter must be initialized before using any Python API, which includes all the functions and classes in pybind11. The RAII guard class `scoped_interpreter` takes care of the interpreter lifetime. After the guard is destroyed, the interpreter shuts down and clears its memory. No Python functions can be called after this. Executing Python code ===================== There are a few different ways to run Python code. One option is to use `eval`, `exec` or `eval_file`, as explained in :ref:`eval`. Here is a quick example in the context of an executable with an embedded interpreter: .. code-block:: cpp #include namespace py = pybind11; int main() { py::scoped_interpreter guard{}; py::exec(R"( kwargs = dict(name="World", number=42) message = "Hello, {name}! The answer is {number}".format(**kwargs) print(message) )"); } Alternatively, similar results can be achieved using pybind11's API (see :doc:`/advanced/pycpp/index` for more details). .. code-block:: cpp #include namespace py = pybind11; using namespace py::literals; int main() { py::scoped_interpreter guard{}; auto kwargs = py::dict("name"_a="World", "number"_a=42); auto message = "Hello, {name}! The answer is {number}"_s.format(**kwargs); py::print(message); } The two approaches can also be combined: .. code-block:: cpp #include #include namespace py = pybind11; using namespace py::literals; int main() { py::scoped_interpreter guard{}; auto locals = py::dict("name"_a="World", "number"_a=42); py::exec(R"( message = "Hello, {name}! The answer is {number}".format(**locals()) )", py::globals(), locals); auto message = locals["message"].cast(); std::cout << message; } Importing modules ================= Python modules can be imported using `module_::import()`: .. code-block:: cpp py::module_ sys = py::module_::import("sys"); py::print(sys.attr("path")); For convenience, the current working directory is included in ``sys.path`` when embedding the interpreter. This makes it easy to import local Python files: .. code-block:: python """calc.py located in the working directory""" def add(i, j): return i + j .. code-block:: cpp py::module_ calc = py::module_::import("calc"); py::object result = calc.attr("add")(1, 2); int n = result.cast(); assert(n == 3); Modules can be reloaded using `module_::reload()` if the source is modified e.g. by an external process. This can be useful in scenarios where the application imports a user defined data processing script which needs to be updated after changes by the user. Note that this function does not reload modules recursively. .. _embedding_modules: Adding embedded modules ======================= Embedded binary modules can be added using the `PYBIND11_EMBEDDED_MODULE` macro. Note that the definition must be placed at global scope. They can be imported like any other module. .. code-block:: cpp #include namespace py = pybind11; PYBIND11_EMBEDDED_MODULE(fast_calc, m) { // `m` is a `py::module_` which is used to bind functions and classes m.def("add", [](int i, int j) { return i + j; }); } int main() { py::scoped_interpreter guard{}; auto fast_calc = py::module_::import("fast_calc"); auto result = fast_calc.attr("add")(1, 2).cast(); assert(result == 3); } Unlike extension modules where only a single binary module can be created, on the embedded side an unlimited number of modules can be added using multiple `PYBIND11_EMBEDDED_MODULE` definitions (as long as they have unique names). These modules are added to Python's list of builtins, so they can also be imported in pure Python files loaded by the interpreter. Everything interacts naturally: .. code-block:: python """py_module.py located in the working directory""" import cpp_module a = cpp_module.a b = a + 1 .. code-block:: cpp #include namespace py = pybind11; PYBIND11_EMBEDDED_MODULE(cpp_module, m) { m.attr("a") = 1; } int main() { py::scoped_interpreter guard{}; auto py_module = py::module_::import("py_module"); auto locals = py::dict("fmt"_a="{} + {} = {}", **py_module.attr("__dict__")); assert(locals["a"].cast() == 1); assert(locals["b"].cast() == 2); py::exec(R"( c = a + b message = fmt.format(a, b, c) )", py::globals(), locals); assert(locals["c"].cast() == 3); assert(locals["message"].cast() == "1 + 2 = 3"); } Interpreter lifetime ==================== The Python interpreter shuts down when `scoped_interpreter` is destroyed. After this, creating a new instance will restart the interpreter. Alternatively, the `initialize_interpreter` / `finalize_interpreter` pair of functions can be used to directly set the state at any time. Modules created with pybind11 can be safely re-initialized after the interpreter has been restarted. However, this may not apply to third-party extension modules. The issue is that Python itself cannot completely unload extension modules and there are several caveats with regard to interpreter restarting. In short, not all memory may be freed, either due to Python reference cycles or user-created global data. All the details can be found in the CPython documentation. .. warning:: Creating two concurrent `scoped_interpreter` guards is a fatal error. So is calling `initialize_interpreter` for a second time after the interpreter has already been initialized. Do not use the raw CPython API functions ``Py_Initialize`` and ``Py_Finalize`` as these do not properly handle the lifetime of pybind11's internal data. Sub-interpreter support ======================= Creating multiple copies of `scoped_interpreter` is not possible because it represents the main Python interpreter. Sub-interpreters are something different and they do permit the existence of multiple interpreters. This is an advanced feature of the CPython API and should be handled with care. pybind11 does not currently offer a C++ interface for sub-interpreters, so refer to the CPython documentation for all the details regarding this feature. We'll just mention a couple of caveats the sub-interpreters support in pybind11: 1. Sub-interpreters will not receive independent copies of embedded modules. Instead, these are shared and modifications in one interpreter may be reflected in another. 2. Managing multiple threads, multiple interpreters and the GIL can be challenging and there are several caveats here, even within the pure CPython API (please refer to the Python docs for details). As for pybind11, keep in mind that `gil_scoped_release` and `gil_scoped_acquire` do not take sub-interpreters into account. '>152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 
/****************************************************************************
**
** Copyright (C) 2010 Nokia Corporation and/or its subsidiary(-ies).
** All rights reserved.
**
** Contact: Nokia Corporation (qt-info@nokia.com)
**
** This file is part of a Qt Solutions component.
**
** You may use this file under the terms of the BSD license as follows:
**
** "Redistribution and use in source and binary forms, with or without
** modification, are permitted provided that the following conditions are
** met:
**   * Redistributions of source code must retain the above copyright
**     notice, this list of conditions and the following disclaimer.
**   * Redistributions in binary form must reproduce the above copyright
**     notice, this list of conditions and the following disclaimer in
**     the documentation and/or other materials provided with the
**     distribution.
**   * Neither the name of Nokia Corporation and its Subsidiary(-ies) nor
**     the names of its contributors may be used to endorse or promote
**     products derived from this software without specific prior written
**     permission.
**
** THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
** "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
** LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
** A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
** OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
** SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
** LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
** DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
** THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
** (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
** OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE."
**
****************************************************************************/

#include <QApplication>
#include <QScrollArea>
#include <QGridLayout>
#include <QLabel>
#include <QIcon>
#include <QMap>
#include "qtpropertymanager.h"
#include "qteditorfactory.h"
#include "qttreepropertybrowser.h"
#include "qtbuttonpropertybrowser.h"
#include "qtgroupboxpropertybrowser.h"

int main(int argc, char **argv)
{
    QApplication app(argc, argv);

    QWidget *w = new QWidget();

    QtBoolPropertyManager *boolManager = new QtBoolPropertyManager(w);
    QtIntPropertyManager *intManager = new QtIntPropertyManager(w);
    QtStringPropertyManager *stringManager = new QtStringPropertyManager(w);
    QtSizePropertyManager *sizeManager = new QtSizePropertyManager(w);
    QtRectPropertyManager *rectManager = new QtRectPropertyManager(w);
    QtSizePolicyPropertyManager *sizePolicyManager = new QtSizePolicyPropertyManager(w);
    QtEnumPropertyManager *enumManager = new QtEnumPropertyManager(w);
    QtGroupPropertyManager *groupManager = new QtGroupPropertyManager(w);

    QtProperty *item0 = groupManager->addProperty("QObject");

    QtProperty *item1 = stringManager->addProperty("objectName");
    item0->addSubProperty(item1);

    QtProperty *item2 = boolManager->addProperty("enabled");
    item0->addSubProperty(item2);

    QtProperty *item3 = rectManager->addProperty("geometry");
    item0->addSubProperty(item3);

    QtProperty *item4 = sizePolicyManager->addProperty("sizePolicy");
    item0->addSubProperty(item4);

    QtProperty *item5 = sizeManager->addProperty("sizeIncrement");
    item0->addSubProperty(item5);

    QtProperty *item7 = boolManager->addProperty("mouseTracking");
    item0->addSubProperty(item7);

    QtProperty *item8 = enumManager->addProperty("direction");
    QStringList enumNames;
    enumNames << "Up" << "Right" << "Down" << "Left";
    enumManager->setEnumNames(item8, enumNames);
    QMap<int, QIcon> enumIcons;
    enumIcons[0] = QIcon(":/demo/images/up.png");
    enumIcons[1] = QIcon(":/demo/images/right.png");
    enumIcons[2] = QIcon(":/demo/images/down.png");
    enumIcons[3] = QIcon(":/demo/images/left.png");
    enumManager->setEnumIcons(item8, enumIcons);
    item0->addSubProperty(item8);

    QtProperty *item9 = intManager->addProperty("value");
    intManager->setRange(item9, -100, 100);
    item0->addSubProperty(item9);

    QtCheckBoxFactory *checkBoxFactory = new QtCheckBoxFactory(w);
    QtSpinBoxFactory *spinBoxFactory = new QtSpinBoxFactory(w);
    QtSliderFactory *sliderFactory = new QtSliderFactory(w);
    QtScrollBarFactory *scrollBarFactory = new QtScrollBarFactory(w);
    QtLineEditFactory *lineEditFactory = new QtLineEditFactory(w);
    QtEnumEditorFactory *comboBoxFactory = new QtEnumEditorFactory(w);

    QtAbstractPropertyBrowser *editor1 = new QtTreePropertyBrowser();
    editor1->setFactoryForManager(boolManager, checkBoxFactory);
    editor1->setFactoryForManager(intManager, spinBoxFactory);
    editor1->setFactoryForManager(stringManager, lineEditFactory);
    editor1->setFactoryForManager(sizeManager->subIntPropertyManager(), spinBoxFactory);
    editor1->setFactoryForManager(rectManager->subIntPropertyManager(), spinBoxFactory);
    editor1->setFactoryForManager(sizePolicyManager->subIntPropertyManager(), spinBoxFactory);
    editor1->setFactoryForManager(sizePolicyManager->subEnumPropertyManager(), comboBoxFactory);
    editor1->setFactoryForManager(enumManager, comboBoxFactory);

    editor1->addProperty(item0);

    QtAbstractPropertyBrowser *editor2 = new QtTreePropertyBrowser();
    editor2->addProperty(item0);

    QtAbstractPropertyBrowser *editor3 = new QtGroupBoxPropertyBrowser();
    editor3->setFactoryForManager(boolManager, checkBoxFactory);
    editor3->setFactoryForManager(intManager, spinBoxFactory);
    editor3->setFactoryForManager(stringManager, lineEditFactory);
    editor3->setFactoryForManager(sizeManager->subIntPropertyManager(), spinBoxFactory);
    editor3->setFactoryForManager(rectManager->subIntPropertyManager(), spinBoxFactory);
    editor3->setFactoryForManager(sizePolicyManager->subIntPropertyManager(), spinBoxFactory);
    editor3->setFactoryForManager(sizePolicyManager->subEnumPropertyManager(), comboBoxFactory);
    editor3->setFactoryForManager(enumManager, comboBoxFactory);

    editor3->addProperty(item0);

    QScrollArea *scroll3 = new QScrollArea();
    scroll3->setWidgetResizable(true);
    scroll3->setWidget(editor3);

    QtAbstractPropertyBrowser *editor4 = new QtGroupBoxPropertyBrowser();
    editor4->setFactoryForManager(boolManager, checkBoxFactory);
    editor4->setFactoryForManager(intManager, scrollBarFactory);
    editor4->setFactoryForManager(stringManager, lineEditFactory);
    editor4->setFactoryForManager(sizeManager->subIntPropertyManager(), spinBoxFactory);
    editor4->setFactoryForManager(rectManager->subIntPropertyManager(), spinBoxFactory);
    editor4->setFactoryForManager(sizePolicyManager->subIntPropertyManager(), sliderFactory);
    editor4->setFactoryForManager(sizePolicyManager->subEnumPropertyManager(), comboBoxFactory);
    editor4->setFactoryForManager(enumManager, comboBoxFactory);

    editor4->addProperty(item0);

    QScrollArea *scroll4 = new QScrollArea();
    scroll4->setWidgetResizable(true);
    scroll4->setWidget(editor4);

    QtAbstractPropertyBrowser *editor5 = new QtButtonPropertyBrowser();
    editor5->setFactoryForManager(boolManager, checkBoxFactory);
    editor5->setFactoryForManager(intManager, scrollBarFactory);
    editor5->setFactoryForManager(stringManager, lineEditFactory);
    editor5->setFactoryForManager(sizeManager->subIntPropertyManager(), spinBoxFactory);
    editor5->setFactoryForManager(rectManager->subIntPropertyManager(), spinBoxFactory);
    editor5->setFactoryForManager(sizePolicyManager->subIntPropertyManager(), sliderFactory);
    editor5->setFactoryForManager(sizePolicyManager->subEnumPropertyManager(), comboBoxFactory);
    editor5->setFactoryForManager(enumManager, comboBoxFactory);

    editor5->addProperty(item0);

    QScrollArea *scroll5 = new QScrollArea();
    scroll5->setWidgetResizable(true);
    scroll5->setWidget(editor5);

    QGridLayout *layout = new QGridLayout(w);
    QLabel *label1 = new QLabel("Editable Tree Property Browser");
    QLabel *label2 = new QLabel("Read Only Tree Property Browser, editor factories are not set");
    QLabel *label3 = new QLabel("Group Box Property Browser");
    QLabel *label4 = new QLabel("Group Box Property Browser with different editor factories");
    QLabel *label5 = new QLabel("Button Property Browser");
    label1->setWordWrap(true);
    label2->setWordWrap(true);
    label3->setWordWrap(true);
    label4->setWordWrap(true);
    label5->setWordWrap(true);
    label1->setFrameShadow(QFrame::Sunken);
    label2->setFrameShadow(QFrame::Sunken);
    label3->setFrameShadow(QFrame::Sunken);
    label4->setFrameShadow(QFrame::Sunken);
    label5->setFrameShadow(QFrame::Sunken);
    label1->setFrameShape(QFrame::Panel);
    label2->setFrameShape(QFrame::Panel);
    label3->setFrameShape(QFrame::Panel);
    label4->setFrameShape(QFrame::Panel);
    label5->setFrameShape(QFrame::Panel);
    label1->setAlignment(Qt::AlignCenter);
    label2->setAlignment(Qt::AlignCenter);
    label3->setAlignment(Qt::AlignCenter);
    label4->setAlignment(Qt::AlignCenter);
    label5->setAlignment(Qt::AlignCenter);

    layout->addWidget(label1, 0, 0);
    layout->addWidget(label2, 0, 1);
    layout->addWidget(label3, 0, 2);
    layout->addWidget(label4, 0, 3);
    layout->addWidget(label5, 0, 4);
    layout->addWidget(editor1, 1, 0);
    layout->addWidget(editor2, 1, 1);
    layout->addWidget(scroll3, 1, 2);
    layout->addWidget(scroll4, 1, 3);
    layout->addWidget(scroll5, 1, 4);
    w->show();

    int ret = app.exec();
    delete w;
    return ret;
}
generated by cgit v1.2.3 (git 2.25.1) at 2025-06-03 01:12:52 +0000