DunePythonCommonMacros
----------------------

Main entry point for the Python extension of the DUNE CMake build system.

This module detects the Python installation, sets up Python-related helper
targets, configures the DUNE Python virtual environment, and includes the
helper modules that implement package installation and Python-based tests.

To disable all Python-related functionality, configure with
``-DCMAKE_DISABLE_FIND_PACKAGE_Python3=TRUE``.

If you use DUNE modules that provide Python functionality, keep in mind:

* CMake discovers the Python interpreter during configuration. Activate any
  desired virtual environment before configuring.
* Each module gets an ``install_python`` target for Python packages, and that
  installation is also part of ``make install``.
* Configure-time virtual environment management is provided by
  :doc:`DunePythonVirtualenv`.

After this module has run, Python-related configuration variables such as the
interpreter discovery results and ``DUNE_PYTHON_SYSTEM_IS_VIRTUALENV`` are
available to downstream modules.

.. cmake:variable:: DUNE_PYTHON_INSTALL_LOCATION

  Control where DUNE installs Python packages. Supported values are:

  * ``user`` for installation through ``pip --user``. This is incompatible
    with virtual environments.
  * ``system`` for installation into the standard paths of the interpreter
    found by CMake.
  * ``none`` to disable package installation.
  * ``--target <path>`` to forward a custom target directory to pip.

  The default depends on whether the selected interpreter already runs inside a
  virtual environment. In that case ``system`` is used, otherwise ``user`` is
  selected.