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

16180 diff mbox series

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@ideasonboard.com>
Reviewed-by: Laurent Pinchart <laurent.pinchart@ideasonboard.com>
---
 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

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@ideasonboard.com>
> Reviewed-by: Laurent Pinchart <laurent.pinchart@ideasonboard.com>

Thanks, it's a good introduction

Reviewed-by: Jacopo Mondi <jacopo@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
>

Hi 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@ideasonboard.com>
> Reviewed-by: Laurent Pinchart <laurent.pinchart@ideasonboard.com>
> ---
>  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.

Can I change this to

.. warning:
    The bindings are under work, and the API will change.

? I'll then push the patch.

> +
> +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.

On 08/06/2022 16:39, Laurent Pinchart wrote:
> Hi 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@ideasonboard.com>
>> Reviewed-by: Laurent Pinchart <laurent.pinchart@ideasonboard.com>
>> ---
>>   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.
> 
> Can I change this to
> 
> .. warning:
>      The bindings are under work, and the API will change.
> 
> ? I'll then push the patch.

Sure. Thanks!

  Tomi