<commit_before>.. _qipy-tutorial:

Using Python with qibuild projects
===================================


Introduction
------------


Let's say you have a C++ library in a qibuild project, called ``foo``.

.. code-block:: console

    <worktree>
    |__ foo
        |__ qiproject.xml
        |__ CMakeLists.txt
        |__ foo.cpp
        |__ foo.hpp

.. code-block:: cmake

    # in <worktree>/foo/CMakeLists.txt
    project(foo)
    find_package(qibuild)

    qi_create_lib(SHARED foo foo.hpp foo.cpp)

.. code-block:: xml

    <!-- in <worktree>/foo/qiproject.xml -->
    <project version="3">
      <qibuild name="foo" />
    </project>

You wish to write a C++ Python extension in another project to wrap the
``foo`` library, using the qibuild build system. Let's say you use swig for
this.

You have an interface file for swig called ``pyfoo.i`` which is going
to generate a ``_pyfoo.so`` Python extension, and a ``foo.py`` to wrap
the C++ extension.

.. code-block:: console

    <worktree>
    |__ foo
        |__ qiproject.xml
        |__ CMakeLists.txt
        |__ foo.cpp
        |__ foo.hpp
    |__ pyfoo
        |__ qiproject.xml
        |__ CMakeLists.txt
        |__ pyfoo.i
        |__ foo.py
        |__ foo_script.py

.. code-block:: xml

    <!-- in pyfoo/qiproject.xml -->
    <project version="3">
      <qibuild name="pyfoo">
        <depends runtime="true" buildtime="true" names="foo" />
      </qibuild>
      <qipy name="pyfoo" />
    </project>

.. code-block:: cmake

    # in <worktree>/foo-py/CMakeLists.txt
    project(pyfoo)

    qi_swig_python(_pyfoo pyfoo.i DEPENDS FOO)

.. code-block:: cpp

    // In pyfoo.i
    %module _pyfoo

    %{
    #include "foo.hpp"
    %}

    %include "foo.hpp"

.. code-block:: py

    # In foo.py

    import _pyfoo

    ...

    # In foo_script.py
    import foo
<commit_msg>doc: fix bad tag in qipy tutorial<commit_after>.. _qipy-tutorial:

Using Python with qibuild projects
===================================


Introduction
------------


Let's say you have a C++ library in a qibuild project, called ``foo``.

.. code-block:: console

    <worktree>
    |__ foo
        |__ qiproject.xml
        |__ CMakeLists.txt
        |__ foo.cpp
        |__ foo.hpp

.. code-block:: cmake

    # in <worktree>/foo/CMakeLists.txt
    project(foo)
    find_package(qibuild)

    qi_create_lib(SHARED foo foo.hpp foo.cpp)

.. code-block:: xml

    <!-- in <worktree>/foo/qiproject.xml -->
    <project version="3">
      <qibuild name="foo" />
    </project>

You wish to write a C++ Python extension in another project to wrap the
``foo`` library, using the qibuild build system. Let's say you use swig for
this.

You have an interface file for swig called ``pyfoo.i`` which is going
to generate a ``_pyfoo.so`` Python extension, and a ``foo.py`` to wrap
the C++ extension.

.. code-block:: console

    <worktree>
    |__ foo
        |__ qiproject.xml
        |__ CMakeLists.txt
        |__ foo.cpp
        |__ foo.hpp
    |__ pyfoo
        |__ qiproject.xml
        |__ CMakeLists.txt
        |__ pyfoo.i
        |__ foo.py
        |__ foo_script.py

.. code-block:: xml

    <!-- in pyfoo/qiproject.xml -->
    <project version="3">
      <qibuild name="pyfoo">
        <depends runtime="true" buildtime="true" names="foo" />
      </qibuild>
      <qipython name="pyfoo" />
    </project>

.. code-block:: cmake

    # in <worktree>/foo-py/CMakeLists.txt
    project(pyfoo)

    qi_swig_python(_pyfoo pyfoo.i DEPENDS FOO)

.. code-block:: cpp

    // In pyfoo.i
    %module _pyfoo

    %{
    #include "foo.hpp"
    %}

    %include "foo.hpp"

.. code-block:: py

    # In foo.py

    import _pyfoo

    ...

    # In foo_script.py
    import foo

{'fraction_non_alphanumeric': 0.15274784482758622, 'fraction_numerical': 0.0010775862068965517, 'mean_word_length': 2.170794192997438, 'pattern_counts': {'":': 0, '<': 35, '<?xml version=': 0, '>': 35, 'https://': 0, 'lorem ipsum': 0, 'www.': 0, 'xml': 14}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 0, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '6799115', 'n_tokens_mistral': 1337, 'n_tokens_neox': 1272, 'n_words': 328}