[libcamera-devel] [PATCH v5 1/4] Documentation: Add python-bindings.rst

[Jacopo Mondi]

Ho Tomi,

On Wed, Jun 08, 2022 at 10:24:15AM +0300, Tomi Valkeinen wrote:
> Add a basic doc for the Python bindings. While not really proper
> documentation yet, the file and the examples should give enough guidance
> for users who are somewhat familiar with libcamera.
>
> Signed-off-by: Tomi Valkeinen <tomi.valkeinen at ideasonboard.com>
> Reviewed-by: Laurent Pinchart <laurent.pinchart at ideasonboard.com>

Thanks, it's a good introduction

Reviewed-by: Jacopo Mondi <jacopo at jmondi.org>

> ---
>  Documentation/index.rst           |  1 +
>  Documentation/meson.build         |  1 +
>  Documentation/python-bindings.rst | 69 +++++++++++++++++++++++++++++++
>  3 files changed, 71 insertions(+)
>  create mode 100644 Documentation/python-bindings.rst
>
> diff --git a/Documentation/index.rst b/Documentation/index.rst
> index 0ee10044..43d8b017 100644
> --- a/Documentation/index.rst
> +++ b/Documentation/index.rst
> @@ -22,3 +22,4 @@
>     Environment variables <environment_variables>
>     Sensor driver requirements <sensor_driver_requirements>
>     Lens driver requirements <lens_driver_requirements>
> +   Python Bindings <python-bindings>
> diff --git a/Documentation/meson.build b/Documentation/meson.build
> index 8e2eacc6..7695bcb1 100644
> --- a/Documentation/meson.build
> +++ b/Documentation/meson.build
> @@ -67,6 +67,7 @@ if sphinx.found()
>          'guides/tracing.rst',
>          'index.rst',
>          'lens_driver_requirements.rst',
> +        'python-bindings.rst',
>          'sensor_driver_requirements.rst',
>         '../README.rst',
>      ]
> diff --git a/Documentation/python-bindings.rst b/Documentation/python-bindings.rst
> new file mode 100644
> index 00000000..d59935ae
> --- /dev/null
> +++ b/Documentation/python-bindings.rst
> @@ -0,0 +1,69 @@
> +.. SPDX-License-Identifier: CC-BY-SA-4.0
> +
> +.. _python-bindings:
> +
> +Python Bindings for libcamera
> +=============================
> +
> +*WARNING* The bindings are under work, and the API will change.
> +
> +Differences to the C++ API
> +--------------------------
> +
> +As a rule of thumb the bindings try to follow the C++ API when possible. This
> +chapter lists the differences.
> +
> +Mostly these differences fall under two categories:
> +
> +1. Differences caused by the inherent differences between C++ and Python.
> +These differences are usually caused by the use of threads or differences in
> +C++ vs Python memory management.
> +
> +2. Differences caused by the code being work-in-progress. It's not always
> +trivial to create a binding in a satisfying way, and the current bindings
> +contain simplified versions of the C++ API just to get forward. These
> +differences are expected to eventually go away.
> +
> +Coding Style
> +------------
> +
> +The C++ code for the bindings follows the libcamera coding style as much as
> +possible. Note that the indentation does not quite follow the clang-format
> +style, as clang-format makes a mess of the style used.
> +
> +The API visible to the Python side follows the Python style as much as possible.
> +
> +This means that e.g. ``Camera::generateConfiguration`` maps to
> +``Camera.generate_configuration``.
> +
> +CameraManager
> +-------------
> +
> +The Python API provides a singleton CameraManager via ``CameraManager.singleton()``.
> +There is no need to start or stop the CameraManager.
> +
> +Handling Completed Requests
> +---------------------------
> +
> +The Python bindings do not expose the ``Camera::requestCompleted`` signal
> +directly as the signal is invoked from another thread and it has real-time
> +constraints. Instead the bindings queue the completed requests internally and
> +use an eventfd to inform the user that there are completed requests.
> +
> +The user can wait on the eventfd, and upon getting an event, use
> +``CameraManager.get_ready_requests()`` to clear the eventfd event and to get
> +the completed requests.
> +
> +Controls & Properties
> +---------------------
> +
> +The classes related to controls and properties are rather complex to implement
> +directly in the Python bindings. There are some simplifications in the Python
> +bindings:
> +
> +- There is no ControlValue class. Python objects are automatically converted
> +  to ControlValues and vice versa.
> +- There is no ControlList class. A Python dict with ControlId keys and Python
> +  object values is used instead.
> +- There is no ControlInfoMap class. A Python dict with ControlId keys and
> +  ControlInfo values is used instead.
> --
> 2.34.1
>