# PythonQt

[![License](https://img.shields.io/github/license/mevislab/pythonqt.svg?color=blue)](LICENSE)

PythonQt is a dynamic [Python](https://www.python.org) binding for [Qt](https://www.qt.io).
It offers an easy way to embed the Python scripting language into
your Qt applications.

# Documentation

API documentation is available at: https://mevislab.github.io/pythonqt

# Licensing

PythonQt is distributed under the `LGPL 2.1` license.

## Licensing of Generator

The build system of PythonQt makes use of a patched version of the LGPL'ed QtScript
generator, located in the `generator` directory.

See the `LICENSE.LGPL` file in the generator subdirectory for details.
Copyright (C) 2009 Nokia Corporation and/or its subsidiary(-ies)

See https://code.qt.io/cgit/qt-labs/qtscriptgenerator.git for the original project.
The PythonQt wrappers generated by the generator are distributed under the `LGPL`
as well.

The integrated preprocessor has been replaced with code from the simplecpp project,
see https://github.com/danmar/simplecpp. It is licensed under the `0BSDL` license,
see the `LICENSE` file in the generator/simplecpp directory.
Copyright (C) 2016-2023 simplecpp team

Wrappers are **not** shipped pre-generated. You must run the generator to
create wrappers for your Qt version. The repository may keep a
single example tree (e.g., `generated_cpp_515`) only as a reference.

# Building

## General

Building PythonQt requires a couple of steps.
Follow these instructions in order to get a correctly built PythonQt runtime and Qt bindings.

### Environment

First, you need to set a couple of environment variables, which depend on your Python and Qt installation.

- `PYTHON_VERSION`

  Set the version of your Python interpreter. The syntax is `<major>.<minor>`, e.g., `3.10`.

- `PYTHON_PATH`

  This is the absolute path to the root directory of your Python installation.

- `PYTHON_LIB`

  The absolute path to the `libs` directory in your python installation `$PYTHON_PATH/libs`.

- `PYTHON_DIR`

  The `PYTHON_DIR` is required for non-Windows installations to find the `python-config` executable.
  This should have the same value as `PYTHON_PATH`.

- `QTDIR`

  The absolute path to the root directory of your Qt installation.

### Binding Generator

1. Configure the generator at the top level

   ```bash
   qmake CONFIG+=generator_only CONFIG+=Release PythonQt.pro
   ```

2. Build the generator

   Use `nmake` for MSVC (Visual Studio; make sure to have the environment variables set for Visual Studio beforehand). Otherwise, use `make`.

3. Generate the bindings

   Use the generator executable from step 2 to generate the bindings.
   The location of the generator executable can vary depending on your platform (the subdirectory is named after the current configuration, e.g., `release`).
   On Windows, the generator is named `pythonqt_generator.exe`; on all other platforms, it is named `pythonqt_generator`.

   ```bash
   <generator-executable> qtscript_masterinclude.h build_all.txt
   ```


**Output location:** by default the generator emits to `../generated_cpp`
(relative to the build). You can override this with:

```bash
qmake PYTHONQT_GENERATED_PATH=/abs/path/to/generated_cpp
```

#### qmake toggles (optional)

* `CONFIG+=generator_only`: build only the wrapper generator.
* `CONFIG+=exclude_generator`: build everything **except** the generator.

Use these to (1) build the generator, (2) run it to produce `generated_cpp`, then (3) build the rest without rebuilding the generator.


### PythonQt Runtime

Next, build the runtime (and extensions) without the generator.

1. Configure at the top level

   ```
   qmake CONFIG+=Release CONFIG+=exclude_generator PythonQt.pro
   ```

2. Build

   Use `nmake` for MSVC (Visual Studio; make sure to have the environment variables set for Visual Studio beforehand). Otherwise, use `make`.

> The build will fail early if wrappers are missing from `../generated_cpp`
> or the path specified via `PYTHONQT_GENERATED_PATH`.

After all these steps, you should now have a fully working PythonQt runtime and Qt bindings for your Python/Qt installation 🎉.

## MinGW

It is possible to build PythonQt with MinGW on Windows instead of using MSVC.
