Documentation: Add python-bindings.rst

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>
Reviewed-by: Jacopo Mondi <jacopo@jmondi.org>
Signed-off-by: Laurent Pinchart <laurent.pinchart@ideasonboard.com>

3 files changed, 72 insertions, 0 deletions

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..bac5cd34
--- /dev/null
+++ b/Documentation/python-bindings.rst
@@ -0,0 +1,70 @@
+.. 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.